CLI Reference

Every subcommand supports --help (or -h). Use cloche help <command> for detailed usage.

cloche init

Set up or refresh a Cloche project. Safe to run on any existing project — existing files are not overwritten.

cloche init [-n | --new] [--install-shell-helpers]
            [--workflow <name>] [--base-image <image>]
            [--agent-command <cmd>] [--no-llm] [--no-commit]

Core behavior (always, no flags needed): Creates the .cloche/ directory structure if missing, creates or updates .cloche/config.toml (setting active = true), adds .gitignore entries for runtime state, and registers the project with the daemon.

--new scaffolding: Creates .cloche/ with the workflow file, Dockerfile, prompt templates (implement.md, fix-tests.md, fix-merge.md), host workflows (host.cloche), Python scripts (get-tasks.py, claim-task.py, prepare-prompt.py, merge.py, close-task.py, cleanup.py, unclaim.py), a bundled copy of the getting-started tutorials at .cloche/docs/init/, .cloche/version, .clocheignore (at project root), and cloche_init_test/cloche/test_cloche.py. Skips existing files.

Beads bootstrap: --new also sets up beads as the task tracker: if the bd CLI is installed and .beads/ does not exist, it runs bd init and creates two starter validation tasks (the second depends on the first). If bd is missing, init prints a warning with install instructions and still generates the scaffold; re-run cloche init --new after installing to create the starter tasks. The tracker is swappable — the bundled .cloche/docs/init/ tutorials cover replacing it.

Scaffold commit: --new finishes by committing the generated files (Add cloche scaffold), because containers are seeded from a clean git snapshot of the last commit — uncommitted files are invisible in-container. Skipped with --no-commit, outside a git repository, or when staged changes are present (init prints guidance in each case). The project image builds automatically on first use, so a manual docker build before the first loop is optional.

Three generated files contain TODO(cloche-init) placeholders that are auto-filled by LLM analysis of your project:

• .cloche/Dockerfile — dependency installation block
• .cloche/<name>.cloche — the test step run command
• .cloche/prompts/implement.md — project context section

LLM command resolution order: --agent-command flag → CLOCHE_AGENT_COMMAND env var → global config [daemon] llm_command → claude if on PATH. The LLM phase has a 30-second timeout and is non-fatal. Use --no-llm for CI environments.

To locate remaining placeholders: grep -r 'TODO(cloche-init)' .cloche/

Also creates ~/.config/cloche/config (global daemon config) if it does not already exist, enabling the web dashboard on localhost:8080.

cloche doctor

Diagnose Cloche infrastructure.

cloche doctor [--project <dir>] [--verbose] [--timeout <duration>]

Runs checks in order and prints a status line for each. Exits 1 if any check fails. Checks 5–8 only run when the current (or --project) directory contains a .cloche/ subdirectory.

cloche run

Launch a workflow run.

cloche run <workflow>[:<step>] [--prompt "..."] [--title "..."] [--issue ID] [--keep-container]

Must be run from inside a git repository. The daemon auto-rebuilds the Docker image when .cloche/Dockerfile changes. Prints the workflow ID, task ID, and attempt ID on success.

cloche resume

Resume a failed workflow run from a specific step.

cloche resume <task-id>
cloche resume <workflow-id>
cloche resume <step-id>

The run must be in a failed state. For container workflows, the container must still exist (failed runs keep their containers by default). Resume creates a new attempt rather than modifying the failed run — the previous attempt stays in its failed state for lineage tracing.

cloche loop

Start or stop the orchestration loop.

cloche loop [--max <n>]
cloche loop once
cloche loop stop [--hard]
cloche loop status

Continuously runs list-tasks → picks an open task → runs the main workflow → repeats.

cloche loop once launches the next ready task, then stops the loop itself, leaving the launched run to continue in the background. Exits 0 once a task is launched, or 1 if nothing was assignable. Track the run with cloche poll or cloche list.

cloche loop stop disables the loop. Running tasks are not cancelled. The stopped state is persisted to .cloche/.loop-stopped; if the daemon restarts while the loop is stopped, in-flight runs are not auto-resumed.

cloche loop stop --hard stops the loop and immediately parks all resumable (pending, running, waiting) runs so they will not fire automatically if the daemon restarts. Parked runs have state parked and can be inspected with cloche list --runs. Use this before rebuilding or restarting the daemon.

cloche loop status shows the current loop state, including a Resumable runs count of parked runs that would otherwise fire on daemon restart.

When stop_on_error or max_consecutive_failures triggers a halt, run cloche loop again to restart.

cloche list

List tasks for the current project.

cloche list [--all] [--project <dir>] [--state <state>] [--limit <n>] [--runs]

Default columns: task ID, status, attempt count, latest attempt ID, title. A task awaiting a help-channel reply after parking shows [awaiting reply: <title> (<channel>/<name>)] appended to its status.

With --runs: workflow ID, workflow, state, type, task ID, title, error. A run with an open help thread shows [pending question: <channel>/<name>] appended to its state; a parked run shows [awaiting reply: <title> (<channel>/<name>)].

cloche status

Show run status and token usage.

cloche status [<task-id>] [--all] [--no-color]

cloche logs

Show step logs.

cloche logs <id> [--type <full|script|llm>] [--step <name>] [-f] [-l <n>]

The first argument accepts any level of the ID hierarchy:

Flags are combinable: cloche logs a3f7:develop:implement -l 20 -f

cloche poll

Block until targets finish.

cloche poll <id> [id...] [--no-color]

Polls every 2 seconds. Exits 0 if all runs succeeded, 1 if any failed or were cancelled.

With a single ID, prints step-level progress. With multiple IDs, displays a compact status summary and re-prints on state changes.

cloche stop

Stop all active runs for a task.

cloche stop <task-id>

Container runs have their container terminated; host runs have their execution cancelled. All affected run states transition to “cancelled”.

cloche delete

Delete a retained Docker container.

cloche delete <container-or-run-id>

cloche health

Show per-project pass/fail summary.

cloche health

Requires CLOCHE_HTTP.

cloche workflow

List all workflows or render a specific workflow as an ASCII-art graph.

cloche workflow [--project <dir>]
cloche workflow <name> [--project <dir>]

With no arguments, lists all workflows grouped by type (container or host). With a workflow name, renders the workflow graph showing step boxes, wiring, and result paths. Wires are colorized: green for success, red for fail/failed, other colors for custom results.

cloche validate

Validate project configuration and workflow definitions.

cloche validate [--project <path>] [--workflow <name>]

Checks: config.toml parsing, workflow syntax, result wiring completeness, terminal coverage, no orphan steps, file references (prompt file() paths, script run paths), and cross-file consistency (workflow_name references resolve).

cloche project

Show project info and config.

cloche project [--name <label>]

By default, looks up the project by the current working directory. Use --name to look up a project by its registered label instead.

Output includes: config settings, orchestrator loop state (running/stopped/halted), currently active runs, and known workflows. When the loop is halted due to stop_on_error, max_consecutive_failures, or a container infrastructure failure, the halt error message is displayed.

cloche get

Get a value from the KV store.

cloche get <key>

Requires CLOCHE_TASK_ID (and CLOCHE_ATTEMPT_ID if set). Exits 1 if the key is not found.

cloche set

Set a value in the KV store.

cloche set <key> <value|->
cloche set <key> -f <file>

Requires CLOCHE_TASK_ID (and CLOCHE_ATTEMPT_ID if set). Pass - as the value to read from stdin (trailing newlines trimmed). Pass -f <file> to read from a file.

cloche tasks

Show the task pipeline and assignment state.

cloche tasks [--project <dir>]

Displays upcoming/open tasks, which tasks are assigned to which runs, and auto-assignment state. Requires CLOCHE_HTTP.

cloche threads

List, show, and reply to agent help-request threads. An agent step (via the ask_user MCP tool or clo ask) can open a help thread mid-run and block for a reply; threads are addressed by <channel>/<name>, where channel defaults to the project name.

cloche threads [list] [--all] [--channel <c>]
cloche threads show <channel>/<name>
cloche threads reply <channel>/<name> "message"

threads show prints the thread’s metadata (title, state, task/run/step) followed by the full message transcript. threads reply appends a user reply, which unblocks the agent’s waiting ask.

If no reply arrives within park_after (default 5m, configurable in the [help] config section), the run is parked: its container is committed and stopped so it doesn’t burn resources indefinitely. Replying to a parked thread automatically resumes the run — a prompt-adapter agent continues its session with the answer; a generic step replays from the start and gets the answer instantly at the same ask site. See cloche status for a run’s parked state.

cloche activity

Show the project activity log.

cloche activity [--project <dir>] [--since <duration|time>] [--until <time>] [--json]

Event kinds: attempt_started, attempt_ended, step_started, step_completed.

cloche –version

Print version information for all Cloche components.

cloche -v
cloche --version

Displays the CLI version, queries the daemon for its version, and runs the agent version check from the project’s container image. Version mismatches produce warnings on stderr.

The daemon and agent binaries also support standalone version output: cloched -v and cloche-agent -v.

cloche shutdown

Send a shutdown signal to the daemon.

cloche shutdown [--force|-f] [--restart|-r]

Refuses to shut down if there are active runs unless --force is specified.

cloche console

Start an interactive agent session in a fresh container.

cloche console [--agent <command>]

Uses the project’s image and setup (project files, auth credentials, overrides) — the same environment as a workflow run, without running a workflow. The terminal is put into raw mode with bidirectional I/O forwarding.

When the session ends, the container is kept and can be deleted with cloche delete <container-id>. The container ID is printed on exit. Must be run from inside a git repository with a .cloche/ directory.

cloche complete

Shell completion helper (not intended for direct use).

cloche complete --index <n> [-i <n>] -- <word0> <word1> ...

Prints one completion candidate per line. If the daemon is reachable, returns dynamic candidates (task IDs, workflow names, attempt IDs) via gRPC. Falls back to static completions otherwise.

Set up with cloche init --install-shell-helpers, which writes completion scripts for bash and zsh.

clo (In-Container CLI)

clo is a lightweight binary available inside containers for reading and writing the daemon’s KV store — and asking the user questions — without needing the full cloche client.

clo get <key>              # Print value to stdout; exit 1 if not found
clo set <key> <value>      # Set a key
clo set <key> -            # Read value from stdin (trailing newlines trimmed)
clo set <key> -f <file>    # Set a key from file contents
clo keys                   # List all keys in the current run namespace
clo ask [--thread <id>] [--option A --option B ...] [--key <ask-key>] [--no-park] "question"
                           # Ask the user a question and block for the reply
clo -v                     # Print version

clo reads CLOCHE_ADDR, CLOCHE_TASK_ID, CLOCHE_ATTEMPT_ID, and CLOCHE_RUN_ID from the environment. The Docker adapter sets all four automatically.

clo ask opens (or continues, with --thread) a help thread and blocks until the user replies from cloche threads reply or a configured integration (see cloche threads and the [help] config section). --option may be repeated to suggest answers; --key sets an idempotency key for replay. If no reply arrives within park_after, the run is parked (container committed and stopped) and clo ask exits 3 instead of returning an answer directly; replaying the same call after resume returns the answer instantly. --no-park disables parking for this ask — it blocks in place until replied or the step’s own timeout fires instead, for steps that cannot replay safely on resume.

Environment Variables

Daemon Configuration

Client Configuration

Host Step Runtime Variables

Set by the daemon for each host step script invocation.

Container Runtime Variables

Injected into the container by the daemon at startup.