Command outputs and exit codes

A command can declare what it writes to stdout, the JSON Schema for structured output, and what its exit statuses mean:

cmd "check" {
  flag "--format <FORMAT>" help="Output format"

  output "human" default=#true help="Human-readable report"
  output "json" media_type="application/json" framing="json" help="One report object" {
    schema #"""
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "required": ["passed"],
      "properties": { "passed": { "type": "boolean" } }
    }
    """#
  }
  output "jsonl" framing="jsonl" help="One event per line"
  output "checkstyle" media_type="application/xml" help="Checkstyle report"
  select "--format"

  exit_code 0 "all checks passed"
  exit_code 1 "a check failed"
}

output's first argument is the value a user types. media_type identifies the content using an IANA media type such as application/json or application/xml. framing is the stream contract a consumer reads:

Framing	Meaning
text	Unstructured text; the default
json	One JSON document, read to end of stream
jsonl	One JSON document per line, consumed incrementally

The name, media type, and framing are deliberately separate. XML can use the default text framing because it is one document read to end of stream, while JSON Lines uses jsonl framing because it contains independently consumable records. An output named ndjson can declare framing="jsonl", allowing consumers to treat equivalent formats alike without knowing each CLI's spelling.

An output also accepts help, default=#true, and hide=#true. The media type is optional and is not inferred from either the output name or framing. At most one effective output may be the default. schema is carried verbatim, so it can use any JSON Schema draft and can contain references that another tool resolves.

For a schema kept next to the spec, name its file instead of embedding it:

output "json" framing="json" {
  schema file="report.schema.json"
}

A relative path is resolved from the KDL file containing the declaration, including when that file is included by another spec. Usage loads the file into the same schema field consumers already read and adds it to Spec::sources, so generated output is self-contained and build scripts know to rerun when the JSON file changes. Inline schemas remain useful for specs parsed from strings, where a relative file has no directory to resolve against.

Selecting an output

For a value-taking flag, declare one select on the command:

flag "--format <FORMAT>"
output "human" default=#true
output "json" framing="json"
select "--format"

Usage fills the flag's choices from the output names. Those choices reach validation, completions, generated documentation, Fig, and generated SDK flag types.

For a boolean flag that selects one output, put select on that output:

flag "--json"
output "text" default=#true
output "json" framing="json" select="--json"

Inheritance

Top-level output, select, and exit_code declarations apply CLI-wide. A command can refine an inherited output by redeclaring its name, or remove it with hide=#true. Exit codes fold by number, so a command can refine exit_code 1 "error" without repeating the CLI-wide success and interrupt statuses.

When commands share a global value selector, each command receives choices for its own effective outputs. This prevents one command from advertising formats that only a sibling produces.

flag "--format <FORMAT>" global=#true
exit_code 0 "success"
exit_code 130 "interrupted"

cmd "list" {
  output "text" default=#true
  output "json" framing="json"
  select "--format"
}

Rust derives

Typed Rust declarations use the same vocabulary:

#[derive(usage::Args)]
#[usage(
    output("human", default, help = "Human-readable report"),
    output("json", media_type = "application/json", framing = "json", schema_from = Report),
    output("checkstyle", media_type = "application/xml"),
    exit_code(0, "all checks passed"),
    exit_code(1, "a check failed"),
)]
struct Check {
    #[usage(long, select)]
    format: Option<String>,
}

A schema can come from schema = "…", schema_from = Type using schemars, or schema_fn = path where the function returns a String.

Generated Markdown and manpages document outputs and exit statuses. usage mcp includes them in describe_command, parsing a valid schema into structured JSON and preserving invalid schema text as a string. Generated Python and TypeScript SDKs add parsed JSON methods and streaming JSONL methods while leaving the existing raw exec method unchanged.