# Command Tool Standard

Defines command contracts, output streams, exit codes, and tool safety.

Catalog: active · v0.2.1 · reviewed 2026-09-23

Source maturity: candidate · Explanation reviewed 2026-10-01

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

[Public page](https://aptlantis.net/city-hall/cts)

<a id="purpose-and-applicability"></a>

## 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.

<a id="how-it-works"></a>

## 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.

<a id="in-practice"></a>

## 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.

### Success envelope

illustrative · teaching example, not a verification result

Canonical teaching fixture: machine stdout result, with no progress text.

Source: `CTS/examples/fixtures/ok-envelope.json`

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

[Inspect Success envelope](/city-hall/standards/cts/example-1.json)

### Error envelope

illustrative · teaching example, not a verification result

Canonical teaching fixture: stable error code/message and no result payload.

Source: `CTS/examples/fixtures/error-envelope.json`

```json
{
  "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"
    }
  ]
}
```

[Inspect Error envelope](/city-hall/standards/cts/example-2.json)

### Command contract slice

illustrative · teaching example, not a verification result

Illustrative command-specific exit mapping; the envelope alone does not assign exit codes.

Source: `CTS/Command Tool Standard.md`

```text
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
```

[Inspect Command contract slice](/city-hall/standards/cts/example-3.txt)

<a id="adopt-one-part"></a>

## 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.

<a id="sources-and-limits"></a>

## 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`

[Reviewed manifest facts](/city-hall/components/cts.md)

## Related responsibilities

- [Library Development Standard](/city-hall/lds): Owns code consumed by other code.
- [Service and Infrastructure Standard](/city-hall/sis): Owns long-running service behavior; CTS can govern its lifecycle CLI.
- [APTlantis Release Hashing Standard](/city-hall/arhs): Owns hashes for distributed command artifacts.