CLI Commands

All commands are invoked as openacp <command> [subcommand] [options]. Every command accepts -h / --help for inline help.

JSON Output

Many commands accept a --json flag for machine-readable output. When --json is passed:

Output is a single line of valid JSON on stdout
Exit code 0 for success, non-zero for errors
All progress indicators and ANSI codes are suppressed

Success envelope (exit 0):

{ "success": true, "data": { ... } }

Error envelope (exit non-zero):

{ "success": false, "error": { "code": "ERROR_CODE", "message": "Human-readable description" } }

Commands that support --json are noted in their options tables below.

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

Flag

Description

--cwd <path>

Working directory for the session (default: current directory)

--channel <name>

Target channel adapter, e.g. telegram, discord (default: first registered)

--json

Output result as JSON

Examples

openacp adopt claude abc123-def456
openacp adopt claude abc123 --cwd /path/to/project
openacp adopt claude abc123 --channel discord
openacp adopt claude abc123 --json

JSON output (data shape):

{ "sessionId": "...", "threadId": "...", "agent": "claude", "status": "active" }

attach

Connects to a running daemon and displays live status with log tailing. Useful for monitoring a daemon instance without opening a separate terminal.

Usage

openacp attach

Shows the daemon's current status (uptime, sessions, adapters, tunnel) and tails the log file. Press Ctrl+C to detach.

agents

Browse and manage AI coding agents from the ACP Registry.

Usage

openacp agents [subcommand]

agents (no subcommand)

Lists all installed agents and agents available to install from the registry.

Example

openacp agents
openacp agents --json

JSON output (data shape):

{ "agents": [{ "key": "claude", "name": "Claude Code", "version": "1.0.0", "distribution": "npm", "description": "...", "installed": true, "available": true, "missingDeps": [] }] }

agents install

Installs an agent from the ACP Registry. Automatically installs the handoff integration if the agent supports it.

openacp agents install <name> [--force] [--json]

Flag

Description

--force

Reinstall even if already installed

--json

Output result as JSON

openacp agents install claude
openacp agents install gemini --force
openacp agents install claude --json

JSON output (data shape):

{ "key": "claude", "version": "1.0.0", "installed": true }

agents uninstall

Removes an installed agent and its handoff integration (if any).

openacp agents uninstall <name> [--json]

Flag

Description

--json

Output result as JSON

openacp agents uninstall gemini
openacp agents uninstall gemini --json

JSON output (data shape):

{ "key": "gemini", "uninstalled": true }

agents info

Shows version, distribution type, command, setup steps, and installation status for an agent.

openacp agents info <name> [--json]

Flag

Description

--json

Output result as JSON

openacp agents info cursor
openacp agents info claude
openacp agents info claude --json

JSON output (data shape):

{ "key": "claude", "name": "Claude Code", "version": "1.0.0", "distribution": "npm", "description": "...", "installed": true, "binaryPath": "/usr/local/bin/claude", "command": "claude", "registryId": "claude" }

agents run

Runs the agent's CLI directly (useful for first-run login and configuration). ACP-specific flags are automatically stripped before passing arguments.

openacp agents run <name> [-- <args>]

Use -- to separate OpenACP flags from agent-specific arguments.

openacp agents run gemini          # Login to Google (first run)
openacp agents run copilot         # Login to GitHub Copilot
openacp agents run cline           # Configure API keys

agents refresh

Force-refreshes the agent catalog from the ACP Registry, bypassing the normal staleness check.

openacp agents refresh

api

Interacts with a running OpenACP daemon over the local REST API. Requires a running daemon (openacp start).

All api subcommands support --json for machine-readable output.

Usage

openacp api <subcommand> [args] [--json]

api cancel

Cancels a session.

openacp api cancel <session-id>

api cleanup

Deletes finished topics from channel adapters.

openacp api cleanup [--status <statuses>]

--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.

openacp api config
openacp api config set <key> <value>

api bypass

Enables or disables bypass permissions for a session. When enabled, the agent runs destructive commands without confirmation prompts.

openacp api bypass <session-id> on|off

api delete-topic

Deletes a topic for a given session ID.

openacp api delete-topic <session-id> [--force]

--force deletes even if the session is currently active.

api health

Shows system health: status, uptime, version, memory, session counts, adapters, and tunnel status.

openacp api health

api new

Creates a new session.

openacp api new [agent] [workspace]
openacp api new [agent] --workspace <path>

Both agent and workspace are optional. Uses defaultAgent and workspace.baseDir from config if omitted.

openacp api new
openacp api new claude /path/to/project
openacp api new gemini --workspace /path/to/project

api notify

Sends a notification message to all registered channel adapters.

openacp api notify <message>

All remaining arguments are joined into the message.

openacp api notify "Deployment complete"

api restart

Sends a restart signal to the running daemon.

openacp api restart

api send

Sends a prompt to a session. The prompt is enqueued; responses arrive asynchronously via the channel adapter.

openacp api send <session-id> <prompt>

All arguments after <session-id> are joined as the prompt.

openacp api send abc123 "Fix the login bug"
openacp api send abc123 refactor the auth module

api session

Shows detailed information about one session.

openacp api session <session-id>

api status

Lists all active sessions with ID, agent, status, and name.

openacp api status

api topics

Lists topics across all channel adapters.

openacp api topics [--status <statuses>]

--status accepts a comma-separated filter (e.g. active,finished).

api tunnel

Shows tunnel status (provider, URL).

openacp api tunnel

api version

Shows the version of the currently running daemon.

openacp api version

dev

Runs OpenACP with a local plugin loaded in development mode. Compiles TypeScript automatically, starts tsc --watch for hot-reload, and boots the server with the plugin.

Usage

openacp dev <plugin-path> [options]

Options

Flag

Description

--no-watch

Disable file watching (no hot-reload)

--verbose

Enable verbose logging

Examples

openacp dev ./my-plugin
openacp dev ../adapter-matrix --no-watch
openacp dev ./my-plugin --verbose

See Dev Mode for the full guide.

config

Views and edits configuration. Works with both a running and a stopped daemon.

Usage

openacp config
openacp config set <key> <value>

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. Supports --json for scripted use.

openacp config set defaultAgent claude
openacp config set security.maxConcurrentSessions 5
openacp config set channels.telegram.botToken "123:ABC"
openacp config set defaultAgent gemini --json

JSON output for config set (data shape):

{ "path": "defaultAgent", "value": "gemini", "needsRestart": false }

doctor

Runs system diagnostics. Checks config validity, agent availability, dependencies, and connectivity. Fixable issues can be auto-repaired interactively.

Usage

openacp doctor [--dry-run] [--json]

Flag

Description

--dry-run

Report issues only; do not apply any fixes

--json

Output result as JSON (implies --dry-run; always exits 0 — check summary.failed for health)

JSON output (data shape):

{
  "categories": [{ "name": "Config", "results": [{ "status": "pass", "message": "Config is valid" }] }],
  "summary": { "passed": 5, "warnings": 1, "failed": 0 }
}

install

Installs a plugin from npm into ~/.openacp/plugins/. Supports built-in plugins, community npm packages, and pinning a specific version with @version syntax.

Usage

openacp install <package>[@version] [--json]

Flag

Description

--json

Output result as JSON

openacp install @openacp/adapter-discord
openacp install @myorg/[email protected]
openacp install @openacp/adapter-discord --json

JSON output (data shape):

{ "plugin": "@openacp/adapter-discord", "version": "1.0.0", "installed": true }

This is an alias for openacp plugin add. See plugin install for details.

integrate

Manages agent integrations that enable features like session handoff from an agent to OpenACP.

Usage

openacp integrate <agent>
openacp integrate <agent> --uninstall

openacp integrate claude
openacp integrate claude --uninstall
openacp integrate opencode

logs

Tails the daemon log file (last 50 lines, then follows new output). Equivalent to tail -f. Press Ctrl+C to stop.

Usage

openacp logs

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

openacp onboard

plugin create

Scaffolds a new OpenACP plugin project with all boilerplate: TypeScript config, test setup, lifecycle hooks, and package.json.

Usage

openacp plugin create

Runs an interactive wizard that prompts for:

Plugin name (npm package name, e.g. @myorg/my-plugin)
Description
Author
License

Creates a directory with src/index.ts, src/__tests__/index.test.ts, package.json, tsconfig.json, CLAUDE.md (AI agent context), PLUGIN_GUIDE.md (developer guide), and config files.

Example

openacp plugin create
# Follow prompts, then:
cd my-plugin
npm install
npm run build
npm test

See Getting Started: Your First Plugin for a full walkthrough.

plugin install

Installs a plugin package. Works with both built-in plugins and community plugins published to npm. Supports @version syntax to pin a specific version. After npm install, checks the plugin's engines.openacp field and warns if the installed CLI version is older than the minimum required.

Usage

openacp plugin add <package>[@version] [--json]
openacp plugin install <package>[@version] [--json]

Flag

Description

--json

Output result as JSON

Examples

openacp plugin add @openacp/adapter-discord
openacp plugin add @myorg/[email protected]
openacp plugin install my-plugin
openacp plugin add @openacp/adapter-discord --json

JSON output (data shape):

{ "plugin": "@openacp/adapter-discord", "version": "1.0.0", "installed": true }

Community plugins are installed via npm install into ~/.openacp/plugins/node_modules/. The plugin's install() hook is called if defined.

plugin configure

Runs the configuration flow for an installed plugin. Calls the plugin's configure() hook, which typically presents interactive prompts to update settings.

Usage

openacp plugin configure <name>

Example

openacp plugin configure @myorg/translator

plugin enable / disable

Enables or disables an installed plugin without removing it. Disabled plugins are skipped during server startup.

Usage

openacp plugin enable <name> [--json]
openacp plugin disable <name> [--json]

Flag

Description

--json

Output result as JSON

Examples

openacp plugin disable @myorg/translator
openacp plugin enable @myorg/translator
openacp plugin enable @myorg/translator --json

JSON output (data shape):

{ "plugin": "@myorg/translator", "enabled": true }

remote

Generates access links for connecting app clients to a running OpenACP instance. Displays local URL, tunnel URL (if enabled), app deep link, and a QR code.

Usage

openacp remote [--json]

Flag

Description

--json

Output result as JSON (no QR code printed)

The generated link includes a single-use access code valid for 30 minutes. The app exchanges this code for a JWT token on first use.

Example output

Local:   http://127.0.0.1:21420
Tunnel:  https://abc.trycloudflare.com
App:     openacp://connect?host=abc.trycloudflare.com&code=xyz123

[QR code]

JSON output (data shape):

{ "code": "xyz123", "name": "my-instance", "role": "owner", "expiresAt": "2026-04-02T13:00:00Z", "urls": { "local": "http://127.0.0.1:21420", "tunnel": "https://abc.trycloudflare.com", "app": "openacp://connect?host=abc.trycloudflare.com&code=xyz123" } }

See App Connectivity for the full guide.

plugins

Lists all plugins installed in ~/.openacp/plugins/.

Usage

openacp plugins [--json]

Flag

Description

--json

Output result as JSON

JSON output (data shape):

{ "plugins": [{ "name": "@openacp/adapter-discord", "version": "1.0.0", "enabled": true, "source": "npm", "description": "Discord adapter" }] }

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

openacp reset

Prompts for confirmation before proceeding.

restart

Restarts the daemon. By default uses the same run mode as configured; use --foreground or --daemon to override.

Usage

openacp restart [--foreground | --daemon] [--json]

Flag

Description

--foreground

Restart in foreground mode (not compatible with --json)

--daemon

Restart as background daemon

--json

Output result as JSON (always uses daemon mode)

openacp restart
openacp restart --daemon --json

JSON output (data shape):

{ "pid": 12345, "instanceId": "global", "dir": "/Users/alice/.openacp" }

start

Starts OpenACP. Requires an existing config (run openacp first to set up).

Usage

openacp start [options]

Options

Flag

Description

--foreground

Force foreground mode regardless of config

--daemon

Force daemon mode regardless of config

--local

Use local .openacp/ instance in the current directory

--global

Use the global ~/.openacp/ instance

--dir <path>

Use a specific instance directory

--name <id>

Give the instance a name

--from <source>

Clone settings from an existing instance

--json

Output result as JSON

JSON output (data shape):

{ "pid": 12345, "instanceId": "global", "dir": "/Users/alice/.openacp" }

status

Shows whether the OpenACP daemon is running and its PID.

Usage

openacp status [--all] [--id <id>] [--json]

Flag

Description

--all

Show status of all registered instances, not just the current one

--id <id>

Show status of a specific instance

--json

Output result as JSON

JSON output (data shape — all instances):

{ "instances": [{ "id": "global", "name": "my-instance", "status": "running", "pid": 12345, "dir": "/Users/alice/.openacp", "mode": "daemon", "channels": ["telegram"], "apiPort": 21420, "tunnelPort": null }] }

JSON output (data shape — single instance with --id):

{ "id": "global", "name": "my-instance", "status": "running", "pid": 12345, "dir": "/Users/alice/.openacp", "mode": "daemon", "channels": ["telegram"], "apiPort": 21420, "tunnelPort": null }

stop

Sends a stop signal to the running daemon.

Usage

openacp stop [--json]

Flag

Description

--json

Output result as JSON

JSON output (data shape):

{ "stopped": true, "pid": 12345 }

tunnel

Manages tunnels to local ports. Requires a running daemon.

Usage

openacp tunnel <subcommand> [args]

tunnel add

Creates a tunnel to a local port.

openacp tunnel add <port> [--label <name>] [--session <id>] [--json]

Flag

Description

--json

Output result as JSON

openacp tunnel add 3000
openacp tunnel add 8080 --label "dev server"
openacp tunnel add 3000 --json

JSON output (data shape):

{ "port": 3000, "publicUrl": "https://abc.trycloudflare.com" }

tunnel list

Lists all active tunnels with their ports, labels, and public URLs.

openacp tunnel list [--json]

Flag

Description

--json

Output result as JSON

JSON output (data shape):

{ "tunnels": [{ "port": 3000, "label": "dev server", "publicUrl": "https://abc.trycloudflare.com", "status": "active" }] }

tunnel stop

Stops the tunnel for a specific local port.

openacp tunnel stop <port> [--json]

Flag

Description

--json

Output result as JSON

JSON output (data shape):

{ "port": 3000, "stopped": true }

tunnel stop-all

Stops all user tunnels.

openacp tunnel stop-all [--json]

Flag

Description

--json

Output result as JSON

JSON output (data shape):

{ "stopped": true }

uninstall

Removes an adapter plugin.

Usage

openacp uninstall <package> [--json]

Flag

Description

--json

Output result as JSON

openacp uninstall @openacp/adapter-discord
openacp uninstall @openacp/adapter-discord --json

JSON output (data shape):

{ "plugin": "@openacp/adapter-discord", "uninstalled": true }

update

Checks npm for the latest version of @openacp/cli and installs it if an update is available.

Usage

openacp update

(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.

If a daemon is already running, openacp shows a rich status display with an interactive menu instead of an error:

r — restart the daemon
f — restart in foreground mode
s — show full status
l — tail logs
q — quit

The startup display also shows which instance is active (global vs. local) and prints hints when a local instance is available but the global is being used.

openacp --foreground forces foreground mode regardless of config.

version

Prints the installed version. Also available as --version / -v.

Usage

openacp version [--json]
openacp --version

Flag

Description

--json

Output result as JSON

openacp --version
openacp version --json

JSON output (data shape):

{ "version": "2026.401.1" }

--help / -h

Prints the top-level help message listing all commands.

openacp --help

PreviousOverview NextREST API

Last updated 17 hours ago

Was this helpful?

Good morning

hashtagJSON Output

hashtagadopt

hashtagattach

hashtagagents

hashtagagents (no subcommand)

hashtagagents install

hashtagagents uninstall

hashtagagents info

hashtagagents run

hashtagagents refresh

hashtagapi

hashtagapi cancel

hashtagapi cleanup

hashtagapi config

hashtagapi bypass

hashtagapi delete-topic

hashtagapi health

hashtagapi new

hashtagapi notify

hashtagapi restart

hashtagapi send

hashtagapi session

hashtagapi status

hashtagapi topics

hashtagapi tunnel

hashtagapi version

hashtagdev

hashtagconfig

hashtagdoctor

hashtaginstall

hashtagintegrate

hashtaglogs

hashtagonboard

hashtagplugin create

hashtagplugin install

hashtagplugin configure

hashtagplugin enable / disable

hashtagremote

hashtagplugins

hashtagreset

hashtagrestart

hashtagstart

hashtagstatus

hashtagstop

hashtagtunnel

hashtagtunnel add

hashtagtunnel list

hashtagtunnel stop

hashtagtunnel stop-all

hashtaguninstall

hashtagupdate

hashtag(no command / --foreground)

hashtagversion

hashtag--help / -h

JSON Output

adopt

attach

agents

agents (no subcommand)

agents install

agents uninstall

agents info

agents run

agents refresh

api

api cancel

api cleanup

api config

api bypass

api delete-topic

api health

api new

api notify

api restart

api send

api session

api status

api topics

api tunnel

api version

dev

config

doctor

install

integrate

logs

onboard

plugin create

plugin install

plugin configure

plugin enable / disable

remote

plugins

reset

restart

start

status

stop

tunnel

tunnel add

tunnel list

tunnel stop

tunnel stop-all

uninstall

update

(no command / --foreground)

version

--help / -h