CLI

copaw is the command-line tool for CoPaw. This page is organized from "get-up-and-running" to "advanced management" — read from top to bottom if you're new, or jump to the section you need.

Not sure what "channels", "heartbeat", or "cron" mean? See Introduction first.

Getting started

These are the commands you'll use on day one.

copaw init

First-time setup. Walks you through configuration interactively.

copaw init              # Interactive setup (recommended for first time)
copaw init --defaults   # Non-interactive, use all defaults (good for scripts)
copaw init --force      # Overwrite existing config files

What the interactive flow covers (in order):

1. Heartbeat — interval (e.g. 30m), target (main / last), optional active hours.
2. Show tool details — whether tool call details appear in channel messages.
3. Language — zh or en for agent persona files (SOUL.md, etc.).
4. Channels — optionally configure iMessage / Discord / DingTalk / Feishu / QQ / Console.
5. LLM provider — select provider, enter API key, choose model (required).
6. Skills — enable all / none / custom selection.
7. Environment variables — optionally add key-value pairs for tools.
8. HEARTBEAT.md — edit the heartbeat checklist in your default editor.

copaw app

Start the CoPaw server. Everything else — channels, cron jobs, the Console UI — depends on this.

copaw app                             # Start on 127.0.0.1:8088
copaw app --host 0.0.0.0 --port 9090 # Custom address
copaw app --reload                    # Auto-reload on code change (dev)
copaw app --workers 4                 # Multi-worker mode
copaw app --log-level debug           # Verbose logging

Console

Once copaw app is running, open http://127.0.0.1:8088/ in your browser to access the Console — a web UI for chat, channels, cron, skills, models, and more. See Console for a full walkthrough.

If the frontend was not built, the root URL returns {"message": "Hello World"} but the API still works.

To build the frontend: in the project's console/ directory run npm ci && npm run build (output in console/dist/). Docker images and pip packages already include the Console.

Models & environment variables

Before using CoPaw you need at least one LLM provider configured. Environment variables power many built-in tools (e.g. web search).

copaw models

Manage LLM providers and the active model.

copaw models list                    # See what's configured
copaw models config                  # Full interactive setup
copaw models config-key modelscope   # Just set ModelScope's API key
copaw models config-key dashscope    # Just set DashScope's API key
copaw models config-key custom       # Set custom provider (Base URL + key)
copaw models set-llm                 # Change active model only

Local models

CoPaw can also run models locally via llama.cpp or MLX — no API key needed. Install the backend first: pip install 'copaw[llamacpp]' or pip install 'copaw[mlx]'.

# Download a model (auto-selects Q4_K_M GGUF)
copaw models download Qwen/Qwen3-4B-GGUF

# Download an MLX model
copaw models download Qwen/Qwen3-4B --backend mlx

# Download from ModelScope
copaw models download Qwen/Qwen2-0.5B-Instruct-GGUF --source modelscope

# List downloaded models
copaw models local
copaw models local --backend mlx

# Delete a downloaded model
copaw models remove-local <model_id>
copaw models remove-local <model_id> --yes   # skip confirmation

Ollama models

CoPaw integrates with Ollama to run models locally. Models are dynamically loaded from your Ollama daemon — install Ollama first from ollama.com.

Install the Ollama SDK: pip install 'copaw[ollama]' (or re-run the installer with --extras ollama)

# Download an Ollama model
copaw models ollama-pull mistral:7b
copaw models ollama-pull qwen3:8b

# List Ollama models
copaw models ollama-list

# Remove an Ollama model
copaw models ollama-remove mistral:7b
copaw models ollama-remove qwen3:8b --yes   # skip confirmation

# Use in config flow (auto-detects Ollama models)
copaw models config           # Select Ollama → Choose from model list
copaw models set-llm          # Switch to a different Ollama model

Key differences from local models:

• Models come from Ollama daemon (not downloaded by CoPaw)
• Use ollama-pull / ollama-remove instead of download / remove-local
• Model list updates dynamically when you add/remove via Ollama CLI or CoPaw

Note: You are responsible for ensuring the API key is valid. CoPaw does not verify key correctness. See Config — LLM Providers.

copaw env

Manage environment variables used by tools and skills at runtime.

copaw env list
copaw env set TAVILY_API_KEY "tvly-xxxxxxxx"
copaw env set GITHUB_TOKEN "ghp_xxxxxxxx"
copaw env delete TAVILY_API_KEY

Note: CoPaw only stores and loads these values; you are responsible for ensuring they are correct. See Config — Environment Variables.

Channels

Connect CoPaw to messaging platforms.

copaw channels

Manage channel configuration (iMessage, Discord, DingTalk, Feishu, QQ, Console, etc.). Note: Use config for interactive setup (no configure subcommand); use remove to uninstall custom channels (no uninstall).

copaw channels list                    # See current status
copaw channels install my_channel      # Create custom channel stub
copaw channels install my_channel --path ./my_channel.py
copaw channels add dingtalk            # Add DingTalk to config
copaw channels remove my_channel       # Remove custom channel (and from config by default)
copaw channels remove my_channel --keep-config   # Remove module only, keep config entry
copaw channels config                 # Interactive configuration

The interactive config flow lets you pick a channel, enable/disable it, and enter credentials. It loops until you choose "Save and exit".

For platform-specific credential setup, see Channels.

Cron (scheduled tasks)

Create jobs that run on a timed schedule — "every day at 9am", "every 2 hours ask CoPaw and send the reply". Requires copaw app to be running.

copaw cron

Creating jobs

Option 1 — CLI arguments (simple jobs)

Two task types:

• text — send a fixed message to a channel on schedule.
• agent — ask CoPaw a question on schedule and deliver the reply.

# Text: send "Good morning!" to DingTalk every day at 9:00
copaw cron create \
  --type text \
  --name "Daily 9am" \
  --cron "0 9 * * *" \
  --channel dingtalk \
  --target-user "your_user_id" \
  --target-session "session_id" \
  --text "Good morning!"

# Agent: every 2 hours, ask CoPaw and forward the reply
copaw cron create \
  --type agent \
  --name "Check todos" \
  --cron "0 */2 * * *" \
  --channel dingtalk \
  --target-user "your_user_id" \
  --target-session "session_id" \
  --text "What are my todo items?"

Required: --type, --name, --cron, --channel, --target-user, --target-session, --text.

Option 2 — JSON file (complex or batch)

copaw cron create -f job_spec.json

JSON structure matches the output of copaw cron get <job_id>.

Additional options

Cron expression cheat sheet

Five fields: minute hour day month weekday (no seconds).

Chats (sessions)

Manage chat sessions via the API. Requires copaw app to be running.

copaw chats

copaw chats list
copaw chats list --user-id alice --channel dingtalk
copaw chats get 823845fe-dd13-43c2-ab8b-d05870602fd8
copaw chats create --session-id "discord:alice" --user-id alice --name "My Chat"
copaw chats create -f chat.json
copaw chats update <chat_id> --name "Renamed"
copaw chats delete <chat_id>

Skills

Extend CoPaw's capabilities with skills (PDF reading, web search, etc.).

copaw skills

copaw skills list     # See what's available
copaw skills config   # Toggle skills on/off interactively

In the interactive UI: ↑/↓ to navigate, Space to toggle, Enter to confirm. A preview of changes is shown before applying.

For built-in skill details and custom skill authoring, see Skills.

Maintenance

copaw clean

Remove everything under the working directory (default ~/.copaw).

copaw clean             # Interactive confirmation
copaw clean --yes       # No confirmation
copaw clean --dry-run   # Only list what would be removed

Global options

Every copaw subcommand inherits:

If the server runs on a non-default address, pass these globally:

copaw --host 0.0.0.0 --port 9090 cron list

Working directory

All config and data live in ~/.copaw by default: config.json, HEARTBEAT.md, jobs.json, chats.json, skills, memory, and agent persona files.

See Config & Working Directory for full details.

Command overview

Related pages

• Introduction — What CoPaw can do
• Console — Web-based management UI
• Channels — DingTalk, Feishu, iMessage, Discord, QQ setup
• Heartbeat — Scheduled check-in / digest
• Skills — Built-in and custom skills
• Config & Working Directory — Working directory and config.json