Agent-Readiness Checklist

This content was generated with the assistance of AI and should be verified against the official documentation of each tool and framework before being relied on in production.

This section’s bibliography lists the reference material consulted while preparing these pages.

This checklist was compiled on 2026-09-30 from the concept pages of this sub-section, which in turn derive from clig.dev and from two engineering blogs, Arcjet’s Designing a CLI for AI agents and Speakeasy’s post on engineering an agent-friendly CLI. Both are engineering blogs, that is, practitioners' accounts of what worked for their products, not standards; where they and clig.dev disagree (secrets in environment variables), the item below says so and the linked page presents the trade-off. The examples name the sub-section’s fictional docsctl, and the list is a review aid, not a certificate: a tool can tick every box and still be hard to use, which is what agent evals are for.

A smoke test that checks a few checklist items against the installed binary
docsctl search "xref" --json 2>/dev/null | jq -e '.schemaVersion == 1' > /dev/null   # stdout is pure JSON
docsctl no-such-command > /dev/null 2>&1; test $? -eq 2                                # usage errors exit 2
docsctl publish --component irurueta-algebra --json < /dev/null > /dev/null 2>&1; test $? -ne 0  # no prompt, no silent publish

Use it as a pull-request template for a new command, or as an audit of an existing tool. Each item is a claim you can verify with a command, a test or a read of the code; the link on the right names the page that explains why and how.

Output

  • Every command accepts --json (or --format json|jsonl|text), and stdout in JSON mode is one document, or one object per line for jsonl, with nothing else on it. Machine-Readable Output

  • Every JSON output carries a schemaVersion, and the schema evolves additively; a published JSON Schema exists for each output. Machine-Readable Output

  • Output is deterministic: sorted keys, stable ordering of arrays, no timestamps or absolute paths unless asked for. Machine-Readable Output

  • --fields and --jq project the output, so an agent can ask for only what it needs. Machine-Readable Output

  • Lists have --limit and --cursor with small defaults, and say when they truncated (truncated, nextCursor). Agent Ergonomics

Interactivity

  • Nothing prompts when stdin is not a terminal, and a prompt never blocks in CI (CI, --no-input, DOCSCTL_NO_INPUT). TTY, Colour & Interactivity

  • --no-input and --yes exist, and a refusal to prompt fails fast with a message that names the bypass flag. TTY, Colour & Interactivity

  • Colour, spinners and progress bars appear only on a terminal, and NO_COLOR, TERM=dumb and --no-color are honoured. TTY, Colour & Interactivity

  • A TUI, if there is one, is a separate command, and every function has a non-interactive equivalent. TUIs vs. CLIs

Safety

  • Commands are read-only unless they say otherwise, and each command’s safety (read-only, destructive, idempotent) is recorded in its metadata. Safety & Idempotency

  • Every mutating command has --dry-run that emits a JSON plan and changes nothing. Safety & Idempotency

  • A destructive action requires an explicit flag, or returns a distinct "confirmation required" exit code together with the exact command that confirms it, rather than prompting. Safety & Idempotency

  • Create-or-update commands are idempotent, and repeating a command with the same idempotency key is safe. Safety & Idempotency

  • Operands are validated locally before any remote call, -- ends option parsing, and no subcommand or flag is resolved by ambiguous prefix. CLI Design Fundamentals, Security

Errors

  • In JSON mode a failure writes one structured error to stderr, with a stable code, the exitCode, a message, a hint that says how to fix it, and retryable. Agent Ergonomics

  • Exit codes are a documented taxonomy: 0 for success (including no-ops and dry runs), a usage code, and distinct codes for validation, not found, confirmation required, retryable and auth failures. Streams & Exit Codes

  • The taxonomy treats sysexits as vocabulary only (the FreeBSD manual marks it deprecated), respects 126, 127 and 128+N, and keeps custom codes clear of them. Streams & Exit Codes

  • The same failure gives the same code in every subcommand, and a test produces each code. Testing CLIs

Streams

  • Data goes to stdout, and everything else (logs, progress, prompts, diagnostics) to stderr, so output can be piped and parsed. Streams & Exit Codes

  • --quiet, --verbose and --log-format json control the diagnostics, and none of them changes what stdout contains. Streams & Exit Codes

  • Output that may be large is capped or paginated, and says so, so it cannot flood an agent’s context. Agent Ergonomics

Timeouts

  • Every network or long operation has a --timeout with a default, and a timeout is a retryable failure with its own exit code. Agent Ergonomics

  • SIGINT and SIGTERM are handled: the tool cleans up and exits with 130 or 143. Streams & Exit Codes

  • Start-up is fast enough to call in a loop (lazy imports, native image where it helps), and it has a measured baseline. Agent Ergonomics, Testing CLIs

Discoverability

  • --help states when to use each command and shows at least one real example, and --version works. Self-Describing Help

  • A machine-readable command tree (schema or --help --json) lists commands, flags, output schemas, exit codes and safety metadata, in a form that maps directly to MCP tool schemas. Self-Describing Help, Wrapping a CLI as an MCP Server

  • Shell completion is generated, not hand-written, and man pages and reference docs come from the same command tree. Documenting CLIs

  • An agent skill or short guide ships with the tool, covers the common tasks and is tested like any other skill. Self-Describing Help

Auth

  • Credentials come from a token file or credential store, with an environment variable (DOCSCTL_TOKEN) for CI, and no browser flow is required to authenticate headlessly (login --token-stdin). Configuration & Auth

  • The environment-variable-versus-file question is a deliberate decision: clig.dev warns against secrets in environment variables, while agent-oriented posts such as Arcjet’s recommend them for headless use. The page presents this as a trade-off, so record which side you chose and why. Configuration & Auth

  • Tokens are never printed, logged or echoed in error envelopes, and an auth failure names the fix (docsctl login or $DOCSCTL_TOKEN). Configuration & Auth, Security

  • Credentials are least-privilege, and a wrapper never exposes login or logout to the model. Security

Config precedence

  • Precedence is flags, then environment, then project, then user (XDG), then system, and --verbose logs, on stderr, which files were read and which layer supplied each value. Configuration & Auth

  • Config lives in the XDG base directories (or the macOS and Windows equivalents), and a project file is found by walking up from the working directory. Configuration & Auth

  • Every setting has a flag, an environment variable (DOCSCTL_*) and a config key with the same name and meaning. CLI Design Fundamentals

Around the tool

These items are not about a single command, but they decide whether the rest holds up in practice.

  • The tool installs at an exact version through the channels its users have, and its releases carry checksums and signatures. Packaging & Distribution

  • The contract is tested on the packaged artifact, and an agent eval covers the most common tasks. Testing CLIs

  • The trade-offs of exposing the tool as a CLI, an MCP server or both were considered. CLI vs. MCP

  • Wrappers never build shell strings, and the tool’s own code never does either. Security, Wrapping as an Agent Tool

References