Codewalkers/docs/cli-config.md

CLI & Configuration

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

Entry Point

src/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
breakdown <initiativeId> [-s summary]	Start breakdown agent
decompose <phaseId> [-t taskName] [-c context]	Decompose 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

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

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

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