CLI Commands
All commands are invoked as openacp <command> [subcommand] [options]. Every command accepts -h / --help for inline help.
adopt
Transfers an existing external agent session into OpenACP so it appears as a messaging thread. Requires a running daemon.
Usage
openacp adopt <agent> <session_id> [--cwd <path>] [--channel <name>]Options
--cwd <path>
Working directory for the session (default: current directory)
--channel <name>
Target channel adapter, e.g. telegram, discord (default: first registered)
Examples
openacp adopt claude abc123-def456
openacp adopt claude abc123 --cwd /path/to/project
openacp adopt claude abc123 --channel discordagents
Browse and manage AI coding agents from the ACP Registry.
Usage
agents (no subcommand)
Lists all installed agents and agents available to install from the registry.
Example
agents install
Installs an agent from the ACP Registry. Automatically installs the handoff integration if the agent supports it.
--force
Reinstall even if already installed
agents uninstall
Removes an installed agent and its handoff integration (if any).
agents info
Shows version, distribution type, command, setup steps, and installation status for an agent.
agents run
Runs the agent's CLI directly (useful for first-run login and configuration). ACP-specific flags are automatically stripped before passing arguments.
Use -- to separate OpenACP flags from agent-specific arguments.
agents refresh
Force-refreshes the agent catalog from the ACP Registry, bypassing the normal staleness check.
api
Interacts with a running OpenACP daemon over the local REST API. Requires a running daemon (openacp start).
Usage
api cancel
Cancels a session.
api cleanup
Deletes finished topics from channel adapters.
--status accepts a comma-separated list (e.g. finished,error). Defaults to finished topics.
api config
Shows or updates runtime config. Prefer openacp config for general use — it works whether the daemon is running or not.
api dangerous
Enables or disables dangerous mode for a session. When enabled, the agent runs destructive commands without confirmation prompts.
api delete-topic
Deletes a topic for a given session ID.
--force deletes even if the session is currently active.
api health
Shows system health: status, uptime, version, memory, session counts, adapters, and tunnel status.
api new
Creates a new session.
Both agent and workspace are optional. Uses defaultAgent and workspace.baseDir from config if omitted.
api notify
Sends a notification message to all registered channel adapters.
All remaining arguments are joined into the message.
api restart
Sends a restart signal to the running daemon.
api send
Sends a prompt to a session. The prompt is enqueued; responses arrive asynchronously via the channel adapter.
All arguments after <session-id> are joined as the prompt.
api session
Shows detailed information about one session.
api status
Lists all active sessions with ID, agent, status, and name.
api topics
Lists topics across all channel adapters.
--status accepts a comma-separated filter (e.g. active,finished).
api tunnel
Shows tunnel status (provider, URL).
api version
Shows the version of the currently running daemon.
config
Views and edits configuration. Works with both a running and a stopped daemon.
Usage
openacp config (no args) opens an interactive terminal editor. When the daemon is running, changes are applied live via the API; otherwise the config file is edited directly.
openacp config set applies a single value by dot-notation path. Values are JSON-parsed if possible, otherwise treated as strings.
doctor
Runs system diagnostics. Checks config validity, agent availability, dependencies, and connectivity. Fixable issues can be auto-repaired interactively.
Usage
--dry-run
Report issues only; do not apply any fixes
install
Installs an adapter plugin from npm into ~/.openacp/plugins/.
Usage
integrate
Manages agent integrations that enable features like session handoff from an agent to OpenACP.
Usage
logs
Tails the daemon log file (last 50 lines, then follows new output). Equivalent to tail -f. Press Ctrl+C to stop.
Usage
Log directory is configured via logging.logDir (default: ~/.openacp/logs/).
onboard
Runs the first-run setup wizard if no config exists. If config already exists, runs the reconfiguration wizard, which allows modifying or disabling individual channels, agents, workspace settings, run mode, and integrations. Individual sections (e.g. a specific channel) can be modified, disabled, or deleted without affecting the rest of the config.
Usage
plugins
Lists all plugins installed in ~/.openacp/plugins/.
Usage
reset
Deletes all OpenACP data (~/.openacp) and allows starting fresh. This is destructive — config, plugins, and agent data are removed. The daemon must be stopped first.
Usage
Prompts for confirmation before proceeding.
restart
There is no standalone restart command. Use openacp api restart to restart a running daemon, or stop and start it manually:
start
Starts OpenACP as a background daemon. Requires an existing config (run openacp first to set up).
Usage
status
Shows whether the OpenACP daemon is running and its PID.
Usage
stop
Sends a stop signal to the running daemon.
Usage
tunnel
Manages tunnels to local ports. Requires a running daemon.
Usage
tunnel add
Creates a tunnel to a local port.
tunnel list
Lists all active tunnels with their ports, labels, and public URLs.
tunnel stop
Stops the tunnel for a specific local port.
tunnel stop-all
Stops all user tunnels.
uninstall
Removes an adapter plugin.
Usage
update
Checks npm for the latest version of @openacp/cli and installs it if an update is available.
Usage
(no command / --foreground)
Running openacp with no arguments starts the server. On first run, the setup wizard launches. After setup, behavior depends on runMode in config:
foreground— runs in the current terminal.daemon— spawns a background process and exits.
openacp --foreground forces foreground mode regardless of config.
--version / -v
Prints the installed version.
--help / -h
Prints the top-level help message listing all commands.
Last updated
Was this helpful?