Codewalkers/docs/cli-config.md

CLI & Configuration

apps/server/cli/ — CLI commands, apps/server/config/ — workspace configuration, apps/server/bin/ — entry point.

Entry Point

apps/server/bin/cw.ts — hashbang entry that imports and runs the CLI.

CLI Framework

Uses Commander.js for command parsing.

Global Flags

• -s, --server — Start coordination server in foreground
• -p, --port <number> — Server port (default: 3847, env: CW_PORT)
• -d, --debug — Enable debug mode (archive agent workdirs before cleanup)

Commands

System

Command	Description
cw init	Create .cwrc workspace file in current directory
cw start	Start coordination server (see Server Wiring below)
cw stop	Stop running server (reads PID file, sends signal)
cw status	Query server health endpoint
cw id [-n count]	Generate nanoid(s) offline

Agent Management (cw agent)

Command	Description
spawn <prompt> --task <id> [--name] [--provider] [--initiative] [--cwd]	Spawn agent
stop <name>	Stop running agent
delete <name>	Delete agent, clean workdir/branches/logs
list	List all agents with status
get <name>	Agent details (ID, task, session, worktree, status)
resume <name> <answers>	Resume with JSON answers or single string
result <name>	Get execution result

Task Management (cw task)

Command	Description
list --parent|--phase|--initiative <id>	List tasks with counts
get <taskId>	Task details
status <taskId> <status>	Update status

Dispatch (cw dispatch)

Command	Description
queue <taskId>	Queue task for dispatch
next	Dispatch next available task
status	Show queue status
complete <taskId>	Mark task complete

Initiative Management (cw initiative)

Command	Description
create <name> [--project <ids...>]	Create initiative
list [-s status]	List initiatives
get <id>	Initiative details
phases <initiativeId>	List phases

Architect (cw architect)

Command	Description
discuss <initiativeId> [-c context]	Start discussion agent
plan <initiativeId> [-s summary]	Start plan agent
detail <phaseId> [-t taskName] [-c context]	Detail phase into tasks

Phase (cw phase)

Command	Description
add-dependency --phase <id> --depends-on <id>	Add dependency edge
dependencies <phaseId>	List dependencies
queue <phaseId>	Queue approved phase
dispatch	Dispatch next phase
queue-status	Show phase queue

Merge & Coordination (cw merge, cw coordinate)

Command	Description
merge queue <taskId>	Queue task for merge
merge status	Show merge queue
merge next	Show next mergeable task
coordinate [-t branch]	Process all ready merges (default: main)

Messages (cw message)

Command	Description
list [--agent <id>] [--status <s>]	List messages
read <messageId>	Read full message
respond <messageId> <response>	Respond to message

Projects (cw project)

Command	Description
register --name <n> --url <u>	Register git repo
list	List projects
delete <id>	Delete project

Preview Deployments (cw preview)

Command	Description
start --initiative <id> --project <id> --branch <branch> [--phase <id>]	Start Docker preview
stop <previewId>	Stop and clean up preview
list [--initiative <id>]	List active previews
status <previewId>	Get preview status with service details

Inter-Agent Conversation (cw listen, cw ask, cw answer)

Command	Description
listen --agent-id <id> [--poll-interval <ms>] [--timeout <ms>]	Poll for pending questions, print JSON, exit
ask <question> --from <agentId> [--agent-id|--phase-id|--task-id <target>] [--poll-interval <ms>] [--timeout <ms>]	Ask question, block until answered, print answer
answer <answer> --conversation-id <id>	Answer a pending conversation

All three commands output JSON for programmatic agent consumption.

Errand Sessions (cw errand)

Command	Description
start <description> --project <id> [--base <branch>]	Start a new errand session (description ≤200 chars)
list [--project <id>] [--status <status>]	List errands; status: active|pending_review|conflict|merged|abandoned
chat <id> <message>	Deliver a message to the running errand agent
diff <id>	Print unified git diff between base branch and errand branch
complete <id>	Mark errand as done and ready for review
merge <id> [--target <branch>]	Merge errand branch into target branch
resolve <id>	Print worktree path and conflicting files for manual resolution
abandon <id>	Stop agent, remove worktree and branch, keep DB record as abandoned
delete <id>	Stop agent, remove worktree, delete branch, and delete DB record

Accounts (cw account)

Command	Description
add [--provider] [--email] [--token]	Auto-discover, manually register, or register with setup token
list	Show accounts with exhaustion status
remove <id>	Remove account
refresh	Clear expired exhaustion markers
extract [--email <email>]	Extract current Claude credentials as JSON (no server required)

Server Wiring

The CLI is the composition root. It creates concrete implementations and passes them as contextDeps:

ServerContextDeps = Omit<TrpcAdapterOptions, 'eventBus' | 'serverStartedAt' | 'processCount'>

This includes all repositories, managers, and the credential manager. The server adds eventBus, serverStartedAt, and processCount at startup.

Workspace Configuration

apps/server/config/ module:

.cwrc File

JSON file at workspace root that marks a cw workspace:

{ "version": 1 }

findWorkspaceRoot()

Walks up directory tree looking for .cwrc file. Returns the directory containing it, or throws if not found.

Schema

Currently { version: 1 } — extend with new top-level keys as needed.

Files

File	Purpose
types.ts	CwrcConfig type definition
cwrc.ts	findWorkspaceRoot(), readCwrc(), writeCwrc()
index.ts	Public API exports