CLI Contract Inventory
This inventory captures Holon's current CLI surface as compiled from
src/main.rs and checked against target/debug/holon --help for holon 0.14.1.
It is a stability planning document, not a promise that every listed command is
already stable.
The current implementation keeps the CLI in one Rust binary:
src/main.rs defines the Clap command tree and most CLI handlers.docs/website/reference/cli.md is the user-facing command reference.docs/website/reference/cli-stability-policy.md documents the
user-facing support policy for stable, experimental, internal, and
deprecated CLI surfaces.docs/website/reference/configuration.md documents config files,
credential-related environment variables, and diagnostics.
Stability levels
See CLI stability policy for the user-facing
support policy behind these labels.
| Level | Meaning | Change policy |
|---|
stable | Intended public surface that users and scripts may reasonably depend on. | Avoid breaking changes; require release notes and migration path. |
experimental | Publicly reachable but still being shaped. | May change before 1.0; prefer warnings or aliases before removal. |
internal | Debug, runtime, or local-development surface. | Not intended for external automation; may change when internals change. |
deprecated | Kept for compatibility but replaced by another surface. | Document replacement and remove only through an explicit deprecation plan. |
Cross-cutting CLI contract
| Surface | Current behavior | Initial stability | Notes |
|---|
| Command parser | Clap-derived command tree with --help and --version at the root. | stable | Command and flag names are the highest-value CLI contract. |
| Help text | Human-readable Clap output. | experimental | Useful for users; exact spacing and prose should not be treated as machine-readable. |
| Errors | Clap validation errors or anyhow errors rendered by the binary runtime. | experimental | Exit code shape needs explicit tests before declaring stable. |
| JSON output | Script-facing JSON commands pretty-print JSON to stdout via the shared print_json path. | experimental | JSON field shape usually comes from runtime/control-plane structs and needs API inventory alignment. |
| Human output | run, solve, serve, debug latency, debug prompt, and some debug/export commands write human text to stdout. | experimental | Do not snapshot full prose unless the command is intentionally script-facing. |
| stderr | Tracing logs, Clap errors, credential prompt, and some provider/runtime diagnostics. | experimental | Credential prompt intentionally writes to stderr. |
| stdin | Only config credentials set --stdin currently reads from stdin. | stable candidate | Interaction details need a focused test. |
| Config/env | Most commands load AppConfig; config commands use $HOLON_HOME for offline config paths. | experimental | See configuration reference for the broader env surface. |
Command inventory
Root
| Command | Args | Options | Output | Initial stability | Notes |
|---|
holon --help | none | -h, --help, -V, --version | human help to stdout | stable candidate | Should be covered by command-tree snapshot tests. |
holon <COMMAND> --help | command-dependent | command-dependent | human help to stdout | stable candidate for shape; experimental for prose | Regenerate cli.md when command shape changes. |
Server and daemon
| Command | Args | Options | Output | Initial stability | Notes |
|---|
holon serve | none | --access <local|tunnel|lan|tailnet> default local; --host <HOST>; --listen <LISTEN>; --port <PORT>; --advertise <ADVERTISE>; --token <TOKEN>; --token-file <TOKEN_FILE> | long-running server; startup summaries on stdout; logs/tracing on stderr | experimental | Non-loopback/tailnet/lan access requires control token via flag, file, or HOLON_CONTROL_TOKEN. |
holon daemon start | none | same ServeOptions as serve | JSON daemon lifecycle response | stable candidate | Inline token is passed to child process via env, not argv. |
holon daemon stop | none | none | JSON daemon lifecycle response | stable candidate | Uses local daemon lifecycle helper. |
holon daemon status | none | none | JSON daemon status response | stable candidate | Important local inspection surface. |
holon daemon restart | none | same ServeOptions as serve | JSON daemon lifecycle response | stable candidate | Same access/token validation as serve. |
holon daemon logs | none | --tail <TAIL> default 80 | JSON daemon log response | stable candidate | daemon logs is documented as a local troubleshooting surface. |
Offline configuration
These commands operate on persisted config or credential files directly rather
than requiring a running daemon.
| Command | Args | Options | Output | Initial stability | Notes |
|---|
holon config get | <KEY> | none | JSON value for the key | stable candidate | Prefers daemon runtime config API when reachable, preserving stdout shape; key set comes from the configuration contract. |
holon config set | <KEY> <VALUE> | none | JSON value after write | stable candidate | Prefers daemon runtime config API when reachable, falls back offline, and reports applied_via on stderr; daemon rejections surface the daemon reason. |
holon config unset | <KEY> | none | JSON { "key": ..., "status": "unset" } | stable candidate | Prefers daemon runtime config API when reachable, falls back offline, and reports applied_via on stderr; status string should be locked if scripts depend on it. |
holon config list | none | none | full persisted config JSON | experimental | Prefers daemon runtime config API when reachable, preserving stdout shape; exposes broad config file shape. |
holon config schema | none | none | JSON config schema/metadata | stable JSON | Locked by tests/cli_json_contract.rs; entry objects expose key, kind, description, default, and optional allowed_values. |
holon config doctor | none | none | JSON provider/system diagnostics | experimental | Diagnostic shape may evolve as providers change. |
holon config models list | none | none | JSON model availability list | experimental | Provider catalog and availability details are still evolving. |
Provider configuration
| Command | Args | Options | Output | Initial stability | Notes |
|---|
holon config providers set | <PROVIDER> | --transport <TRANSPORT>; --base-url <BASE_URL>; --credential-source <SOURCE> default none; --credential-kind <KIND> default none; --credential-env <ENV>; --credential-profile <PROFILE>; --credential-external <COMMAND> | JSON { "applied_via": "offline_store", "provider": ... } | stable candidate for command shape; experimental for provider object | Built-in providers may reject incompatible transport overrides. |
holon config providers get | <PROVIDER> | none | JSON provider view | experimental | Output uses runtime provider view. |
holon config providers list | none | none | JSON array/object of provider views | experimental | Output shape should be reconciled with API/config inventory. |
holon config providers remove | <PROVIDER> | none | JSON { "applied_via": "offline_store", "provider": ..., "status": "removed|not_configured" } | stable JSON | Locked by tests/cli_json_contract.rs; status strings are script-facing. |
holon config providers doctor | <PROVIDER> | none | JSON provider view plus model-chain diagnostics | experimental | Diagnostic details may evolve. |
Credential configuration
| Command | Args | Options | Output | Initial stability | Notes |
|---|
holon config credentials set | <PROFILE> | required --kind <KIND>; one of --stdin or --material <MATERIAL> | JSON { "applied_via": "offline_store", "credential": { "profile": ..., "kind": ..., "configured": true } } | stable JSON | Locked by tests/cli_json_contract.rs; --stdin prompt goes to stderr; raw --material is intentionally discouraged for secrets. |
holon config credentials list | none | none | JSON credential profile list with profile, kind, and configured; credential material is never included | stable JSON | Locked by tests/cli_json_contract.rs; must not expose credential material. |
holon config credentials remove | <PROFILE> | none | JSON { "applied_via": "offline_store", "credential": { "profile": ..., "kind": ..., "configured": false } } | stable JSON | Locked by tests/cli_json_contract.rs; missing profiles return kind: "unknown" and configured: false. |
Agent interaction and inspection
These commands require a reachable local control plane unless noted otherwise.
| Command | Args | Options | Output | Initial stability | Notes |
|---|
holon prompt | <TEXT> | --agent <AGENT> | JSON control prompt response | experimental | Lightweight prompt path; response shape belongs to control-plane API inventory. |
holon tail | none | --limit <LIMIT> default 20; --agent <AGENT> | JSON recent briefs/log tail | stable candidate | Result shape should align with brief/output contract. |
holon transcript | none | --limit <LIMIT> default 50; --agent <AGENT> | JSON transcript entries | stable candidate | Transcript entry stability needs API inventory. |
holon task run | <SUMMARY> | required --cmd <CMD>; --workdir <WORKDIR>; --shell <SHELL>; --login <true|false>; --tty; --yield-time-ms <MS>; --max-output-tokens <N>; --agent <AGENT> | pretty JSON control-plane response | experimental | Creates command tasks through the control plane. |
holon task status | <TASK_ID> | --agent <AGENT> | pretty JSON TaskStatusSnapshot | experimental | Reads task lifecycle state through the task status API. |
holon task output | <TASK_ID> | --block; --timeout-ms <MS>; --agent <AGENT> | pretty JSON TaskOutputResult | experimental | Output preview length follows the task's creation-time --max-output-tokens; this command controls readiness waiting only. |
holon task input | <TASK_ID> | required --text <TEXT>; --agent <AGENT> | pretty JSON TaskInputResult | experimental | Sends trusted operator text to command-task stdin/TTY or supervised child-agent follow-up input. |
holon task stop | <TASK_ID> | --agent <AGENT> | pretty JSON TaskStopResult | experimental | Requests managed-task cancellation through the control plane. |
holon work-item list | none | --limit <LIMIT> default 50; --agent <AGENT> | pretty JSON array of WorkItemRecord | experimental | Initial WorkItem CLI surface is read-only. The JSON schema owner is the HTTP/API WorkItemRecord read model returned by /agents/:agent_id/work-items. |
holon work-item get | <WORK_ITEM_ID> | --agent <AGENT> | pretty JSON WorkItemRecord | experimental | Reads a single work item through /agents/:agent_id/work-items/:work_item_id; create/update/pick/complete commands are deferred until those mutation API contracts are stabilized. |
holon timer | none | required --after-ms <MS>; --every-ms <MS>; --summary <SUMMARY>; --agent <AGENT> | pretty JSON control-plane response | experimental | Timer surface should be aligned with WorkItem/waiting-plane contract. |
Agent lifecycle and model selection
| Command | Args | Options | Output | Initial stability | Notes |
|---|
holon agent / holon agents | optional subcommand | none | defaults to agent list JSON | stable candidate | agents is an alias. |
holon agent list | none | none | JSON agent entries | stable candidate | Public multi-agent inspection surface. |
holon agent status | optional [AGENT_ID] | none | JSON agent status | stable candidate | Positional agent id; defaults to configured default agent. |
holon agent create | <AGENT_ID> | --template <TEMPLATE> | pretty JSON control-plane response | stable candidate | Template identifier contract should align with agent initialization docs. |
holon agent start | optional [AGENT_ID] | none | JSON lifecycle control response | stable candidate | Replacement for deprecated control start. |
holon agent stop | optional [AGENT_ID] | none | JSON lifecycle control response | stable candidate | Replacement for deprecated control stop. |
holon agent abort | optional [AGENT_ID] | none | pretty JSON control-plane response | stable candidate | Replacement for deprecated control abort; shares the lifecycle JSON output path with start/stop. |
holon agent model get | optional [AGENT_ID] | none | JSON model override/status fragment | stable candidate | Reads summary.model from agent status. |
holon agent model set | <MODEL> [AGENT_ID] | none | JSON model override response | stable candidate | Positional AGENT_ID is tested. |
holon agent model clear | optional [AGENT_ID] | none | JSON model override response | stable candidate | Should share contract with set/get. |
holon control | <start|stop|abort> | --agent <AGENT> | pretty JSON lifecycle response | deprecated | Use `holon agent start |
Deprecated holon control compatibility is documented in
CLI stability policy.
New automation should use the holon agent ... lifecycle commands.
Skills
Skill management is split into library operations and agent enablement:
| Command | Args | Options | Output | Initial stability | Notes |
|---|
holon skills catalog | none | none | JSON catalog response | experimental | Lists all skills in the local Skill Library. |
holon skills refresh | none | none | JSON catalog response | experimental | Refresh runtime catalog by rescanning local skill roots. Does not reconcile with lock file or fetch remote updates. |
holon skills add | <SOURCE> | --remote; --skill <SKILL>; --copy | pretty JSON control-plane response | experimental | Adds a skill to the local Skill Library. Local paths resolved relative to cwd when directories. |
holon skills remove | <NAME> | none | pretty JSON control-plane response | experimental | Removes a skill from the local Skill Library. |
holon skills check | [NAME] | none | pretty JSON control-plane response | experimental | Checks Skill Library consistency against .skill-lock.json. |
holon skills reconcile | [NAME] | none | pretty JSON control-plane response | experimental | Reconciles library entries with lock file. |
holon skills list | none | --agent <AGENT> | JSON agent skills response | experimental | Lists skills enabled/effective for an agent. |
holon skills enable | <NAME> | --agent <AGENT>; --copy | pretty JSON control-plane response | experimental | Enables a locally known skill for an agent. |
holon skills disable | <NAME> | --agent <AGENT> | pretty JSON control-plane response | experimental | Disables a skill for an agent. |
holon skills install | <NAME_OR_PATH> | --remote; --skill <SKILL>; --copy; --agent <AGENT> | pretty JSON control-plane response | deprecated | Compatibility alias. Prefer skills add for library or skills enable for agents. |
holon skills uninstall | <NAME> | --agent <AGENT> | pretty JSON control-plane response | deprecated | Compatibility alias. Prefer skills remove for library or skills disable for agents. |
One-shot and solve workflows
| Command | Args | Options | Output | Initial stability | Notes |
|---|
holon run | <TEXT> | --trust <TRUST> default trusted-operator; --json; --agent <AGENT>; --create-agent; --template <TEMPLATE>; --max-turns <N>; --no-wait-for-tasks; --home <HOME>; --workspace-root <PATH>; --cwd <PATH> | human render_text() by default; pretty JSON with --json | stable candidate for command shape; experimental for output | Core user entry point. JSON response shape should be locked before stable automation guidance. |
holon solve | <REF> | --repo <REPO>; --base <BASE>; --goal <GOAL>; --role <ROLE>; --agent <AGENT>; --template <TEMPLATE>; --model <MODEL>; --max-turns <N>; --trust <TRUST> default trusted-operator; --json; --home <HOME>; --workspace <PATH>; --workspace-root <PATH>; --cwd <PATH>; --input <INPUT>; --output <OUTPUT> | human render_text() by default; pretty JSON with --json | experimental | GitHub/task workflow surface. --workspace and --workspace-root are currently coalesced. |
Workspace
| Command | Args | Options | Output | Initial stability | Notes |
|---|
holon workspace attach | <PATH> | --agent <AGENT> | JSON attach response | stable candidate | Workspace identity/projection contract is central to runtime stability. |
holon workspace exit | none | --agent <AGENT> | JSON exit response | stable candidate | Should align with workspace-binding RFCs. |
holon workspace detach | <WORKSPACE_ID> | --agent <AGENT> | JSON detach response | stable candidate | WORKSPACE_ID stability belongs to API/runtime inventory. |
TUI
| Command | Args | Options | Output | Initial stability | Notes |
|---|
holon tui | none | --no-alt-screen; --connect <URL>; --token <TOKEN>; --token-file <PATH>; --token-profile <PROFILE> | interactive terminal UI | experimental | --connect requires exactly one token source. TUI is not the primary stable runtime contract. |
Debug utilities
| Command | Args | Options | Output | Initial stability | Notes |
|---|
holon debug prompt | <TEXT> | --agent <AGENT>; --trust <TRUST> default trusted-operator | human prompt dump | internal | Debug-only prompt inspection. |
holon debug latency | none | --agent <AGENT>; --limit <LIMIT> default 10; --events-limit <EVENTS_LIMIT> default 5000 | human latency report | internal | Useful diagnostics; prose should not be machine contract. |
holon debug scheduler-fixture | none | --agent <AGENT>; required --output <OUTPUT> | writes JSON/JSONL fixture files; prints export summary | internal | Fixture file shape may be useful for tests but should be documented separately if stabilized. |
Environment and config inputs touched by CLI
This is not the full configuration inventory; it lists environment variables
that visibly affect CLI behavior while invoking commands.
| Input | Used by | Current behavior | Initial stability |
|---|
HOLON_HOME | config/credentials and runtime config loading | Selects Holon home/config/credential paths. | stable candidate |
HOLON_HTTP_ADDR | runtime/control-plane commands | Selects local control-plane HTTP address when loading AppConfig. | stable candidate |
HOLON_CALLBACK_BASE_URL | serve, runtime config | Sets callback base URL default. | experimental |
HOLON_SOCKET_PATH | daemon/serve | Selects local control socket path. | experimental |
HOLON_WORKSPACE_DIR | runtime commands | Sets default workspace directory. | experimental |
HOLON_AGENT_ID | commands with optional --agent / [AGENT_ID] | Sets default agent id. | stable candidate |
HOLON_CONTROL_TOKEN | serve, daemon, control-plane client config | Supplies bearer token/control auth. | stable candidate |
HOLON_CONTROL_AUTH_MODE | control-plane config | Parses auto, required, or disabled. | experimental |
HOLON_MODEL | run, solve, provider config | Sets default model; solve --model writes this env var for the process. | stable candidate |
| Provider API-key env vars | provider-backed commands | Examples include OPENAI_API_KEY, ANTHROPIC_AUTH_TOKEN, and configured custom env names. | stable candidate for documented provider envs |
RUST_LOG and tracing env filter | all commands | Controls tracing output to stderr. | internal |
Output contract gaps
- JSON responses now share the normalized stdout path for script-facing
commands. The remaining output work is assigning schema owners and
stability levels to each response shape.
- Exit codes now have a baseline process contract. See
CLI exit codes. Command-specific business-state
promotion to non-zero exits remains intentionally opt-in and must be
documented per command.
- Machine-readable outputs need schema owners. CLI JSON often mirrors
control-plane/runtime structs. The API inventory should decide which fields
are stable, diagnostic, or internal.
- Human output is mixed with operational summaries.
serve, run,
solve, and debug commands should clearly state whether their stdout is
script-safe.
- Deprecated
control remains reachable. It should keep compatibility
until a removal plan is documented.
- Help snapshots are manual.
docs/website/reference/cli.md says it is
regenerated from holon --help, but there is no checked-in generator or
snapshot test.
Tracking issues
The initial Milestone 8 CLI/API stability follow-up work is complete. Phase 2
work remains tracked in the
CLI/API Stability Contracts
milestone by
#1444:
| Priority | Issue | Scope |
|---|
| 1 | #1437 | Refresh API/CLI contract inventories after Milestone 8 completion. |
| 1 | #1442 | Add JSON output schema and golden tests for stable commands. |
| 2 | #1438 | Migrate OpenAPI baseline to aide route/type metadata. |
| 2 | #1439 | Tighten OpenAPI DTO schemas for stable read models. |
| 2 | #1440 | Add WorkItem mutation HTTP lifecycle endpoints. |
| 2 | #1441 | Add Timer cancellation lifecycle endpoint. |
| 3 | #1443 | Define stable operator-facing event payload subset. |
Recommended next contract tests
| Priority | Test | Purpose |
|---|
| 1 | Clap command tree/help snapshot with normalized whitespace | Detect accidental command/flag drift. |
| 1 | Parse tests for stable candidate positional args and aliases | Lock high-value CLI shape without over-snapshotting prose. |
| 1 | --json smoke tests for run/solve with a fake provider or fixture | Confirm machine-readable mode remains parseable. |
| 2 | Config command golden JSON for get, set, unset, schema, provider remove, credential list/remove | Lock offline scripting surfaces. |
| 2 | Daemon/status/log JSON shape tests | Lock local operations surfaces. |
| 2 | More error behavior tests for missing token and command-specific business states | Extend the baseline exit-code contract where commands promote domain failures to process failures. |
| 3 | Normalize or document raw HTTP-body commands (task, timer, agent create/abort, skills add/remove/enable/disable) | Reduce output contract drift. |
Follow-up inventory scope
After this CLI inventory is reviewed, continue in this order:
- CLI JSON output schemas for stable-candidate commands
(#1442).
- Control-plane DTO schemas used by CLI task/work-item/timer commands
(#1439).
- Runtime event payload subset used by tail, transcript, replay, and SSE
(#1443).
- Rust crate public API, if it is intended to be consumed externally.
