Skip to content
werk

Getting Started

Install

Section titled “Install”

werk is a Rust binary. Install it with cargo:

Terminal window
cargo install werk

This gives you the werk command — the CLI surface. The TUI (terminal interface) launches when you run werk with no arguments.

Create a workspace

Section titled “Create a workspace”

werk stores tensions in a local SQLite database. The first time you run a command, it creates one in the current directory:

Terminal window
werk add "a clear description of what you want to exist"

This creates tension #1. You now have a workspace.

Describe reality

Section titled “Describe reality”

A tension with only a desired state is incomplete. Tell werk what actually exists:

Terminal window
werk reality 1 "what is true right now — be honest"

The gap between these two descriptions is the structural tension. werk will now compute signals, track time, and record your gestures as you work toward resolution.

See the structure

Section titled “See the structure”
Terminal window
werk tree

Shows your tension hierarchy. With one tension, this is simple. As you create more tensions — children, siblings, parallel efforts — the tree reveals the structure of your work.

Terminal window
werk show 1

Shows everything about a single tension: desired, actual, signals, epochs, notes.

Enter the instrument

Section titled “Enter the instrument”
Terminal window
werk

With no arguments, werk opens the TUI — the terminal interface. This is the primary practice surface. Navigate with keyboard, view tensions in spatial layout (desired above actual), use the command palette (/) for any gesture.

What to do next

Section titled “What to do next”