CLI Commands

Every command supports --json for structured output. Every destructive command supports --dry-run for preview. Run werk <command> --help for full usage with examples.

Structure — Architecture of Space

Commands that create, move, and shape the tension hierarchy.

Command	Description
`add`	Create a new tension. `--parent <id>` to nest it.
`compose`	Create a parent for existing tensions.
`move`	Reparent a tension. `move 42 --parent 10`
`rm`	Delete a tension. Children are reparented to grandparent.
`show`	Display full tension details — desired, actual, signals, epochs.
`tree`	Display the tension forest as a tree.
`split`	Split a tension into N new tensions with provenance tracking.
`merge`	Merge tensions with provenance tracking.

Action — Grammar of Action

Commands that mutate tension state. Every mutation is a gesture.

Command	Description
`reality`	Update current reality. `reality 42 "what is true now"`
`desire`	Update desired state. `desire 42 "what I want"`
`resolve`	Mark a tension as resolved.
`release`	Let go of a tension’s desired state. Requires `--reason`.
`reopen`	Reopen a resolved or released tension.
`hold`	Remove from sequence (unposition).
`position`	Set position in order of operations. `position 42 3`
`note`	Add, retract, or list notes on a tension.

Time — Calculus of Time

Commands that set temporal parameters. You provide two inputs; werk computes the rest.

Command	Description
`horizon`	Set or display deadline. `horizon 42 2026-06` or `horizon 42 none`
`snooze`	Snooze until a future date.
`recur`	Set or clear recurrence interval.
`epoch`	Manually mark an epoch boundary.

Framing — Logic of Framing

Commands that shape what’s visible.

Command	Description
`list`	Query engine with 12+ filter/sort flags. The general-purpose reading command.
`tree`	Hierarchical view with signals and closure ratios.
`stats`	Field-level summaries and aggregates.
`survey`	Napoleonic field survey — all tensions by temporal urgency.
`log`	Query the logbase — epoch history, cross-tension timeline, provenance.

System

Command	Description
`init`	Initialize a workspace (creates `.werk/` directory).
`config`	Get or set configuration values.
`flush`	Export tension state to git-trackable JSON.
`batch`	Apply mutations from YAML files.
`mcp`	Start the MCP server (stdio transport, 35 tools).
`serve`	Launch the web interface at `localhost:3749`.
`nuke`	Destroy the workspace.

Conventions

Short codes everywhere. Use #42 not ULIDs. Short codes are the user-facing addressing scheme.
--json on every command. Agents should always use this flag.
Deep addressing. #42~e3 (epoch 3), #42.n3 (note 3), #42@2026-03 (temporal lookup).
Non-interactive. No command blocks on stdin. Safe for scripts and agents.