# 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](./tui.md) |
| `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](./mcp.md) |
| `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).

### channels login

```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](./channels/index.md) 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](./channels/index.md#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)](./tui.md)**.

---

## 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](./gateway.md)).

### Force Start

If port is already in use:

```bash
xopc gateway --force
```

This will:
1. Send SIGTERM to processes on the port
2. Wait 700ms for graceful shutdown
3. Send SIGKILL if still running
4. 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](./mcp.md) for configuration and Web UI, and [MCP CLI & API](./cli/mcp.md) 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](image-multimodal.md).

---

## 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
```
