Command Tool Standard

Purpose and applicability

A script breaks when a command prints progress into JSON or changes an exit code unexpectedly. CTS makes the command boundary a documented contract.

Commands invoked by people, scripts or automation pipelines, regardless of implementation language.

How it works

Declare inputs, flags, stable fields, stdout, stderr and exit codes per public command. Human output is normally the default; structured output is explicitly requested. Diagnostics belong on stderr, and destructive commands declare preview, confirmation and recovery behavior.

Outputs include help/version text, command contracts, an exit-code table, structured-output schema, success/error fixtures and compatibility notes. The envelope constrains status/tool/version; command-specific data has its own stable contract.

In practice

The two canonical fixture envelopes show a result object and a null error payload. JSON status is not an operating-system exit code; the command contract must say how those correlate.

{
  "status": "ok",
  "tool": "example-command",
  "version": "1.0.0",
  "data": {
    "message": "Completed successfully.",
    "items_count": 1
  },
  "warnings": [],
  "errors": []
}

{
  "status": "error",
  "tool": "example-command",
  "version": "1.0.0",
  "data": null,
  "warnings": [],
  "errors": [
    {
      "code": "input-missing",
      "message": "Required input path was not found.",
      "path": "input.txt"
    }
  ]
}

Invocation: example-command INPUT --json
Input: one required input file
stdout: one JSON envelope, no progress text
stderr: diagnostics
exit 0: completed result
exit 3: required input missing (illustrative mapping)
stability: experimental until behavior is checked
mutation: none for this example

Adopt one part

Start with a bounded surface or record. Complete the relevant adopter checks before extending the claim.

1. Choose one command and document invocation, inputs, streams and exit codes.
2. Add separate human and machine examples; keep diagnostics out of machine stdout.
3. Validate fixtures and real invocations, including failure and preview behavior, before scripts depend on a stability claim.

Sources and limits

These fixtures are illustrative; neither was produced by a running command here. CTS governs command behavior, not a library API or a continuously running service. Release hashing and archive signatures have separate owners.

These are reviewed public explanations, not the normative specifications. Suite references are relative to the canonical collection; site/ references identify committed website sources and webserver/ references identify serving configuration. Illustrative examples demonstrate record shape; they do not establish compliance. Suite checks and adopter validation are separate.

• CTS/CTS.manifest.toml
• CTS/Adoption-Guide.md
• CTS/Validation-Checklist.md
• CTS/Command Tool Standard.md
• CTS/CommandOutput.schema.json
• CTS/examples/fixtures/ok-envelope.json
• CTS/examples/fixtures/error-envelope.json