CLI Command Reference

xopc provides a rich set of CLI commands for management, conversation, and configuration.

Usage

Install from npm (recommended)

bash

npm install -g @xopcai/xopc
xopc <command>

Run from source (development)

bash

git clone https://github.com/xopcai/xopc.git
cd xopc
pnpm install

pnpm run dev -- <command>

Note: Examples in this document use xopc. If running from source, replace with pnpm run dev --.

Command Overview

Command	Description
`setup`	Initialize config and workspace
`onboard`	Interactive setup wizard
`channels`	Channel login (`channels login`) and DM pairing approval (`channels pairing approve`)
`agents`	Manage multi-agent entries in config (`list`, add, delete)
`agent`	Chat with Agent
`tui`	Full-screen terminal UI (gateway or `--local` embedded) — see TUI
`gateway`	Start REST gateway
`cron`	Manage scheduled tasks
`extension`	Manage extensions
`skills`	Manage skills
`mcp`	Manage MCP servers (`list`, `show`, `set`, `unset`, `serve`) — see MCP
`config`	View/edit configuration
`image`	Image understanding / generation defaults (`status`, `set-understanding`, `set-generation`, fallbacks, `providers`)
`session`	Manage sessions

setup

Initialize config file and workspace directory only.

bash

xopc setup

Parameters:

Parameter	Description
`--workspace <path>`	Workspace directory path

Examples:

bash

# Create default config and workspace
xopc setup

# Custom workspace path
xopc setup --workspace ~/my-workspace

What it does:

Creates ~/.xopc/xopc.json (if not exists)
Creates workspace directory with profile Markdown templates

For full state directory layout (agents, cron, logs, profile seeds), use xopc init instead.

init

Initialize the full xopc state tree (config, agents/<id>/, cron, logs, profile Markdown seeds).

bash

xopc init
xopc init --agent-id coder
xopc init --force

Option	Description
`--force`	Re-run initialization steps
`--skip-workspace`	Skip profile Markdown seed files
`--agent-id <id>`	Agent id to initialize (default: `main`)

profile

Manage isolated state profiles (~/.xopc for default, ~/.xopc-<name> otherwise). Switching profiles sets XOPC_PROFILE in your shell.

bash

xopc profile list
xopc profile create staging
xopc profile switch staging
xopc profile delete staging --force

onboard

Interactive setup wizard for xopc (gateway defaults: 127.0.0.1:18790, token auth; no prompts for bind/port/token).

bash

xopc onboard

Options:

Option	Description
`--model`	Configure LLM provider and model only
`--channels`	Configure messaging channels only
`--gateway`	Apply default gateway settings (quiet)
`--all`	Configure everything (default)

Examples:

bash

# Full interactive setup (default)
xopc onboard

# Configure LLM model only
xopc onboard --model

# Configure channels only
xopc onboard --channels

Features:

Auto-detects if workspace needs setup
Configure LLM provider and model
Configure messaging channels (Telegram, Weixin QR via channel menu, …)
Apply gateway defaults with auto-generated token when missing
At the end (interactive): choose Terminal UI (embedded) or Gateway (OS service) or exit

channels

Messaging channel login (QR / credentials flows) and DM pairing approval on the machine where you run the CLI (same host as the gateway when approving Feishu / Weixin pairing codes).

bash

xopc channels login
xopc channels login --channel weixin
xopc channels login --channel feishu
xopc channels login --channel feishu
xopc channels login --account <account-id>

See channel docs under Channels for what each integration expects.

channels pairing approve

When dmPolicy is pairing for Telegram, Feishu, or Weixin, unknown users get a one-time pairing code in chat. The bot owner approves it on the host:

bash

xopc channels pairing approve --channel telegram --account default AB12CD34
xopc channels pairing approve --channel feishu --account default AB12CD34
xopc channels pairing approve --channel feishu AB12CD34
xopc channels pairing approve --channel weixin AB12CD34

--channel: telegram | feishu | weixin (required).
--account: config account id (default: default when omitted).
<code>: 8-character code from the user’s DM.

On success, the sender id is appended to the channel allowFrom credential file (merged with config allowFrom at runtime). File layout is documented in Channels — DM pairing.

agents

Manage agents.list in config.json. Paths for workspace and ~/.xopc/agents/<id>/ follow the merged config — there is no separate env-based agent registry.

Subcommand	Description
`agents list`	Print configured agents and the resolved default agent id (`--json` supported).
`agents add <name>`	Requires `--workspace <dir>`. Appends/updates `agents.list`, creates dirs, seeds Markdown profile files. Optional: `--model`, `--agent-dir`.
`agents delete <id>`	Removes the agent from `list` and strips matching `bindings`. Add `--purge` to delete on-disk agent home and workspace (not allowed for `main`).

Examples:

bash

xopc agents list
xopc agents add coder --workspace ~/xopc-workspaces/coder --model anthropic/claude-sonnet-4-5
xopc agents delete coder
xopc agents delete coder --purge

agent

Chat with Agent.

Single Message

bash

xopc agent -m "Hello, world!"

Parameters:

Parameter	Description
`-m, --message`	Message to send
`-s, --session`	Session key (default: default)
`-i, --interactive`	Interactive mode

Interactive Mode

bash

xopc agent -i

Usage:

> Hello!
Bot: Hello! How can I help?

> List files
Bot: File listing...

> quit

Specify Session

bash

xopc agent -m "Continue our discussion" -s my-session

tui

Interactive terminal UI for chatting with the agent (streaming, tools, thinking). Built on @earendil-works/pi-tui.

Quick start:

bash

xopc tui                              # gateway mode (default URL in CLI; override with --url)
xopc tui --local                      # embedded AgentService, no gateway
xopc tui --url http://localhost:18790 --token <token>
xopc tui -s <sessionKey> -m "Hello"   # resume session + optional first message

Option	Description
`--url <url>`	Gateway base URL
`--token <token>`	Gateway bearer token
`-s, --session <key>`	Session key (default: `cli:tui`)
`-m, --message <text>`	Send once after connect
`--local`	Embedded mode (no gateway)
`--thinking <level>`	Thinking level override

Full behavior, slash commands, and keyboard shortcuts: Terminal UI (tui).

gateway

Start REST API gateway.

Foreground Mode (Default)

bash

xopc gateway --port 18790

The gateway runs in foreground mode by default. Press Ctrl+C to stop.

Parameters:

Parameter	Description
`-p, --port`	Port number (default: 18790)
`--bind <mode>`	Bind mode: `loopback`, `lan`, `auto`, `custom`, `tailnet` (default from config)
`--token`	Auth token
`--no-hot-reload`	Disable config hot reload
`--force`	Force kill existing process on port

For an OS-managed gateway, use xopc gateway service install (see Gateway).

Force Start

If port is already in use:

bash

xopc gateway --force

This will:

Send SIGTERM to processes on the port
Wait 700ms for graceful shutdown
Send SIGKILL if still running
Start new gateway instance

Subcommands

Subcommand	Description
`gateway status`	Check gateway status
`gateway stop`	Stop running gateway
`gateway restart`	Restart gateway
`gateway logs`	View gateway logs
`gateway token`	View/generate auth token
`gateway service`	Install/start/stop OS service (`install`, `start`, `stop`, `restart`, `uninstall`)

Examples:

bash

# Check status
xopc gateway status

# Stop gateway (graceful)
xopc gateway stop

# Restart gateway
xopc gateway restart

# View last 50 lines
xopc gateway logs

# Follow logs in real-time
xopc gateway logs --follow

# Generate new token
xopc gateway token --generate

# Install and start as system service
xopc gateway service install
xopc gateway service start

cron

Manage scheduled tasks.

Add Task

bash

xopc cron add --schedule "0 9 * * *" --message "Good morning!"

Parameters:

Parameter	Description
`--schedule`	Cron expression
`--message`	Message to send
`--name`	Task name (optional)

Examples:

bash

# Daily at 9am
xopc cron add --schedule "0 9 * * *" --message "Daily update"

# Weekdays at 6pm
xopc cron add --schedule "0 18 * * 1-5" --message "Time to wrap up!"

# Hourly reminder
xopc cron add --schedule "0 * * * *" --message "Hourly reminder" --name hourly

Remove Task

bash

xopc cron remove <task-id>

Enable/Disable

bash

xopc cron enable <task-id>
xopc cron disable <task-id>

Trigger Task

bash

xopc cron run <task-id>
# alias:
xopc cron trigger <task-id>

extensions

Manage extensions. Installed extensions live under ~/.xopc/extensions; discovery still follows workspace → global → bundled priority.

List Extensions

bash

xopc extensions list
xopc extensions list --json

Install Extension

bash

# Install from npm (always under ~/.xopc/extensions)
xopc extensions install xopc-extension-telegram

# Install from local directory
xopc extensions install ./my-local-extension

# Install from xopc-store only
xopc extensions install --store telegram

Parameters:

Parameter	Description
`--store`	Install from xopc-store only
`--npm`	Install from npm only
`-f, --force`	Replace an existing store/local install

Health, Audit, and Verify

bash

xopc extensions health
xopc extensions audit
xopc extensions verify [extension-id]

Search, Update, and Freeze

bash

xopc extensions search [keyword]
xopc extensions update [extension-id]
xopc extensions freeze

Develop, Package, and Publish

bash

xopc extensions dev ./my-local-extension
xopc extensions pack ./my-local-extension
xopc extensions publish ./my-local-extension --dry-run

skills

Manage skills (install, enable, configure, test).

List Skills

bash

xopc skills list
xopc skills list -v          # Verbose output
xopc skills list --json      # JSON format

Install Skill Dependencies

bash

xopc skills install <skill-name>
xopc skills install <skill-name> -i <install-id>   # Specify installer
xopc skills install <skill-name> --dry-run         # Dry run

Enable/Disable Skills

bash

xopc skills enable <skill-name>
xopc skills disable <skill-name>

View Skill Status

bash

xopc skills status
xopc skills status <skill-name>
xopc skills status --json

Security Audit

bash

xopc skills audit
xopc skills audit <skill-name>
xopc skills audit <skill-name> --deep    # Verbose output

Configure Skill

bash

xopc skills config <skill-name> --show
xopc skills config <skill-name> --api-key=KEY
xopc skills config <skill-name> --env KEY=value

Test Skill

bash

# Test all skills
xopc skills test

# Test specific skill
xopc skills test <skill-name>

# Verbose output
xopc skills test --verbose

# JSON format
xopc skills test --format json

# Skip specific tests
xopc skills test --skip-security
xopc skills test --skip-examples

mcp

Manage outbound MCP servers and run the inbound channel bridge.

bash

xopc mcp list
xopc mcp show fetch
xopc mcp set fetch '{"command":"npx","args":["-y","@modelcontextprotocol/server-fetch"]}'
xopc mcp unset fetch

# Inbound stdio bridge → gateway
xopc mcp serve --url http://127.0.0.1:18790 --token-file ~/.xopc/gateway.token

See MCP for configuration and Web UI, and MCP CLI & API for flags and REST endpoints.

session

Manage conversation sessions.

List Sessions

bash

# List all sessions
xopc session list

# Filter by status
xopc session list --status active
xopc session list --status archived
xopc session list --status pinned

# Search by name or content
xopc session list --query "project"

# Sort and limit
xopc session list --sort updatedAt --order desc --limit 50

View Session Details

bash

# Show session info and recent messages
xopc session info telegram:123456

# Search within a session
xopc session grep telegram:123456 "API design"

Manage Sessions

bash

# Rename a session
xopc session rename telegram:123456 "Project Discussion"

# Add tags
xopc session tag telegram:123456 work important

# Remove tags
xopc session untag telegram:123456 important

# Archive a session
xopc session archive telegram:123456

# Unarchive a session
xopc session unarchive telegram:123456

# Pin a session
xopc session pin telegram:123456

# Unpin a session
xopc session unpin telegram:123456

# Delete a session
xopc session delete telegram:123456

# Export session to JSON
xopc session export telegram:123456 --format json --output backup.json

Statistics

bash

xopc session stats

config

View and edit configuration (non-interactive).

Show Configuration

bash

xopc config show
# legacy alias:
xopc config --show

Validate Configuration

bash

xopc config validate
# legacy alias:
xopc config --validate

Edit values with xopc config set / xopc config unset, or open the file path from xopc config path in your editor.

image

Manage agents.defaults.imageModel, imageGenerationModel, mediaMaxMb, and their fallback lists without editing JSON paths by hand.

bash

xopc image status
xopc image status --json
xopc image set-understanding openai/gpt-4o
xopc image set-generation openai/gpt-image-1
xopc image add-fallback understanding anthropic/claude-sonnet-4-5
xopc image add-fallback generation dashscope/wan2.6-t2i
xopc image remove-fallback understanding 0
xopc image providers
xopc image set-max-size 10

See Image & vision.

Global Options

Workspace Path

bash

--workspace /path/to/workspace

Config File

bash

--config /path/to/config.json

Verbose Output

bash

--verbose

Help

bash

xopc --help
xopc agent --help
xopc gateway --help

Exit Codes

Exit Code	Description
`0`	Success
`1`	General error
`2`	Invalid arguments
`3`	Configuration error

Quick Scripts

Create a quick script bot:

bash

#!/bin/bash

case "$1" in
  chat)
    xopc agent -m "${*:2}"
    ;;
  shell)
    xopc agent -i
    ;;
  start)
    xopc gateway --port 18790
    ;;
  cron)
    shift
    xopc cron "$@"
    ;;
  extensions)
    shift
    xopc extensions "$@"
    ;;
  skills)
    shift
    xopc skills "$@"
    ;;
  session)
    shift
    xopc session "$@"
    ;;
  *)
    echo "Usage: bot {chat|shell|start|cron|extension|skills|session}"
    ;;
esac

Usage:

bash

bot chat Hello!
bot start
bot cron list
bot extension list
bot skills list
bot session list

CLI Command Reference ​

Usage ​

Install from npm (recommended) ​

Run from source (development) ​

Command Overview ​

setup ​

init ​

profile ​

onboard ​

channels ​

channels login ​

channels pairing approve ​

agents ​

agent ​

Single Message ​

Interactive Mode ​

Specify Session ​

tui ​

gateway ​

Foreground Mode (Default) ​

Force Start ​

Subcommands ​

cron ​

Add Task ​

Remove Task ​

Enable/Disable ​

Trigger Task ​

extensions ​

List Extensions ​

Install Extension ​

Health, Audit, and Verify ​

Search, Update, and Freeze ​

Develop, Package, and Publish ​

skills ​

List Skills ​

Install Skill Dependencies ​

Enable/Disable Skills ​

View Skill Status ​

Security Audit ​

Configure Skill ​

Test Skill ​

mcp ​

session ​

List Sessions ​

View Session Details ​

Manage Sessions ​

Statistics ​

config ​

Show Configuration ​

Validate Configuration ​

image ​

Global Options ​

Workspace Path ​

Config File ​

Verbose Output ​

Help ​

Exit Codes ​

Quick Scripts ​

CLI Command Reference

Usage

Install from npm (recommended)

Run from source (development)

Command Overview

setup

init

profile

onboard

channels

channels login

channels pairing approve

agents

agent

Single Message

Interactive Mode

Specify Session

tui

gateway

Foreground Mode (Default)

Force Start

Subcommands

cron

Add Task

Remove Task

Enable/Disable

Trigger Task

extensions

List Extensions

Install Extension

Health, Audit, and Verify

Search, Update, and Freeze

Develop, Package, and Publish

skills

List Skills

Install Skill Dependencies

Enable/Disable Skills

View Skill Status

Security Audit

Configure Skill

Test Skill

mcp

session

List Sessions

View Session Details

Manage Sessions

Statistics

config

Show Configuration

Validate Configuration

image

Global Options

Workspace Path

Config File

Verbose Output

Help

Exit Codes

Quick Scripts