Skip to content
Athena Docs

Schema dumps

The CLI exposes its full surface as JSON so AI agents can discover what’s available without parsing --help text.

Whole-CLI dump

Terminal window
athena --schema

Returns one big JSON document with every subcommand, its arguments, their types, defaults, required-ness, and the exit-code table.

Shape (truncated):

{
  "name": "athena",
  "version": "1.x.y",
  "commands": {
    "login":         { "args": [...], "description": "..." },
    "whoami":        { ... },
    "logout":        { ... },
    "workspace":     { "subcommands": { "list": {...}, "use": {...}, "current": {...}, "clear": {...} } },
    "agent":         { "subcommands": { "list": {...}, "get": {...}, "create": {...}, "delete": {...}, "run": {...}, "draft": {...}, ... } },
    "group":         { "subcommands": { "list": {...}, "config": { "subcommands": { ... } }, ... } }
  },
  "exit_codes": [
    { "code": 0, "name": "Success", "description": "..." },
    ...
  ],
  "error_envelope": { "$ref": "#/definitions/ErrorResponse" }
}

The error_envelope ref documents the wire shape of every error so an agent knows what to expect on stderr.

Per-command dump

Any subcommand accepts --schema to dump just its own slice:

Terminal window
athena agent run --schema
{
  "name": "run",
  "description": "Execute an agent. Default mode streams NDJSON events...",
  "args": [
    { "name": "slug", "type": "string", "required": true, "positional": true, "description": "Agent slug or ID" },
    { "name": "input", "type": "string", "required": true, "description": "Path to JSON file, '-' for stdin, or inline JSON" },
    { "name": "final-only", "type": "boolean", "default": false, "description": "Wait for the terminal event..." },
    { "name": "idempotency-key", "type": "string", "required": false, "description": "..." }
  ],
  "exit_codes_used": [0, 2, 3, 7, 8, 9, 11, 13]
}

exit_codes_used lists the subset of exit codes this command can produce. Useful for narrowing your error-handling table.

Using schemas from an AI agent

A typical agent loop:

1. agent runs `athena --schema | jq .` once at session start
2. caches the result
3. when user says "run my email-drafter agent", agent looks up
   `commands.agent.subcommands.run.args` to figure out the invocation
4. executes the command
5. parses stdout / stderr per the documented shapes

Versioning

The schema dump is keyed by the CLI version (athena --version). Newer versions may add commands, args, or exit codes; removing or renaming any of those is a major-version change. Pin to a specific binary version in CI if you need stricter compatibility guarantees.