Skip to content

cli-contract.mdx

Latest commit

 

History

History
160 lines (122 loc) · 7.01 KB

cli-contract.mdx

File metadata and controls

160 lines (122 loc) · 7.01 KB
Raw
title CLI contract
description Stable command parsing, exit codes, JSON success envelopes, and JSON error behavior for the current CLI.

This document describes the stable CLI contract for agentplane command parsing, success output, and error behavior.

Scope: global flags, parsing rules, exit codes, JSON success envelopes, and JSON error output.

1) Invocation model

agentplane [global-flags] <command> [args/options]

Supported global flags:

  • --root <path>: resolve project from an explicit root.
  • --json-errors: print machine-readable errors.
  • --allow-network: allow optional network actions that would otherwise be skipped by approval policy.
  • --no-update-check: skip update check call.
  • --help, -h, --version, -v.

1.1 Global flag scoping (spec-driven CLI)

Scoped global flags (--json-errors, --allow-network) are recognized only before the command id. For example:

  • agentplane --json-errors task list ... enables JSON error output.
  • agentplane help --json emits JSON help output and does not enable JSON error mode.
  • agentplane task list --json-errors treats --json-errors as a command flag candidate, not global mode.

1.2 Node runtime support

The agentplane CLI requires Node.js 24 or newer. The separately published library packages retain their wider runtime contracts: @agentplaneorg/core requires Node.js 20.5.0 or newer, and @agentplaneorg/recipes requires Node.js 20 or newer.

CI builds and packs both library artifacts on Node.js 24, then installs and exercises every public export from those tarballs on both the declared minimum runtime and Node.js 24. Package manifests remain the source of truth for the engine ranges.

2) Exit codes

The CLI uses stable exit codes for success and every classified failure family. The exhaustive code list and error-code mapping are generated from runtime metadata in the CLI reference. Do not maintain a second handwritten mapping in documentation.

3) --json-errors format

When --json-errors is provided and a command fails, the CLI prints one JSON object to stdout:

{
  "error": {
    "code": "E_USAGE",
    "message": "Missing required argument: --root",
    "context": {
      "command": "init",
      "args": ["--yes"]
    }
  }
}

Rules:

  • JSON errors are written to stdout; human-readable diagnostics go to stderr only when --json-errors is not set.
  • error.code is a stable string enum; the exhaustive enum and exit-code mapping are generated in the CLI reference.
  • context is optional and must not include secrets.
  • State, remediation, next-action, and reason-decoding fields are optional and omitted when unavailable.
  • Field names, nesting, and casing are exact. The generated JSON error envelope reference is canonical.

4) --output json success envelope (agent_json_v1)

When --output json is provided and a command succeeds, the CLI emits one stable envelope to stdout:

{
  "schema_version": 1,
  "mode": "agent_json_v1",
  "command": "config show",
  "ok": true,
  "exit_code": 0,
  "stdout": "{\n  \"workflow_mode\": \"branch_pr\"\n}",
  "stderr": "",
  "data": {
    "workflow_mode": "branch_pr"
  }
}

Rules:

  • The exact top-level key order is stable: schema_version, mode, command, ok, exit_code, stdout, stderr, then optional data.
  • schema_version is currently 1; mode is currently agent_json_v1.
  • command is the canonical command id selected by the dispatcher, for example help, config show, or task list.
  • stdout and stderr preserve the trimmed text output produced by the command.
  • data is included only when stdout is itself valid JSON; when present, it must equal JSON.parse(stdout).
  • Text commands such as task list, task search, and task next therefore omit data and keep only the text in stdout.
  • --output json also enables the same machine-readable failure path as --json-errors; the agent_json_v1 envelope is the success contract, not the error contract.

5) Human output conventions

Human-facing command output should use createCliEmitter() from packages/agentplane/src/cli/output.ts instead of ad-hoc local render helpers.

Conventions:

  • Use line() / lines() for plain text output.
  • Use json() for standalone pretty JSON payloads.
  • Use jsonSection() for labeled pretty JSON blocks such as scenario metadata sections.
  • Use report() for labeled scalar/status blocks.
  • Use success(), info(), and warn() for framed status messages instead of reformatting emoji/status strings locally.
  • Treat low-level render plumbing inside cli/output.ts as internal implementation detail; command modules should depend on the emitter surface, not on helper internals.

6) Command registry and loading

Command definitions are registered in packages/agentplane/src/cli/run-cli/command-catalog.ts. The catalog keeps command specs lightweight and loads command runtime handlers lazily.

This split keeps agentplane help fast and reduces accidental startup cost from heavy imports.

7) Help and startup surfaces

  • agentplane quickstart and agentplane role <ROLE> are generated from packages/agentplane/src/cli/command-guide.ts.
  • The docs-site startup path lives in docs/start/quickstart.mdx.
  • Installed runtime surfaces must stay self-contained and must not require repo-only docs files to exist locally.
  • agentplane role <ROLE> renders one unified surface:
    • installed .agentplane/agents/<ROLE>.json role/profile content when available
  • plus built-in CLI/runtime supplements for that role
  • For unknown role requests, CLI prints known built-in roles and discovered project role ids.

8) Contract boundaries

  • agentplane help --compact is a human output convenience, not a machine schema.
  • agentplane help --json is machine-readable help output.
  • --json-errors is for failed command output only.
  • --output json preserves text output inside stdout; consumers must not assume data exists for text commands.
  • Command descriptions and examples may change, but option names, required flags, error shapes, and exit code mapping are treated as stable contract surface.

9) Source references

  • Parser and global flags:
    • packages/agentplane/src/cli/run-cli.ts
  • Error codes and JSON error envelope metadata:
    • packages/agentplane/src/shared/errors.ts
  • Exit-code metadata and error mapping:
    • packages/agentplane/src/cli/exit-codes.ts
  • Generated runtime and command reference renderer:
    • packages/agentplane/src/cli/spec/docs-render.ts
  • Help/role guide text:
    • packages/agentplane/src/cli/command-guide.ts
  • Startup guide source:
    • packages/agentplane/src/cli/command-guide.ts
  • Command catalog:
    • packages/agentplane/src/cli/run-cli/command-catalog.ts
  • Agent Change Record command group:
    • packages/agentplane/src/commands/acr/acr.command.ts

For command-level help JSON schema details, see CLI help JSON contract.