CLI Overview — codepakt docs

The cpk binary is a thin HTTP client. Every command makes one or two requests to the codepakt server and prints the result. There’s no local state management, no caching, no background processes — just HTTP calls.

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
│
├── 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

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