CLI Schema is a language-agnostic specification for machine-readable CLI descriptions — structured enough for AI agents, expressive enough for docs, precise enough for shell completions.
// why cli-schema
Describe your CLI once in a structured, open format — then let every tool in the ecosystem consume it.
Structured enough for LLMs and autonomous agents to reason about your CLI without training data.
Generate beautiful, accurate reference docs directly from the schema. No more manual maintenance.
Power tab completions for bash, zsh, fish, and PowerShell from a single source of truth.
Works with any CLI regardless of implementation language — Go, Rust, Python, Ruby, or anything else.
JSON Schema meta-schema included. Validate any cli-schema document against the spec instantly.
Public domain dedication. No licensing concerns. Use it in any project, commercial or otherwise.
// how it works
Two ways to expose a schema. One consistent format to consume it.
Add a __schema subcommand to your CLI that outputs a valid cli-schema JSON document. Discovery is instant.
Place a mytool.cli-schema.json file next to your binary. No runtime changes required.
Any tool that understands cli-schema can now generate docs, completions, type-safe wrappers, or agent interfaces — automatically.
{
"name": "gh",
"version": "2.40.0",
"commands": [
{
"name": "pr",
"description": "Manage pull requests",
"commands": [
{
"name": "create",
"flags": [
{
"name": "title",
"short": "t",
"type": "string",
"required": true
}
]
}
]
}
]
}// use cases
cli-schema is infrastructure. Build anything on top of it.
Give agents a structured view of any CLI without fine-tuning. cli-schema maps directly to function calling schemas.
Power autocompletion, inline docs, and flag validation inside editors and devtools.
Always-accurate CLI reference pages, man pages, and --help output generated straight from the schema.
One schema, completions for every shell. bash, zsh, fish, PowerShell — generated without manual scripts.
The specification is open, CC0 licensed, and ready for feedback.
Contributions and implementations welcome.