reserve command reference

6 min readStableIntermediate

Every subcommand and flag reserve accepts. Scenario-based usage lives in the guides linked throughout; this page is the scannable, complete list.

Root invocation

Bash

reserve [NAME]...

Checks one or more names. A name carrying a dot is checked exactly as typed. -h/--help and -V/--version work everywhere, including after a subcommand name. reserve help is not a subcommand; use --help. Subcommand names can't be abbreviated (reserve ext doesn't resolve to reserve extensions).

--names-frompath

Read names from a file, one per line, or - for standard input. Commas also separate, # starts a comment, and blank lines are skipped.

Subcommands

groupssubcommand

List the extension groups you can pick from.

-f, --familyindustry | region | popularity | curated

Show only one family.

--jsonboolean

CONSOLE

$ reserve groups --family region
 
south-asia       bangladesh, india, pakistan, sri lanka, ...
southeast-asia   singapore, thailand, vietnam, ...
east-asia        japan, south korea, china, ...
europe           germany, united kingdom, france, ...

extensionssubcommand

Browse and search the extension catalog without checking anything. Accepts every flag under Choosing extensions and Ordering and paging below, plus its own --json.

CONSOLE

$ reserve extensions --group south-asia --json
 
{"query":{"group":["south-asia"]},"page":1,"pageCount":1,"total":4,"extensions":[
  {"extension":"bd","rank":89,"kind":"country","industries":["business","tech"]},
  {"extension":"in","rank":12,"kind":"country","industries":["business","tech","shop"]}
]}

config showsubcommand

Print every resolved setting and where each value came from (flag, environment, or built-in default). Takes --json.

CONSOLE

$ RESERVE_TIMEOUT=45 reserve config show
 
concurrency:   24        built-in default
timeout:       45        environment (RESERVE_TIMEOUT)
width:         120       built-in default
source:        auto      built-in default
cache_ttl:     not cached  built-in default

config pathsubcommand

Print the config, cache, and data paths this machine uses. Takes --json. (config on its own isn't runnable: it needs show or path.)

CONSOLE

$ reserve config path
 
config: ~/.config/devops.bd/reserve
cache:  ~/.cache/devops.bd/reserve
data:   ~/.local/share/devops.bd/reserve

doctorsubcommand

Print what the tool sees: version, catalog, terminal, network, and paths. Takes --json.

See Install reserve for a full sample reserve doctor transcript.

completionssubcommand

reserve completions <SHELL> writes a completion script to stdout. Accepts bash, elvish, fish, powershell, zsh. No --json.

Bash

reserve completions zsh > "${fpath[1]}/_reserve"

mansubcommand

reserve man [COMMAND]... writes the manual page to stdout, or one subcommand's page, a nested one named in full, as in config show. No --json.

Bash

reserve man               # the whole manual, piped to a pager if you like:
reserve man | less
reserve man config show   # just the config show page

servesubcommand

Run an HTTP endpoint and a Model Context Protocol server on one address, until interrupted. Binds to 127.0.0.1 on port 4243 by default, so a fresh install exposes nothing to the network. See reserve serve and the MCP endpoint for the full HTTP and MCP surface.

--bindaddressDefault: 127.0.0.1

Address to bind. Validated as an address when the flag is parsed.

--portintegerDefault: 4243

Port to bind.

Bash

reserve serve                        # loopback only, port 4243
reserve serve --bind 0.0.0.0 --port 8080

Every subcommand that prints data offers its own --json, and a root-level --json (before the subcommand name) reaches the same commands.

Choosing extensions

-g, --groupstring[]

Group to pull extensions from. Repeat the flag or comma-separate several values.

-t, --tldstring[]

Extension to check, named directly, such as com or co.uk.

-x, --excludestring[]

Extension to leave out of whatever else was chosen.

-s, --searchtext

Keep only extensions matching this text, by name, country, or industry.

--industrystring[]

Keep only extensions marketed for this industry.

--regionstring[]

Keep only country extensions from this region.

--cctldboolean

Keep only two-letter country extensions.

--depthany | second | thirdDefault: any

Keep plain extensions such as com (second), multi-label ones such as co.uk (third), or both (any, the default).

--lengthspec

Keep extensions by length: 2, -3, 4-, or 2-4.

--tlds-frompath

Read extensions from a file, or - for standard input, in the same shape as a name list.

--include-restrictedboolean

Include zones the public cannot register under.

Ordering and paging

--sortname | popularity | lengthDefault: popularity

name sorts alphabetically, popularity by how widely the extension is used, length by character count.

--orderasc | desc

Which way to order. Defaults to what reads best for the chosen field.

--pageinteger ≥ 1Default: 1

Which page to show. When checking a name, this decides which extensions are contacted, not just what's printed.

--page-sizeinteger ≥ 1

Rows per page. Defaults to what the terminal fits when browsing, and to 25 extensions when checking a name.

--all-pagesboolean

Print every page at once instead of stopping at the first. Can't be combined with --page.

Pacing

-c, --concurrencyinteger, 1-1024

Lookups in flight across the whole run. Reads RESERVE_CONCURRENCY when the flag is absent.

--per-registryinteger, 1-1024

Lookups in flight against any one registry.

--rateinteger, 1-10000

Sustained requests per second against any one registry.

--timeoutinteger, 1-3600

Seconds to wait on any single request. Reads RESERVE_TIMEOUT.

--cautiousboolean

Go slowly, for a very large sweep or a strict registry. This is a ceiling: --rate, --per-registry, and --concurrency can lower it, never raise it.

--sourceauto | registry | text | dnsDefault: auto

Where answers come from. registry asks the structured service only; text uses the older port-43 protocol only; dns can prove a name is taken, never that one is free.

--refreshboolean

Re-download the registry server list instead of using the cached copy.

--registry-serverspath

Use your own structured-service list, in the published bootstrap shape.

--text-serverspath

Use your own text-service table, in the same shape as the built-in one.

--servers-replaceboolean

Let a supplied server list replace the built-in one instead of overlaying it.

--no-referralboolean

Never ask IANA who serves an extension.

--cache-ttlseconds

Reuse a taken or unknown answer from this many seconds ago instead of asking again. Never applies to an available name.

Output

--jsonboolean

Print machine-readable JSON instead of the table.

--dry-runboolean

Show what the run would do and write nothing, without asking any registry.

-a, --available-onlyboolean

Show only the names nobody holds, and save only those.

--detailsboolean

Show registrar, dates, status, nameservers, and abuse contact.

--responderboolean

Show which registry server answered.

--dnsboolean

Show the DNS records found for each name.

--where-to-buyboolean

For an available name, show the registry and where to buy it.

--explainboolean

Show which source answered and why, in the order they were tried.

--rawboolean

Show the server's own unprocessed response for the answer that decided each name.

--fullboolean

Turn on every extra section at once. Can't be combined with --details, --responder, --dns, --where-to-buy, --explain, or --raw individually.

-o, --outpath

Write the results into this directory. Can't be combined with --save.

--saveboolean

Write result files into the current directory. Can't be combined with --out.

--appendboolean

Merge into the files already there instead of refusing. Needs --save or --out.

--save-jsonboolean

Write the result files as JSON while the screen keeps its table. Needs --save or --out.

Global settings

These five flags work before or after the subcommand name.

--colorauto | always | neverDefault: auto

never also removes the progress line unless --progress asks for it.

--progressauto | always | neverDefault: auto

When to show the progress line, apart from what colour and -q decide.

--widthinteger, 1-10000

Lay the table out for this many columns instead of the terminal's width. Reads RESERVE_WIDTH.

--no-inputboolean

Never prompt and never open the picker. Reads RESERVE_NO_INPUT.

--interactiveboolean

Open the picker even when extensions were given on the command line.

-v, --verbosecounted flag

Turns on tracing; repeat to say more.

-q, --quietcounted flag

Drops the progress line and the start and finish notes. Can't be combined with --verbose.

Rules the parser enforces

Only one list can be read from standard input: --names-from - and --tlds-from - can't both be given.
--no-input and --interactive can't be typed together as flags. An exported RESERVE_NO_INPUT, though, is a standing preference and loses to a typed --interactive for that run.
--out rejects an empty value, and rejects a leading ~ (write the path in full: a shell already expands ~ before reserve sees it). On Windows it also rejects a reserved device name like con or nul, or a segment ending in a dot or space.
--group, --tld, --exclude, --industry, and --region all accept either a comma-separated list or a repeated flag.

Typed rows

On the interactive picker's settings screen, a typed row takes the usual line-editing keys: Left, Right, Home, End, Delete, Backspace, Ctrl-A, Ctrl-E, Ctrl-U, Ctrl-K, Ctrl-W. See Use the interactive picker.

reserve command reference

Root invocation

Subcommands

Choosing extensions

Ordering and paging

Pacing

Output

Global settings

Rules the parser enforces

Typed rows

Check whether a domain name is available

Output and exit codes

Environment variables

reserve serve and the MCP endpoint

reserve command reference

Root invocation

Subcommands

Choosing extensions

Ordering and paging

Pacing

Output

Global settings

Rules the parser enforces

Typed rows

Related pages

Check whether a domain name is available

Output and exit codes

Environment variables

reserve serve and the MCP endpoint