On this page

CLI Reference

Holon's command-line interface. All commands accept --help for detailed flag documentation.

For scripting guidance, stability levels, and support policy, see CLI stability policy and CLI contract inventory.

Agent output observation

holon tail --agent <id> --limit 20 retains the default JSON brief snapshot. Opt in to persisted assistant text progress and bounded observation:

holon tail --agent child --include-progress
holon tail --agent child --include-progress --follow --timeout-ms 5000 \
  --max-events 100 --max-bytes 65536
holon tail --agent child --include-progress --follow --cursor '<checkpoint>'

Opt-in output is NDJSON: progress/brief/turn-status records followed by an end receipt with cursor, stop reason, record count and timestamped runtime status. Follow has a whole-operation deadline (default 5 s, maximum 30 s), record budget (default 100, maximum 1000, excluding the final receipt), and serialized byte budget (default 64 KiB, maximum 1 MiB, including the receipt). --follow alone follows briefs; --cursor resumes after a conversation stream checkpoint without replaying the initial text snapshot. Reset/gap requires a fresh snapshot.

Reads select output types, not tasks: one agent's tasks may be mixed. They do not expose raw transcript, reasoning or tool trace, but are not an isolation or redaction guarantee. Reads never prompt/wake/stop the observed agent or consume task results. EOF or an end receipt does not mean a task completed. Use holon task status <TASK_ID> (TaskStatus for models) for lifecycle and WaitFor(wake=task_result, resource=<task_id>, delivery=...) for result re-entry. The runtime must advertise agents.conversation-read.v1 for opt-in observation; the existing default brief snapshot remains available without it.

Command Tree

holon (v0.59.0)
├── context      Show the declared caller context
├── commands     Show machine-readable CLI command metadata
├── serve        Start HTTP control plane server
├── onboard      Interactive setup wizard or secret-safe diagnostics
├── daemon       Background daemon lifecycle
│   ├── start    Start the daemon
│   ├── prepare-update Stop the daemon without altering desired auto-start state
│   ├── stop     Stop the daemon
│   ├── status   Check daemon status
│   ├── restart  Restart the daemon
│   └── logs     View daemon logs
├── config       Runtime configuration
│   ├── get      Read a config key
│   ├── set      Write a config key
│   ├── unset    Remove a config key
│   ├── providers Provider management
│   │   ├── set    Add/update a provider
│   │   ├── get    Show a provider
│   │   ├── list   List all providers
│   │   ├── remove Remove a provider
│   │   └── doctor Provider credential check
│   ├── credentials API key storage
│   │   ├── set    Store a credential
│   │   ├── list   List stored credentials
│   │   └── remove Remove a credential
│   ├── models  Model catalog and discovery
│   │   ├── list    List available models
│   │   └── refresh Refresh discovered models for a provider
│   ├── migrate-model-routes  Inspect/rewrite legacy model selections
│   ├── list     List all current config
│   ├── schema   Show all config keys with types and defaults
│   └── doctor   Full system health check
├── prompt       Send a prompt to an agent (lightweight)
├── tail         Read recent briefs or bounded agent progress
├── transcript   Show conversation transcript
├── events       Read stable runtime event envelopes
│   ├── tail     Fetch a bounded page of event envelopes
│   └── stream   Stream event envelopes as newline-delimited JSON
├── task         Run a command as a background task
│   ├── list     List tasks
│   ├── run      Run a command as a managed background task
│   ├── status   Show task lifecycle status
│   ├── input    Send text input to a task
│   └── stop     Stop a task
├── work-item    Inspect and manage WorkItems
│   ├── list     List WorkItems
│   ├── get      Show a WorkItem
│   ├── create   Create a WorkItem
│   ├── pick     Pick a WorkItem as current focus
│   ├── update   Update a WorkItem
│   └── complete Complete a WorkItem
├── timer        Create, list, or cancel timers
│   ├── create   Create a delayed or recurring timer
│   ├── list     List active timers
│   └── cancel   Cancel an active timer
├── control      [deprecated] use `holon agent start|stop|abort`
├── agent        Agent management
│   ├── list     List all agents
│   ├── get      Show canonical agent detail
│   ├── status   Show agent status
│   ├── create   Create a new agent
│   ├── rename   Rename a public self-owned agent
│   ├── repair   Retry incomplete post-create bootstrap steps
│   ├── start    Start an agent
│   ├── stop     Stop an agent
│   ├── delete   Permanently delete an agent and its data
│   ├── abort    Abort current run
│   ├── reset-callback Reset the external trigger callback for an agent
│   └── model    Per-agent model configuration
│       ├── get  Get agent model override
│       ├── set  Set agent model override
│       └── clear Clear agent model override
├── skills         Manage skills
│   ├── catalog    List Skill Library catalog
│   ├── add        Add a skill to the library
│   ├── remove     Remove a skill from the library
│   ├── check      Check library consistency
│   ├── reconcile  Reconcile library with lock file
│   ├── list       List agent enabled skills
│   ├── enable     Enable a skill for an agent
│   ├── disable    Disable a skill for an agent
│   ├── update     Fetch and update skills from remote sources
│   ├── refresh    Rescan local roots
│   ├── install    [deprecated] Compatibility alias
│   └── uninstall  [deprecated] Compatibility alias
├── run          One-shot agent interaction
├── solve        Solve a GitHub issue or similar target
├── workspace    Workspace management (attach, exit, detach)
│   ├── attach   Attach to an existing workspace
│   ├── exit     Exit current workspace
│   └── detach   Detach from a workspace
├── tui          Launch interactive terminal UI
├── memory-index Memory indexing management
│   └── rebuild  Rebuild the memory search index
├── models-dev   models.dev snapshot refresh, validation, and audit
│   ├── refresh  Fetch the snapshot and regenerate the artifact
│   ├── validate Validate the checked-in snapshot and artifact
│   └── audit    Audit provider mappings against a snapshot
├── debug        Debug utilities
│   ├── prompt   Debug-mode prompt
│   ├── latency  Show latency metrics
│   ├── performance  Show performance metrics
│   ├── trace    Show end-to-end trace by id or search
│   ├── runtime-db   Runtime database audit, retention, and maintenance
│   │   ├── agent-relations Report or backfill canonical agent relation records
│   │   ├── audit    Audit runtime database invariants
│   │   ├── retention Run retention cleanup on old database records
│   │   ├── compact  Compact the runtime database
│   │   ├── wait-final-brief-publication Prepare or apply a repair for WaitFor final brief publication linkage
│   │   ├── turn-settlement Audit or apply a fingerprint-fenced historical Turn settlement repair
│   │   └── conversation-input-assignment-rollback Preflight or rollback v66 repair marker
│   ├── scheduler-recovery  Inspect/apply scheduler recovery
│   └── scheduler-fixture Generate scheduler fixture data
└── help         Print help

Note: This reference is maintained from the checked CLI snapshot. If you are running a source build from main, some commands or flags may differ. Always run holon --help and holon <COMMAND> --help for the live command reference of your installed version.

Common Workflows

Quick one-shot

holon run "Explain Rust ownership"
holon run --json "List files"                          # JSON output
holon run --authority-class external-evidence "User query"  # set authority class

Create and use an agent

holon agent create reviewer --template code-reviewer
holon agent repair reviewer
holon run --agent reviewer "Review src/runtime/turn.rs"

Agent lifecycle

holon agent start reviewer
holon agent stop reviewer
holon agent abort reviewer
holon agent delete reviewer --yes

Deprecated: The holon control command has been replaced by holon agent start, holon agent stop, and holon agent abort. The old control command is kept for backward compatibility only; see CLI stability policy for the compatibility and removal criteria.

holon agent delete permanently removes an agent and its associated data. Pass --cascade-private-children to also remove its private child agents and --wait to block until the deletion job completes. It requires --yes in non-interactive mode.

holon agent repair <AGENT_ID> retries incomplete post-create template, runtime, workspace, model, and initial-message steps. It does not recreate the Agent or overwrite conflicting user-managed state.

holon agent rename <AGENT_ID> --name <NAME> updates the display name of a public self-owned agent and echoes the updated agent detail. The agent id is permanent; duplicate names are rejected with a readable conflict error.

Model selection

holon config set model.default "deepseek-anthropic@default/deepseek-v4-pro"
holon agent model set "anthropic@default/claude-sonnet-4-6" reviewer
holon agent model get reviewer
holon agent model clear reviewer

Executable model selections use canonical provider@endpoint/model route refs. Legacy provider/model input remains accepted. Inspect or rewrite persisted legacy values with:

holon config migrate-model-routes          # dry-run
holon config migrate-model-routes --write  # validated canonical rewrite

models.dev provider mapping

Holon ships a checked-in models.dev snapshot and a versioned provider mapping manifest that reconciles upstream model metadata with Holon provider/route identities. The holon models-dev subcommands audit, validate, and refresh this snapshot:

holon models-dev validate        # validate the checked-in snapshot and artifact
holon models-dev audit           # audit provider mappings against the snapshot
holon models-dev audit --json    # machine-readable mapping audit report
holon models-dev refresh         # fetch upstream and regenerate the artifact

refresh and validate target the repository's checked-in models.dev/ files and are intended for Holon development and release automation. See Supported Models for the runtime model catalog.

Memory index management

Manage the local vector/full-text memory search index for agents and workspaces:

holon memory-index rebuild                      # submit a full rebuild to background indexer
holon memory-index rebuild --agent <AGENT>      # rebuild index for a specific agent
holon memory-index rebuild --workspace <WS>     # rebuild index for a specific workspace
holon memory-index rebuild --offline            # run directly without submitting to daemon

Debug utilities

Holon provides operational and diagnostic subcommands under holon debug for inspecting runtime metrics, traces, and database health:

# Performance, latency, and traces
holon debug latency
holon debug performance
holon debug trace <trace_id>

# Runtime database audit, compact, and repair
holon debug runtime-db audit
holon debug runtime-db compact
holon debug runtime-db retention
holon debug runtime-db agent-relations
holon debug runtime-db wait-final-brief-publication --dry-run
holon debug runtime-db turn-settlement

# Scheduler diagnostic inspection
holon debug scheduler-recovery
holon debug scheduler-fixture

Daemon management

holon daemon start
holon daemon start --port 8787 --access tunnel
holon daemon status
holon daemon logs
holon daemon restart
holon daemon stop

Lifecycle command JSON includes process_created: true only when the command created the returned daemon process. An idempotent Start that reuses an existing daemon reports false; success alone does not establish process ownership. During shutdown, the stop path rechecks process liveness with a short delay and treats zombie processes (state Z or X) as exited rather than running daemons, preventing spurious TERM+KILL failures when system reaping lags behind process termination. holon daemon status reports readiness with bounded diagnostic checks and avoids waiting on a busy runtime database.

Persistent serve options

serve, daemon start, and daemon restart inherit accepted serve options from HOLON_HOME/daemon/serve_profile.json, even after clean shutdown removes run/daemon.json. Stop and prepare-update do not remove this profile. Explicit CLI options take precedence over explicit startup environment inputs, then the profile, validated legacy metadata (migration only), and defaults. HOLON_HTTP_ADDR and HOLON_CONTROL_TOKEN are explicit environment overrides; an unset variable is not an override. Startup logs name the configuration source and overridden fields / environment variables without printing credential values. Service managers that keep passing flags or environment inputs keep overriding the saved configuration; inspect these diagnostics when troubleshooting.

Token-file and web-dist paths are saved as absolute paths. Token contents are never saved. Inline or environment tokens save only an external_required authentication marker: subsequent startup requires an explicit token or token file, even for loopback. A missing or empty token file fails instead of falling back to unauthenticated access. Authentication-only overrides preserve the network and desktop settings.

Use --reset-serve-options on serve/start/restart to explicitly discard inherited options and resolve CLI, environment and defaults again:

holon daemon restart --reset-serve-options --access local

Invalid options, credential reads, foreign runtime identity, or conflicting idempotent Start do not replace the profile or stop the current daemon. Once valid intent is accepted, a later bind/readiness failure retains that intent; it does not mean startup succeeded. Inspect daemon status and logs. A corrupt or unsupported profile fails rather than silently selecting defaults. Stop and prepare-update can still safely stop an identified daemon without reading or replacing that profile. Old binaries cannot inherit this profile; supply explicit flags and credentials when downgrading. Options already deleted by an old version cannot be recovered.

Onboarding

holon onboard is the fastest way to configure Holon for the first time or repair a broken provider/model configuration. It has two modes:

Interactive TUI (default on a terminal): walks you through provider selection, model choice, search settings, and credential input — without echoing secret material to the screen.
JSON diagnostics (--json or non-TTY): prints a secret-safe diagnostic report with actionable next steps, suitable for scripts and CI.

holon onboard                    # Interactive setup wizard (TTY)
holon onboard --json             # Secret-safe diagnostic report (JSON)

The TUI flow guides you through:

Provider — select from built-in and custom providers
Credential — for OpenAI Codex: browser-based OAuth login; for other providers: enter your API key (input never echoed or stored in logs)
Model — pick a default model for your provider, or enter a custom model id
Search — enable DuckDuckGo managed search, model-native search, or disable
Apply — writes config, stores credentials, and prints a summary

The JSON report includes status, sections (home, agent, model_provider, search, credentials), and next_actions. It is secret-safe by design: no credential material ever appears in the report.

Configuration inspection

holon config list                # All current config
holon config schema              # All keys with types and defaults
holon config doctor              # Full health check
holon config providers list      # All registered providers
holon config models list         # Available models with status
holon config credentials list    # Stored credential profiles

Stable script-facing JSON contracts currently cover holon config schema, holon config providers remove, and holon config credentials set/list/remove. Other configuration inspection commands emit JSON too, but remain experimental until their provider/runtime DTO ownership is fully stabilized. Human-readable help and prose output are separate from these JSON contracts.

Credential setup

holon config credentials set --kind api_key --stdin deepseek
# Paste key, press Enter, then Ctrl+D
holon config credentials remove deepseek

Custom provider

holon config providers set my-proxy \
  --transport anthropic_messages \
  --base-url "https://my-proxy.example.com" \
  --credential-source env \
  --credential-env "MY_PROXY_API_KEY" \
  --credential-kind api_key

HTTP server

holon serve --port 8787
holon serve --port 8787 --token "secret"
holon serve --access tunnel

Background tasks

holon task run "Build project" --cmd "cargo build"
holon task status <TASK_ID>
holon task input <TASK_ID> --text "continue\n"
holon task stop <TASK_ID>

Task lifecycle commands default to the configured default agent. Pass --agent <AGENT> to inspect or control a task owned by a different public agent. All task lifecycle commands print the corresponding JSON control-plane or read-model response.

The former holon task output command and model tool TaskOutput are removed, including their block/timeout_ms current-turn short wait. They are not replaced by tail polling. Use the status response's runtime-confirmed command file path for bounded reads, for example:

dd if="$CONFIRMED_OUTPUT_PATH" bs=1 skip=0 count=8192 status=none

Set the variable to the exact returned path; never derive it from an agent home or task id. Capture can retain only a head/tail and rewrite the file at termination. EOF is not completion; wait for a terminal task before relying on a stable final log. Observe agent progress with bounded holon tail --agent, which does not promise task-exclusive output. The underlying HTTP task-output route and runtime capture/result services remain available.

WorkItems

holon work-item list
holon work-item list --limit 10 --agent planner
holon work-item get <WORK_ITEM_ID>
holon work-item get <WORK_ITEM_ID> --agent planner
holon work-item create "Triage failing CI"
holon work-item pick <WORK_ITEM_ID> --reason "unblock release"
holon work-item complete <WORK_ITEM_ID>

list and get are read-only and print the HTTP read-model WorkItemRecord JSON shape returned by /agents/:agent_id/work-items and /agents/:agent_id/work-items/:work_item_id. The create, update, pick, and complete subcommands mutate WorkItem state and return the corresponding control-plane response.

Timers

holon timer create --after-ms 60000 --summary "Heartbeat check"
holon timer list
holon timer cancel <TIMER_ID>

holon timer schedules delayed or recurring timers for an agent (defaults to the default agent, or pass --agent <AGENT>).

Events

holon events tail --limit 20
holon events tail --order asc --max-level info
holon events tail --agent benchmark-run --order asc --offline
holon events stream --after-seq 42 --max-events 100

events tail --offline reads the same stable event envelope from the local runtime database without requiring a running daemon. Offline pages do not support --max-level.

Terminal UI

holon tui
holon tui --no-alt-screen
holon tui --connect http://remote:8787 --token "secret"

Multi-turn tasks

holon run --max-turns 5 "Write a Rust function with tests"
holon run --workspace-root /path/to/project "Analyze this codebase"
holon run --agent builder --workspace-root /path/to/project "Fix build errors"

Key Options Reference

`holon run` options

Option	Description
`--agent <AGENT>`	Target a specific agent
`--create-agent`	Create agent if not exists
`--template <TEMPLATE>`	Agent template for new agents
`--authority-class <CLASS>`	Authority class: `operator-instruction`, `runtime-instruction`, `integration-signal`, `external-evidence` (alias: `--trust`)
`--json`	Machine-readable JSON output
`--max-turns <N>`	Limit agent turns
`--no-wait-for-tasks`	Don't block on background tasks
`--workspace-root <PATH>`	Workspace root directory
`--cwd <PATH>`	Working directory
`--home <PATH>`	Holon home directory

`holon serve` options

Option	Description
`--port <PORT>`	Listen port
`--host <HOST>`	Bind host
`--listen <ADDR>`	Listen address
`--access <MODE>`	`local`, `tunnel`, `cloudflare`, `lan`, `tailnet`
`--token <TOKEN>`	Bearer token for auth
`--token-file <PATH>`	Read token from file
`--advertise <URL>`	Advertised URL
`--cloudflare-token-file <PATH>`	Named Tunnel connector token file; requires `cloudflare` access and an HTTPS advertised hostname
`--web-dist <PATH>`	Web assets directory; persisted as an absolute path
`--reset-serve-options`	Discard inherited serve intent; resolve explicit CLI/env and defaults
`--desktop-integration[=true\|false]`	Allow authorized Finder actions on the daemon host; macOS only, independent of LAN/Serve; default off
`--desktop-integration-if-unconfigured`	Enable desktop integration only if no profile or valid legacy intent exists when accepted under the lifecycle lock; explicit desktop options win; cannot combine with reset

`holon daemon start` options

Option	Description
`--port <PORT>`	Daemon port
`--access <MODE>`	Access mode (same as serve)
`--host <HOST>`	Bind host
`--listen <ADDR>`	Listen address
`--token <TOKEN>`	Auth token
`--token-file <PATH>`	Read token from a file; persist only its absolute path
`--advertise <URL>`	Advertised URL
`--cloudflare-token-file <PATH>`	Same as serve; persists the absolute path, not the connector token
`--web-dist <PATH>`	Web assets directory
`--reset-serve-options`	Same as serve; also available on daemon restart
`--desktop-integration[=true\|false]`	Same as serve; restart inherits the setting unless explicitly overridden
`--desktop-integration-if-unconfigured`	Same as serve; also available on restart; a request-only first-launch hint, not a persistent override

`holon agent create` options

Option	Description
`--template <TEMPLATE>`	Built-in or path template

`holon solve` options

Flag	Type	Default	Description
`REF` (positional)	string	(required)	GitHub URL, `owner/repo#NN`, or `#NN`
`--repo`	string	—	Repository for numeric-only refs
`--base`	string	`main`	Base branch for fix branches
`--goal`	string	—	Override the agent's reading of the target
`--role`	string	—	Extra role context passed to the agent
`--agent`	string	`github-solve`	Agent ID to use or create
`--template`	string	`github-solver`	Template for the agent
`--model`	string	—	Override the configured model
`--max-turns`	integer	—	Maximum agent turns before a forced stop
`--authority-class` (alias `--trust`)	string	`operator-instruction`	Trust level for the run
`--json`	flag	false	Print JSON instead of text
`--home`	path	`~/.holon`	Holon home directory
`--workspace`	path	—	Working directory for the agent
`--cwd`	path	—	Current working directory for the agent
`--input`	path	—	Input context directory
`--output`	path	—	Output artifacts directory