These requirements are formalized as the CLI Agent Spec.
agentyper is the reference Python implementation of that specification.
When Large Language Models (LLMs) or AI Agents interact with command-line interfaces, they behave very differently than human operators. To be "Agent-Ready," a CLI tool must satisfy these fundamental requirements:
Agents cannot read a man page or --help text the way a human does and reliably infer parameter constraints. They require a strict, machine-readable JSON Schema (e.g., OpenAPI format) that perfectly describes the tool inputs (types, defaults, enums), which they can feed directly into their internal Function Calling / Tool Calling loops.
Standard terminal environments use interactive prompts like [y/N] or Please enter password:. An agent attached via subprocess or stdio will hang indefinitely waiting for standard input. True agent CLIs must provide deterministic ways to bypass interactive prompts programmatically (e.g., --yes).
Terminals are often designed for human eyes, utilizing ANSI color codes, progress bars, and ASCII tables. Agents hallucinate when trying to parse this text. They need outputs to be strictly structured (JSON/CSV) so they can deterministically parse the result.
When a human supplies --count "foo", standard CLIs throw a string exception: Error: "foo" is not a valid integer. An agent needs a structured JSON error indicating exactly which parameter failed (e.g., {"loc": ["count"], "msg": "Input should be a valid integer"}) so it can auto-correct its payload without hallucination.
Agents rely on exit codes to branch logic.
- A
0means success. - A
1(Validation Error) tells the agent: "You made a mistake, fix your argument and retry." - A
2(System Error) tells the agent: "Something is broken externally, abort and report to the user."
Agents should be able to control the level of detail they receive. While binary --debug flags are common, stacked verbosity flags (e.g., -v, -vv) are preferred for better scalability and to avoid flag contention with other domain-specific options.
Read more about CLI Verbosity Design Patterns (-vv vs -d).