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]

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.

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

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

cloche loop once starts the loop, waits for a single task to complete, then stops. Exits 0 on success, 1 on failure.

cloche loop stop disables the loop. Running tasks are not cancelled.

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. With --runs: workflow ID, workflow, state, type, task ID, title, error.

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>] [-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 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> -- <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 KV CLI)

clo is a lightweight binary available inside containers for reading and writing the daemon’s KV store 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 attempt namespace
clo -v                     # Print version

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

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.