CLI & agents guide

Install and log in

The greybull CLI ships on npm and needs Node 20 or newer. Run it with npx or install it globally. greybull login opens your browser and stores a scoped API key in ~/.config/greybull/config.json.

npx greybull login
npx greybull whoami

Every API key is scoped: dns:read, dns:write, domains:read, domains:write, compute:read and compute:write. The login consent screen lets you pick the scopes for the key it stores; you can also create and manage keys under API settings in the dash.

Everyday commands

# Zones and records
greybull dns zones
greybull dns list example.nl --type TXT
greybull dns add example.nl A www 203.0.113.20
greybull dns update example.nl A www 203.0.113.20 203.0.113.21
greybull dns delete example.nl TXT _acme-challenge '"token123"'

# Whole-zone editing in your $EDITOR, pdnsutil-style
greybull dns edit example.nl

# Delegation and DNSSEC health (parent DS, DNSKEY, lame NS)
greybull dns check example.nl

# Record templates for zones you set up over and over
greybull dns template apply default-mail example.nl

# Domains: check, register, transfer in
greybull domains list
greybull domains check acme --tlds nl,com,eu
greybull domains register acme.nl
greybull domains transfer acme.nl

# Compute: list instances, SSH or serial console by name
greybull compute list
greybull ssh web-01
greybull console web-01

Record operations are sibling-safe: they touch only the record you name, identified by name, type and exact content. Commands that spend money (domains register, domains transfer) always show the live yearly price and ask for confirmation first — they never proceed implicitly.

Scripting and CI

The CLI is built to behave in pipelines:

Non-interactive auth. Set GREYBULL_API_KEY=ck_... and skip login entirely — nothing is written to disk. Ideal for CI runners.
--json switches output from tables to raw JSON, including structured results for mutations.
--yes auto-accepts confirmation prompts; without it, confirmations abort safely when stdin is not a terminal.
File-based zone editing. dns edit --file zone.db (or --file - for stdin) applies a full zone without an editor; add --dry-run to see the diff without applying.
Clean streams. Results go to stdout; warnings and errors go to stderr.
Distinct exit codes. 0 success, 1 unexpected error, 2 usage or validation, 3 authentication, 4 not found, 5 network or server error.
Color handling. ANSI colors switch off automatically when output is piped, or when NO_COLOR is set.

# Fetch all A records as JSON in CI
GREYBULL_API_KEY=$GREYBULL_API_KEY \
  greybull dns list example.nl --type A --json | jq '.[].content'

# Review a zone change, then apply it
greybull dns edit example.nl --file zone.db --dry-run
greybull dns edit example.nl --file zone.db

Connect an AI agent over MCP

Greybull speaks the Model Context Protocol. The dash hosts an MCP server (streamable HTTP) that gives agents like Claude scoped access to your account — the same API keys, the same permission model.

claude mcp add --transport http greybull \
  https://dash.greybull.cloud/api/mcp/mcp \
  --header "X-API-Key: ck_..."

Any MCP client works: authenticate with Authorization: Bearer ck_... or an X-API-Key header. The server exposes eight tools, each guarded by the key's scopes:

list_zones, list_dns_records — requires dns:read
create_dns_record, update_dns_record, delete_dns_record — requires dns:write
list_domains, get_domain, check_domain_availability — requires domains:read

Give your agent a key with only the scopes it needs. A read-only key (dns:read, domains:read) lets an agent audit your zones and check domain availability without being able to change anything.

Or the plain REST API

Everything the CLI does goes through the public API, which you can call directly. See the per-product guides for endpoints: Hosted DNS, Compute and Container Hosting.

curl "https://dash.greybull.cloud/api/v1/domains/search?q=acme&tlds=nl,com" \
  -H "X-API-Key: $API_KEY"