CLI Reference

modula is the command-line companion to the engine. Use it to read and write tasks, variants, comments, and config against your running workspace — the same surface every spawned agent uses instead of curl.

Reads print clean, labelled text. Writes take a single JSON body and print a one-line confirmation. If something goes wrong, you get error: <detail> and a non-zero exit code.


modula [--workspace <id|name>] <command> [args]

modula task        Read and write tasks
modula roadmap     View the roadmap in order
modula variant     Register and transition task variants
modula comment     Read and post to task threads
modula config      Read the workspace config
modula workspace   List and create workspaces
modula engine      Run the engine yourself

Most commands act on one workspace. Pass --workspace (alias --ws) with its name or id, or set it once with MODULA_WORKSPACE. Agents inherit it automatically, so you rarely set it by hand. Run modula --version for the version, or modula <command> --help for inline help.

Tasks


modula task list
modula task get <task>
modula task create <body>
modula task patch <task> <body>

task list shows every task in the workspace — id, external id, title, source, pipeline status, approval, and a summary of its variants. task get shows one task in full, including its dependencies, notes, variants, and labels. An empty workspace prints (no tasks).

task create makes an internal task from {"title":"…"}, or upserts one from a tracker when you add external_id and a source of jira, linear, or github.


modula task create '{"title":"Add CLI reference docs"}'
# → created task: 8f3c… (—)

modula task create '{"title":"Fix login","external_id":"PROJ-42","source":"jira"}'
# → created task: 8f3c… (PROJ-42)   (re-running prints "updated task: …")

task patch does one of two things depending on what you send. Include status, notes, or depends_on to advance the task along the pipeline; send anything else — approved, max_variants, worktree, description, title — to edit the task itself.


modula task patch 8f3c… '{"status":"in_review"}'
# → task 8f3c…: pipeline_status → in_review

modula task patch 8f3c… '{"approved":true,"max_variants":3}'
# → patched task: 8f3c…

Roadmap


modula roadmap list

Shows every task in roadmap order, with its pipeline status, dependencies, and notes. An empty roadmap prints (no roadmap entries).

Variants


modula variant get <variant>
modula variant create <task> <body>
modula variant patch <variant> <body>

variant get shows a variant’s status and position, plus the task it belongs to. variant create adds N variants to a task with {"count":N}; they stay unstarted until promoted.


modula variant create 8f3c… '{"count":2}'
# → created variant: a1b2… (position 1)
# → created variant: c3d4… (position 2)

variant patch moves a variant to a new state. Send a raw status, or a code-reviewer verdict of {"action":"accept"} or {"action":"rework"}.


modula variant patch a1b2… '{"status":"in_progress"}'   # → variant a1b2… → in_progress
modula variant patch a1b2… '{"action":"accept"}'        # → variant a1b2… → accepted

Comments


modula comment list <task>
modula comment create <task> <body>

comment list shows a task’s whole thread — task-level entries first, then each variant’s. comment create posts an entry. The body needs author, kind (comment, question, verdict, or rework), and content. Variant-scoped entries add variant and round; verdicts add verdict, and kick-backs add affected_variants.


modula comment create 8f3c… '{"author":"worker","kind":"comment","content":"hello from cli"}'
# → posted comment by worker (entry 1)

Config


modula config get

Prints the workspace config — limits, pipeline stages, projects, providers, and agents.


modula config get
# limits:
#   max_spawns_per_run: 8
#
# pipeline:
#   <key> — <label> [<tone>]
#   …
#
# projects:
#   my-app (…)
#     path: /Users/me/code/my-app
#     base_branch: main
#
# providers:
#   claude-personal (…) — type=claude
#     config_dir: ~/.claude
#
# agents:
#   reviewer (…) — provider=… model=…

Workspaces


modula workspace list
modula workspace get <workspace>
modula workspace create <body>

These are global — they don’t need a workspace selected. workspace list shows every workspace with its id, name, slug, and description. workspace get looks one up by name or id. workspace create makes a new one; the name sets a slug you’ll use to select it later.


modula workspace create '{"name":"My App"}'
# → created workspace: 8f3c… (My App)

Running the engine

The desktop app runs the engine for you, so you don’t normally need these. Reach for them to host the engine yourself — for example, headless on a server.


modula engine
modula status
modula install
modula link-cli

engine runs the engine. status checks it’s up and lists workspaces. install registers it to start at login (launchd on macOS, systemd on Linux, a registry key on Windows). link-cli puts modula on your PATH.


modula status
# → engine: … (serving)  followed by the workspace list

Environment variables

Set these to avoid passing flags on every command:

Variable	Description
`MODULA_WORKSPACE`	Default workspace id for scoped commands. Overridden by `--workspace` / `--ws`.
`MODULA_ENGINE_SOCKET`	Where to reach the engine, if it isn’t at the default location. Overridden by `--socket`.


export MODULA_WORKSPACE="my-workspace"
modula task list

A scoped command with no workspace set fails with MODULA_WORKSPACE is not set (pass --workspace <id|slug>).