CLI Overview

The cpk binary is a CLI that either talks to the local coordination daemon (for task/board/docs commands) or reads the project’s SQLite database directly (for code intelligence commands). Commands are ~200-250 tokens per call.

Command tree

cpk
├── server
│   ├── start          Start the coordination server daemon
│   ├── stop           Stop the running server
│   ├── status         Check server health and port
│   └── logs           Show server logs
│
├── init               Initialize a project in the current directory
│
│   # Code intelligence (offline, no server needed)
├── scan               Parse the codebase and index symbols/imports
│   ├── --incremental   Only scan files changed since the staged index
│   ├── --install-hook  Install a pre-commit git hook for auto-updates
│   └── --remove-hook   Remove the pre-commit git hook
├── code
│   ├── symbols        Find symbols by name, kind, file, or export
│   ├── imports <file> What a file imports
│   ├── dependents <f> Who imports a file (impact analysis)
│   └── summary        Project overview: files, symbols, languages
│
│   # Task coordination (needs cpk server running)
├── task
│   ├── add            Create a new task
│   ├── list           List tasks with optional filters
│   ├── show <id>      Show full task details
│   ├── update <id>    Update task fields (status, priority, assignee, etc.)
│   ├── mine           List tasks assigned to the current agent
│   ├── pickup         Claim the next available task (atomic)
│   ├── done <id>      Mark a task complete (moves to review)
│   ├── block <id>     Mark a task blocked
│   └── unblock <id>   Remove a block (returns to open)
│
├── agent
│   └── list           List all agents (auto-populated from interactions)
│
├── board
│   └── status         Show board health overview
│
├── docs
│   ├── write          Write a document to the knowledge base
│   ├── search <query> Search the knowledge base
│   ├── list           List all documents
│   └── read <id>      Read full document content
│
├── generate           Generate .codepakt/AGENTS.md + .codepakt/CLAUDE.md
│
└── config
    ├── show           Display current configuration
    └── set <key> <value>  Set a configuration value

Two execution modes

Command group	Needs server?	How it works
cpk scan, cpk code *	No	Reads/writes .codepakt/data.db directly via SQLite
cpk task *, cpk board *, cpk agent *, cpk docs *	Yes	HTTP calls to the daemon on port 41920
cpk init, cpk generate, cpk config *	Mixed	init registers the project locally; generate writes template files; config reads local JSON
cpk server *	—	Manages the daemon itself

Code intelligence works offline because queries and scans are against a single local SQLite file. Task coordination needs the server for atomic pickup across concurrent agents (BEGIN IMMEDIATE transactions).

Environment variables

Variable	Required	Description
CPK_AGENT	For task pickup/done/block/mine	Agent name. Alternative to --agent flag. Set this at the start of each agent session.
CPK_PORT	No	Override the default server port (41920). Must be set before starting the server and in all CLI calls that follow.

export CPK_AGENT=backend
export CPK_PORT=8080

CPK_AGENT (or --agent flag) is required for: task pickup, task mine, task done, task block.

It is optional but recorded for: docs write.

It is not used for: server *, init, task add, task list, task show, task unblock, agent *, board *, config *, version.

Project configuration

Running cpk init creates .codepakt/config.json in the current directory:

{
  "url": "http://localhost:41920",
  "project_id": "proj_abc123"
}

Key	Description
url	Server URL. Change this when pointing at a remote server.
project_id	Active project. Set automatically by cpk init.

The CLI looks for .codepakt/config.json in the current directory, then walks up the directory tree until it finds one or reaches the filesystem root.

Change config values with cpk config set:

cpk config set url http://192.168.1.10:41920

Output format

All commands output JSON by default. Use --human for human-readable output. Errors print to stderr with a non-zero exit code.

Use cpk --version to print the installed version.

Reference pages

• cpk scan — code intelligence scanner, git hook installation, incremental updates
• cpk code — querying symbols, imports, dependents, and project summary
• cpk server — starting, stopping, and checking the daemon
• cpk task — full task command reference
• cpk agent — list agents
• cpk board — board health overview
• cpk docs — knowledge base commands
• cpk generate — generate coordination files (.codepakt/AGENTS.md + .codepakt/CLAUDE.md)
• cpk config — configuration management