Acp Agent CLI

acp-agent-cli

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

When the user passes a natural language request, interpret it and map it to the appropriate CLI command using the command reference below. If the request is ambiguous, ask the user to clarify. Execute the mapped command via Bash and return the result.

Natural Language to Command Mapping

If the user's request does not match any known command, explain what the CLI can do and suggest relevant commands.

Description

Full-function ACP CLI for developers and automation, exposing the complete ACP protocol surface and an integrated agent registry for discovering, managing, and installing ACP agents through one unified command-line workflow.

This generated Skill reuses the approved description contract across Cargo metadata, SKILL.md, README, and help text.

Prerequisites

• A working Rust toolchain (rustup, cargo) to compile and test the binary.
• No additional system dependencies are required for the default scaffold.
• The managed daemon uses std-only local IPC and writes runtime artifacts under state/daemon.

Invocation

acp-agent-cli [OPTIONS] <COMMAND>
acp-agent-cli help [COMMAND_PATH ...] [--format yaml|json|toml]
acp-agent-cli run [OPTIONS] <INPUT>
acp-agent-cli paths [OPTIONS]
acp-agent-cli context <show|use> [OPTIONS]
acp-agent-cli agent <status|candidates|select|set-executable|set-args> [OPTIONS]
acp-agent-cli workspace <browse|mkdir> [OPTIONS]
acp-agent-cli session <create|list|use|show|prompt|cancel-turn|stop|mode|config-option|model|authenticate|remote-sessions> [OPTIONS]
acp-agent-cli command list [OPTIONS]
acp-agent-cli skill list [OPTIONS]
acp-agent-cli proposal <list|approve|reject|edit> [OPTIONS]
acp-agent-cli file <upload|download> [OPTIONS]
acp-agent-cli code <read|list|search> [OPTIONS]
acp-agent-cli terminal <create|list|input|resize|output|close> [OPTIONS]
acp-agent-cli port-forward <create|list|delete> [OPTIONS]
acp-agent-cli events follow [OPTIONS]
acp-agent-cli state show [OPTIONS]
acp-agent-cli passthrough <command|skill> [OPTIONS]
acp-agent-cli repl [OPTIONS]
acp-agent-cli daemon <run|start|stop|restart|status> [OPTIONS]

The canonical agent-facing contract uses the bare command name shown above. cargo run -- ... and ./target/release/acp-agent-cli ... are local developer execution forms and should be documented in README.md, not treated as the final installed skill interface.

Global Options

Commands

Input

• The scaffolded CLI does not read default-mode input from stdin.
• run requires one positional <INPUT> argument.
• context use accepts one or more of --agent, --workspace, --session, --selector KEY=VALUE, and --cwd PATH.
• help accepts an optional command path such as run, paths, context use, session prompt, or daemon status.

Output

Standard command results are written to stdout. Errors and diagnostics are written to stderr.

Help Channels

• Leaf commands never auto-display help. Missing required input stays a structured validation failure in the selected output format.
• Top-level invocation and non-leaf invocation (for example context or daemon) display man-like human-readable help automatically and exit 0.
• --help is the man-like human-readable help channel. It always prints text and exits 0, regardless of --format.
• help is the structured help channel. It supports yaml, json, and toml, with YAML as the default.
• Human-readable help is a required man-like surface with these sections in order: NAME, SYNOPSIS, DESCRIPTION, OPTIONS, FORMATS, EXAMPLES, EXIT CODES.

Structured Results

The default one-shot result format is YAML.

Example run result:

status: ok
message: Hello from acp-agent-cli
input: demo-input
effective_context:
  workspace: demo

Example paths result:

config_dir: /home/user/.config/acp-agent-cli
data_dir: /home/user/.local/share/acp-agent-cli
state_dir: /home/user/.local/share/acp-agent-cli/state
cache_dir: /home/user/.cache/acp-agent-cli
scope: user_scoped_default
override_mechanisms:
  - --config-dir
  - --data-dir
  - --state-dir
  - --cache-dir
  - --log-dir

Runtime Directories and Active Context

• paths exposes the runtime directory family: config, data, state, cache, and optional logs.
• Defaults are user-scoped unless explicitly overridden.
• context show exposes the persisted and effective Active Context.
• Explicit per-invocation selectors on run override the persisted Active Context for that invocation only.
• repl is enabled and keeps plain-text help, persisted history, and slash command completion.
• When daemon is enabled, runtime artifacts live beneath state/daemon.

Streaming Mode

• Activate streaming with --stream.
• --stream --format yaml writes YAML multi-document output using --- before each record and ... at the end.
• --stream --format json writes NDJSON, one compact JSON object per line.
• --stream --format toml is unsupported and must fail with a non-zero exit code and an explanation on stderr.

Managed Daemon Contract

• Public daemon control uses daemon start, daemon stop, daemon restart, and daemon status.
• daemon run is the foreground app-server entrypoint used for supervision and for daemon start to spawn the background worker.
• run is daemonizable and accepts --via local|daemon plus --ensure-daemon.
• Local-only surfaces such as help, paths, context, and daemon reject daemon routing with structured errors.
• Local IPC is the default transport. Loopback TCP is opt-in only. OS permissions protect local IPC, and TCP requires explicit authentication when enabled.
• Runtime artifact inspection includes daemon.pid, daemon.sock_or_pipe_metadata, daemon-state.json, daemon.log, daemon.lock, and auth.token_when_tcp_enabled.

Optional Features

• Streaming is enabled for run output via --stream, with YAML multi-doc and NDJSON framing.
• REPL is enabled as a local session console. REPL help remains plain text only and the default REPL presentation is human-oriented.
• Package-local packaging-ready metadata or support fixtures may be added by a supported capability later, but repository-owned CI workflows and release automation are not copied into generated skill packages by default.

Errors

Structured errors preserve the selected output format and include at least stable code and message fields.

Example structured error (--format json):

{
  "code": "run.missing_input",
  "message": "the run command requires <INPUT>; use --help for man-like human-readable help",
  "source": "leaf_validation",
  "format": "json"
}

Examples

Human-readable discovery:

$ acp-agent-cli
NAME
  acp-agent-cli - Full-function ACP CLI for developers and automation, exposing the complete ACP protocol surface and an integrated agent registry for discovering, managing, and installing ACP agents through one unified command-line workflow.

--help discovery:

$ acp-agent-cli run --help
NAME
  acp-agent-cli run - Execute the generated leaf command

Structured help:

$ acp-agent-cli help session prompt --format yaml

Persist Active Context:

$ acp-agent-cli context use --workspace /tmp/demo --session local-1 --selector provider=staging

Run with daemon routing:

$ acp-agent-cli run demo-input --via daemon --ensure-daemon

Open the REPL:

$ acp-agent-cli repl --session local-1

Created: 2026-04-16