Skip to content

cli-reference.md

Latest commit

 

History

History
87 lines (51 loc) · 3.15 KB

cli-reference.md

File metadata and controls

87 lines (51 loc) · 3.15 KB
Raw

CLI Reference

Formal documentation for the acp command-line interface, as implemented in cmd/acp.

The acp binary contains everything: the CLI, the control plane (acp serve), and the worker harness (acp agent). All commands read and write the vault directly — there is no API server in V1.

Global: every command accepts --vault <path>; the default comes from $VAULT_PATH, falling back to ./vault.

Setup

acp init

Scaffolds the vault directory structure (tasks/{pending,doing,done,failed,.wip}, agents/, knowledge/, logs/, results/, scratch/). Idempotent.

Task Management

acp task create [flags] <description>

Creates a new task in pending/ and prints the generated task ID.

Options:

  • --role <role>: Optional. Capability required to claim this task (e.g. coder). Empty = any worker.
  • --priority <level>: low | normal | high | critical. Default: normal.
  • --metadata <json>: Optional JSON object of string key-value pairs.
acp task create --role coder --priority high "Refactor the authentication middleware"

acp task list [--status S] [--role R] [--agent A] [--json]

Lists tasks, optionally filtered. --json is the machine-readable form orchestrators should consume.

acp task show <id>

Prints the full JSON of one task, searching all state directories.

acp task retry <id>

Moves a failed task back to pending/, resetting retry_count and release_count. Only valid for tasks in failed/.

There is deliberately no task cancel in V1 — the state machine defines no cancellation transition (see DD-007).

Observation

acp status [--json]

Shows task counts per state and every registered agent with its liveness (an agent is alive if its heartbeat record was updated in the last 15 minutes) and current task.

Runtime

acp serve

Runs the control plane: the RecoveryController (lease expiry + .wip janitor), the VaultController (integrity scans), and the AgentObserver (stale-heartbeat warnings). Runs until interrupted; safe to kill and restart at any point — all state is in the vault.

Options:

  • --recovery-interval <dur>: default 5m.

acp agent --id <id> [flags]

Runs a worker: register → poll → claim → execute → complete, with background lease renewal.

Options:

  • --id <id>: Required. The agent's identity in the vault.
  • --capabilities <a,b,c>: Claims only tasks whose role is empty or in this list.
  • --exec <cmd>: Shell command to execute each task. Receives $ACP_TASK_ID, $ACP_TASK_DESCRIPTION, $ACP_TASK_ROLE; its combined output becomes the result body. Default: a stub executor (2-second sleep) for development.
  • --poll <dur>: Poll interval, default 5s.
acp agent --id coder-1 --capabilities coder \
  --exec 'claude -p "$ACP_TASK_DESCRIPTION"'

Planned (Not in V1)

  • acp logs <agent-id> — tail an agent's log (use tail -f vault/logs/<agent-id>.log meanwhile; ambient inspectability is the point)
  • acp events [--follow] — stream the event trail, once vault/events/ exists (see API Contract §4)