# Lumpcode CLI — command reference

This page documents every `lumpcode` subcommand and its options.

## Contents

**[Global conventions](#ref-global-conventions)** — [Working directory](#ref-working-directory) · [`--json`](#ref-json-output) · [`--verbose`](#ref-verbose-output) · [Booleans](#ref-boolean-options) · [Validation](#ref-project-validation) · [`--help`](#ref-lumpcode-help)

**[Project setup](#ref-section-project-setup)** — [`lumpcode project-setup`](#ref-cmd-project-setup) · [`lumpcode lump-create`](#ref-cmd-lump-create)

**[Run](#ref-section-run)** — [`lumpcode run`](#ref-cmd-run) · [`lumpcode lump-plan`](#ref-cmd-lump-plan)

**[Daemon](#ref-daemon)** — [`lumpcode start`](#ref-cmd-start) · [`lumpcode stop`](#ref-cmd-stop) · [`lumpcode restart`](#ref-cmd-restart) · [`lumpcode supervise`](#ref-cmd-supervise) · [`lumpcode daemon-status`](#ref-cmd-daemon-status) · [`lumpcode daemon-log`](#ref-cmd-daemon-log)

**[Status & cleanup](#ref-status-cleanup)** — [`lumpcode lump-status`](#ref-cmd-lump-status) · [`lumpcode context-status`](#ref-cmd-context-status) · [`lumpcode clean`](#ref-cmd-clean) · [`lumpcode reset-presets`](#ref-cmd-reset-presets)

**[Related documentation](#ref-related-documentation)** · **[Three “status” commands](#three-commands-that-mention-status)**

---

<a id="ref-global-conventions"></a>

## Global conventions

<a id="ref-working-directory"></a>

### Working directory

Most commands use the current working directory as the project root. Run `lumpcode` from the root of the git repository that contains `.lumpcode/`.

If a lump uses a **workspace copy** under `~/.lumpcode/project-copies/`, you still invoke the CLI from your real repo root; see [concepts.md § Three workspaces](./concepts.md#three-workspaces).

<h3 id="ref-json-output"><code>--json</code> output</h3>

Every subcommand accepts **`--json`**. Option tables below list only **command-specific** options.

When **`--json`** is set, the CLI prints a single JSON object instead of human-oriented lines:

```json
{
  "messages": ["…"],
  "data": { }
}
```

- **`messages`** — Always an array of strings (summary lines or errors).
- **`data`** — Optional structured payload (command-specific).

On failure the process exits non-zero. The result envelope goes to stderr on failure and stdout on success.

**Operational logging** (daemon ticks, lock waits, engine step detail) is separate from the result envelope. With **`--json`**, operational **`info`**, **`warn`**, and **`verbose`** lines are suppressed; operational **`error`** lines still print to stderr so you see failures that are not part of the final envelope (for example soft git commit/push errors during a run).

<h3 id="ref-verbose-output"><code>--verbose</code> operational logging</h3>

Every subcommand accepts **`--verbose`**. On **`run`** and **`start`** it gates **`Logger.verbose`** output — extra engine detail during a lump run (branch names, shell commands, git status snapshots, and similar). On other commands the flag is accepted for consistency but has no effect today.

**Not gated by `--verbose`:** normal operational progress at **`info`** level still prints on **`run`** / **`start`** without the flag — for example daemon tick summaries, execution-workspace and branch-workspace lock-wait lines, and per-lump tick results. Those are suppressed only when **`--json`** is set (except operational **`error`** lines; see above).

Verbose is activated when **either** the CLI flag **or** the lump config field **`verbose: true`** is set for that **`run`** / **`start`** invocation (`effectiveVerbose = --verbose || lumpConfig.verbose`).

Operational logs use the shared **`Logger`** (`error`, `warn`, `info`, `verbose`). They are not mixed into the **`--json`** result envelope except that **`error`**-level operational lines still print when **`--json`** is set (see above).

<a id="ref-boolean-options"></a>

### Boolean options

Boolean options are **flags**: omit the flag for the default, pass the flag to select the non-default behavior.

```bash
lumpcode start --foreground
lumpcode context-status myLump myContext --setToFinished
```

For **`lumpcode lump-status`**, verbose status JSON is default; pass **`--silent`** for summary-only output.

**Windows / PowerShell:** single-quoted cron strings are safest: `--cronSetup '*/10 * * * *'`.

<a id="ref-project-validation"></a>

### Project validation

Commands that need a Lumpcode project verify that **`.lumpcode/`** and **`.git/`** exist under the effective project root. If not, they fail with a clear error message.

<h3 id="ref-lumpcode-help"><code>lumpcode --help</code></h3>

The program and each subcommand support **`--help`** (e.g. `lumpcode run --help`).

---

<a id="ref-section-project-setup"></a>

## Project setup

<a id="ref-cmd-project-setup"></a>

### `lumpcode project-setup`

**Description:** Create a fresh `.lumpcode/` tree in a git repository.

**Usage:** `lumpcode project-setup [options]`


| Option | Type | Required | Description |
| ------ | ---- | -------- | ----------- |
| `--projectPath` | string | No | Directory to initialize (default: `.` resolved from cwd) |
| `--projectName` | string | No | Stored in `project.json`; must be letters, digits, `_`, `-` only; if omitted, inferred from `origin` or directory basename and normalized |
| `--mode` | `shared` \| `dedicated` | No | Initial `local.json.mode` (default `shared`) — see [local-config.md](./local-config.md) |
| `--primaryBranch` | string | No | Initial `project.json.primaryBranch` (default `main`) |


**Creates:**

- `.lumpcode/project.json` — `{ "projectName": "…", "primaryBranch": "main" }` (commit this)
- `.lumpcode/local.json` — `{ "mode": "shared" }` (per machine, gitignored)
- `.lumpcode/lumps/` — empty
- `.lumpcode/commands/` — empty
- Appends `.lumpcode/**/contextStatusRecord.json`, `.lumpcode/**/history/`, `.lumpcode/.cache/`, and `.lumpcode/local.json` to `.gitignore`

**Fails if:**

- Path does not exist or is not a directory
- Path is not a git work tree
- `.lumpcode/` already exists

**See also:** [project-config.md](./project-config.md), [get-started.md](./get-started.md#step-1-initialize-the-lumpcode-project).

<a id="ref-cmd-lump-create"></a>

### `lumpcode lump-create`

**Description:** Scaffold a new lump configuration file.

**Usage:** `lumpcode lump-create <lumpName> [options]`


| Argument   | Required | Description                                                                               |
| ---------- | -------- | ----------------------------------------------------------------------------------------- |
| `lumpName` | Yes      | Folder name under `.lumpcode/lumps/`; no `/`, `\`, leading/trailing spaces, or `.` / `..` |



| Option     | Type            | Required | Description                      |
| ---------- | --------------- | -------- | -------------------------------- |
| `--config` | `json` \| `js` \| `ts` | No       | Output format (default `json`) |


**Creates:** `.lumpcode/lumps/<lumpName>/config.json`, `config.js`, or `config.ts`.

**Fails if:** A `config.json`, `config.js`, or `config.ts` already exists in that lump folder.

**See also:** [lump-config.md](./lump-config.md).

---

<a id="ref-section-run"></a>

## Run

<a id="ref-cmd-run"></a>

### `lumpcode run`

**Description:** Execute **one** tick for a single lump (load config, resolve contexts, run the agent, refresh status).

**Usage:** `lumpcode run <lumpName> [options]`


| Argument   | Required | Description                                 |
| ---------- | -------- | ------------------------------------------- |
| `lumpName` | Yes      | Name of the folder under `.lumpcode/lumps/` |


| Option              | Type   | Required | Description                                                                                    |
| ------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------- |
| `--discoveryBranch` | string | No       | Concrete discovery branch (not a glob). Must match the lump's discovery rules. Required when the lump's rules are pattern-only. In shared mode, honored by `lump-plan` and `lump-status` only (context filtering; no checkout); ignored by `run`. In dedicated mode, must also be allowlisted by `primaryBranches`. |


Plus global [`--json`](#ref-json-output).

**Behavior:**

1. Reads `.lumpcode/local.json` (hard-fails if missing); in dedicated mode, phase 1 locks the execution workspace, pre-flights to `effectiveDiscoveryBranch` (CLI override or lump `discoveryBranch`), loads config, then runs the lump; phase 2 pre-flights to the lump `baseBranch` before agent work.
2. In shared mode, `--discoveryBranch` is ignored by `run` (warn once); `lump-plan` and `lump-status` honor it for context filtering without checkout.
3. After a dedicated manual run, switches the operator checkout back to the branch you were on before `run`.

**Success cases:**

- Normal completion: message includes `SUCCESS: Lump run successfully` and `data` may include details of the run (branch name, context names, etc.).
- **Skipped run** when `maximumNumberOfConcurrentBranches` is reached: still a success but nothing is done.
- **Skipped run** when the lump config has `disabled: true`: exit 0 with an informational message.

**Fails if:** `local.json` missing or invalid, pre-flight git commands fail, config missing/invalid, engine errors, or **`workspacePathBusy`** (another run or daemon holds the workspace path lock — see [concepts.md § Concurrency and locks](./concepts.md#concurrency-and-locks)).

With **`--json`**, busy responses include a stable `code` field (`workspacePathBusy`) plus path and optional holder pid/lump name.

**See also:** [concepts.md](./concepts.md#one-run-end-to-end), [advanced-config.md § Hook lifecycle](./advanced-config.md#hook-lifecycle) (shared / dedicated schemas), [lump-config.md](./lump-config.md#optional-top-level-fields) (`maximumNumberOfConcurrentBranches`), [get-started.md](./get-started.md#step-4-run-once).

<a id="ref-cmd-lump-plan"></a>

### `lumpcode lump-plan`

**Description:** Preview a lump configuration before running it: validate config and hooks, list contexts, show generated prompts, or dry-run the next tick. Does **not** run pre-flight (no `git reset --hard`), does **not** invoke the coding agent, and does **not** push or commit.

**Usage:** `lumpcode lump-plan <lumpName> [options]`


| Argument   | Required | Description                                 |
| ---------- | -------- | ------------------------------------------- |
| `lumpName` | Yes      | Name of the folder under `.lumpcode/lumps/` |



| Option              | Type   | Required | Description                                                                 |
| ------------------- | ------ | -------- | --------------------------------------------------------------------------- |
| `--contexts`        | flag   | No       | Include resolved context names and variables                                |
| `--todoOnly`        | flag   | No       | With `--contexts`, `--prompts`, or `--plan`: only contexts `run` would pick next (read-only git status queries) |
| `--prompts`         | flag   | No       | Include per-context prompt text and resolved agent command (`executable` + `args`) |
| `--plan`            | flag   | No       | Full dry-run: branch name, workspace setup/teardown shell commands, batch contexts, git add/commit/push strings, concurrent-branch skip reason |
| `--contextName`     | string | No       | Scope contexts / prompts / plan to one context                              |
| `--discoveryBranch` | string | No       | Concrete discovery branch (not a glob). Must match the lump's discovery rules. Required when rules are pattern-only. In shared mode, binds context filtering only (no checkout). |

Plus global [`--json`](#ref-json-output).

**Depth:** flags stack by specificity: `--plan` > `--prompts` > `--contexts` > default (validate only).

**Behavior:**

1. Validates project root (`.lumpcode/` + `.git/`).
2. Loads lump config (`config.json` is checked against the JSON schema; `config.js` and `config.ts` are imported and resolved).
3. Resolves hooks, command modules, and `disabled` the same way as `run` (shared pipeline).
4. Optionally lists contexts, expands prompts, or simulates one run tick.

**Note:** `--prompts` and `--plan` may **execute** user-defined hooks (`setupFn`, `promptFn`, dynamic `steps` functions) to produce accurate output. They do not run the agent binary or git mutations.

**Fails if:** Project validation fails, `local.json` missing or invalid, config missing/invalid, or resolution errors.

**See also:** [lump-config.md](./lump-config.md), [`lumpcode run`](#ref-cmd-run).

---

<a id="ref-daemon"></a>

## Daemon

<a id="ref-cmd-start"></a>

### `lumpcode start`

**Description:** Run a **scheduler** that periodically discovers and executes lumps (all loadable lumps by default, or a filtered subset). Every daemon uses the same discovery path; identity is a unique `daemonId`.

**Usage:** `lumpcode start [options]`


| Option              | Type    | Required | Description                                                              |
| ------------------- | ------- | -------- | ------------------------------------------------------------------------ |
| `--foreground`      | flag    | No       | Blocking in this terminal; omit to detach a background daemon            |
| `--cronSetup`       | string  | No       | Cron expression (default `*/5 * * * *` — every 5 minutes)              |
| `--include`         | string  | No       | Comma-separated lump name patterns (exact or `*` globs) to include       |
| `--exclude`         | string  | No       | Comma-separated patterns subtracted after include                        |
| `--daemonId`        | string  | No       | Unique id for PID/log/meta (`[a-zA-Z0-9_-]+`). Default unfiltered: `global` |
| `--maxParallelRun`  | number  | No       | Override `local.json` maxParallelRun for this worktree daemon            |
| `--lumpName`        | string  | No       | **Deprecated.** Equivalent to `--include=<name>`                         |

With **`--json`**, all the logs even the ones of the deamon will be with json output.

**Merged project/local at startup:** `.lumpcode/project.json` and `.lumpcode/local.json` are merged **once** when the daemon starts (local wins on shared keys; includes lump-default fields such as `command`). That surface is frozen for every tick until you restart the daemon. Edit either file and restart to pick up changes.

**Parallel ticks:** when `workspaceStrategy` is `"worktree"`, every daemon uses `maxParallelRun` from `--maxParallelRun` or `local.json` (default `1`) as the in-tick concurrency for its filtered queue. `"checkout"` stays sequential; passing `--maxParallelRun` with checkout fails.

**Pre-flight per tick:** skips the tick when `disabled` is `true` in the frozen config (no pre-flight, no lump runs). Otherwise it discovers eligible lumps per primary branch (subtick), applies include/exclude, then runs the filtered queue (soft-skipping per-lump `disabled` at phase 1). Dedicated discovery checks out each scan branch, then runs frozen `refreshCommand` from merged `project.json` / `local.json` when set (for example `npm i`) before loading lump configs. A refresh failure skips that scan branch; other branches continue. Shared mode and manual `run` do not run it. Empty filter matches idle; the daemon stays up. If discovery/pre-flight fails for a branch the daemon logs and continues with other branches.

**Daemon files** under `~/.lumpcode/daemons/`:

| Scope | Files |
| ----- | ----- |
| Any daemon | `<projectName>.<daemonId>.daemon.pid`, `.daemon.log`, `.daemon.meta.json`, `.daemon.desired.json` |

The per-project **supervisor** lives under `~/.lumpcode/supervisor/` (`<projectName>.pid`, `.log`, `.meta.json`). It is not a daemon id.

Default unfiltered id is `global`. Meta JSON includes `daemonId`, `cronSetup`, `workspaceStrategy`, optional `include` / `exclude` / `maxParallelRun`, and `inFlightLumpCount`.

**Collision rules:**

- Start fails only when the chosen **`daemonId` is already in use**, or any alive peer has **missing/invalid** meta (`data.code: "daemonMetaCorrupt"`). Overlapping filters are allowed; workspace locks coordinate the same lump.
- The workspace strategy recorded in each daemon's meta file is the value frozen at **that daemon's** startup (not re-read from `local.json` on each tick).

**Detached mode (default):**

- Ensures `~/.lumpcode/daemons/` exists.
- Writes `<project>.<id>.daemon.desired.json` (spawn recipe; no `--json` / `--verbose`) **before** spawn.
- Starts the per-project supervisor if it is not running (`lumpcode supervise --foreground`).
- Applies the collision rules above.
- Re-launches itself with `--foreground --cronSetup <expr> --daemonId <id>` (and include/exclude/maxParallelRun when set) and detaches, redirecting stdio to the log file.
- The detached parent writes the PID file with the child pid; the foreground child writes meta.

**Foreground mode:**

- Validates cron, writes desired + PID + meta, runs an immediate tick, then schedules ticks on the same cron.
- On SIGINT/SIGTERM, marks desired `stopping` so the supervisor does not respawn, stops the scheduler, and removes PID/meta/desired if they belong to this process.
- If the supervisor dies, the daemon finishes in-flight work then exits without clearing desired, so a restarted supervisor can relaunch it.

**Fails if:** Invalid cron, daemon id already in use / corrupt peer meta, `--maxParallelRun` with checkout, cannot write PID/log/meta, or `local.json` missing/invalid. Empty filter matches warn and still start.

**See also:** [concepts.md](./concepts.md#when-to-use-run-vs-start-daemon), [advanced-config.md § Hook lifecycle](./advanced-config.md#hook-lifecycle) (daemon tick wrappers), [concepts.md § Concurrency and locks](./concepts.md#concurrency-and-locks), [get-started.md](./get-started.md#step-5-run-continuously-optional).

<a id="ref-cmd-stop"></a>

### `lumpcode stop`

**Description:** Stop a background daemon using its PID file (default id `global`).

**Usage:** `lumpcode stop [options]`

| Option       | Type    | Required | Description                                      |
| ------------ | ------- | -------- | ------------------------------------------------ |
| `--daemonId` | string  | No       | Stop this daemon id (default: `global`)          |
| `--lumpName` | string  | No       | **Deprecated.** Treated as `--daemonId`          |
| `--all`      | flag    | No       | Stop every start-daemon for this project, then the supervisor |
| `--force`    | boolean | No       | Force-stop the daemon and its child processes    |

**Behavior:** Reads the scoped PID file under `~/.lumpcode/daemons/` and daemon meta.

When the daemon is **idle** (`inFlightLumpCount` is `0` or absent, and legacy `busy` is not `true`), marks desired `stopping`, sends **SIGTERM**, waits up to **5 seconds** for exit, then deletes PID, meta, and desired files on success.

When the daemon is **mid-run** (`inFlightLumpCount >= 1`, or legacy `busy: true` from an older CLI), default stop **refuses** (non-zero; with `--json`, `data.code: "daemonBusy"`) and suggests **`--force`**. Artifacts, desired.json, and the process are left alone so in-flight work can finish.

When the PID is alive but daemon **meta is missing or invalid**, default stop **refuses** (non-zero; with `--json`, `data.code: "daemonMetaCorrupt"`) and suggests **`--force`**. Do not invent idle or checkout state from a missing file.

**`lumpcode stop --force`** marks desired `stopping` (so the supervisor will not respawn), immediately tree-kills the daemon PID and all descendant processes (discovered at stop time), polls up to **5 seconds** until the daemon PID is gone, then removes PID, meta, and desired.json on success. Force does **not** require a readable meta file. This is **best-effort**: agent processes that detached from the daemon process tree may survive. A force-killed daemon may leave a workspace lock behind; it is removed automatically on the next acquire ([concepts.md § Concurrency and locks](./concepts.md#concurrency-and-locks)).

**`lumpcode stop --all`** is project-scoped. It marks every start-daemon desired file `stopping` first, SIGTERMs idle daemons (busy ones drain), waits for PIDs to exit, deletes leftovers, then stops the supervisor. **`--all --force`** marks stopping then tree-kills, and still unlinks desired only after the processes are gone. Do not combine `--all` with `--daemonId`.

**Fails if:** No PID file, invalid PID, mid-run without `--force`, corrupt meta without `--force`, cannot signal process, or process does not exit within the deadline.

**See also:** [concepts.md](./concepts.md#when-to-use-run-vs-start-daemon).

<a id="ref-cmd-restart"></a>

### `lumpcode restart`

**Description:** `lumpcode stop` then `lumpcode start`, restoring `cronSetup`, `include` / `exclude`, `maxParallelRun`, and `daemonId` from desired.json (legacy: live meta).

**Usage:** `lumpcode restart [options]`

| Option       | Type   | Required | Description                                      |
| ------------ | ------ | -------- | ------------------------------------------------ |
| `--daemonId` | string | No       | Restart this daemon id (default: `global`)       |
| `--lumpName` | string | No       | **Deprecated.** Treated as `--daemonId`          |

If desired.json is missing, restart adopts filters from live meta. If both desired.json and meta are missing or invalid, restart fails and does not invent a default recipe. If meta is missing or invalid but desired.json is readable, restart uses **`stop --force`** then starts from desired. Mid-run with readable meta still refuses via normal stop (`daemonBusy`).

**See also:** [concepts.md](./concepts.md#when-to-use-run-vs-start-daemon).

<a id="ref-cmd-supervise"></a>

### `lumpcode supervise`

**Description:** Run the per-project supervisor that keeps start-daemons up from `desired.json`. `lumpcode start` starts this process when it is down. It is not a daemon id.

**Usage:** `lumpcode supervise --foreground [options]`

| Option          | Type   | Required | Description                                              |
| --------------- | ------ | -------- | -------------------------------------------------------- |
| `--foreground`  | flag   | Yes      | Blocking in this terminal (no detached supervise mode)   |
| `--projectRoot` | string | No       | Absolute project workspace (default: current directory)  |

Every 30 seconds the supervisor reconciles desired.json against live PIDs: spawn missing start-daemons, leave running ones, adopt pre-feature PIDs into desired.json, orphan-kill PIDs with unreadable meta, and delete leftover files after a drain. Lump daemons are not placed under PM2.

**systemd (optional):** keep only this small process under `Restart=always`. Example unit:

```ini
[Service]
ExecStart=/usr/bin/lumpcode supervise --projectRoot /abs/path/to/repo --foreground
Restart=always
```

There is no `lumpcode supervise-install`. `stop --all` stops the supervisor after the project's start-daemons.

**See also:** [concepts.md](./concepts.md#when-to-use-run-vs-start-daemon) (daemon files table).

<a id="ref-cmd-daemon-status"></a>

### `lumpcode daemon-status`

**Description:** List all project daemons (no flags), or inspect one by `--daemonId`.

**Usage:** `lumpcode daemon-status [options]`

| Option       | Type   | Required | Description                                      |
| ------------ | ------ | -------- | ------------------------------------------------ |
| `--daemonId` | string | No       | Inspect this daemon id                           |
| `--lumpName` | string | No       | **Deprecated.** Treated as `--daemonId`          |

**Output highlights:**

- With no flags: every alive daemon id for the project (plus pid / running summary) and a `supervisor` object (`running`, optional `pid`)
- With `--daemonId`: single-daemon detail (paths, stale PID, cron, filters, `inFlightLumpCount`, `metaStatus` when corrupt)

**See also:** [concepts.md](./concepts.md#when-to-use-run-vs-start-daemon) (daemon files table).

<a id="ref-cmd-daemon-log"></a>

### `lumpcode daemon-log`

**Description:** Tail a background daemon log file. **Follows live by default** (`tail -f`); pass **`--noFollow`** to print and exit.

**Usage:** `lumpcode daemon-log [options]`

| Option       | Type    | Required | Description                                                                 |
| ------------ | ------- | -------- | --------------------------------------------------------------------------- |
| `--daemonId` | string  | No       | Log for this daemon id (default: `global`)                                  |
| `--lumpName` | string  | No       | **Deprecated.** Treated as `--daemonId`                                     |
| `--lines`    | number  | No       | Number of initial lines to show (with follow, uses `tail -n N -f`)            |
| `--noFollow` | flag    | No       | Print lines and exit instead of following live                              |
| `--json`     | flag    | No       | With `--noFollow`, output structured JSON (`logFilePath`, `lines`, …)       |

**Behavior:**

- Default: `tail -f` on the scoped log file until Ctrl+C / SIGTERM.
- With `--lines N` (no `--noFollow`): `tail -n N -f` — show the last *N* lines, then keep following.
- With `--noFollow`: print and exit (`tail` or `tail -n N` when `--lines` is set).
- Does not require the daemon to be running; fails if the log file does not exist for that scope.

**See also:** [concepts.md](./concepts.md#when-to-use-run-vs-start-daemon) (daemon files table).

---

<h2 id="ref-status-cleanup">Status & cleanup</h2>

<a id="ref-cmd-lump-status"></a>

### `lumpcode lump-status`

**Description:** For one lump (or all lumps), **recompute** `contextStatusRecord.json` from remote git state and print a summary.

**Usage:** `lumpcode lump-status [options]`


| Option              | Type   | Default | Description                                                                                                                   |
| ------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `--lumpName`        | string | —       | If omitted, all lumps with loadable configs                                                                                   |
| `--discoveryBranch` | string | —       | Concrete discovery branch (not a glob). Must match the lump's discovery rules. Required when rules are pattern-only. In shared mode, binds context filtering only (no checkout). |
| `--silent`          | flag   | No      | Omit pretty-printed status JSON; print summary lines only (default is verbose when not using `--json`)                         |
| `--json`            | flag   | No      | JSON output mode                                                                                                              |


**Data:** `data.statusByLump` holds the in-memory maps keyed by lump name.

**See also:** [concepts.md](./concepts.md#status-lifecycle), [lump-config.md](./lump-config.md#contextstatusrecordjson).

<a id="ref-cmd-context-status"></a>

### `lumpcode context-status`

**Description:** Show or mutate a **single** context entry after refreshing the lump’s status record.

**Usage:** `lumpcode context-status <lumpName> <contextName> [options]`


| Argument      | Required | Description                   |
| ------------- | -------- | ----------------------------- |
| `lumpName`    | Yes      | Lump folder name              |
| `contextName` | Yes      | Context key inside the record |



| Option            | Type    | Required | Description                                                                                                                |
| ----------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `--setToFinished` | flag | No       | Creates an **empty** marker commit on `baseBranch` with the lump’s normalized message and pushes `baseBranch` |


**Output:** Prints one JSON object for the context row (synthesized `toDo` row if missing).

**See also:** [concepts.md](./concepts.md#status-lifecycle).

<a id="ref-cmd-clean"></a>

### `lumpcode clean`

**Description:** Delete Lumpcode-created branches **locally** and on **`origin`**.

**Usage:** `lumpcode clean [options]`


| Option          | Type   | Required | Description                                                                         |
| --------------- | ------ | -------- | ----------------------------------------------------------------------------------- |
| `--lumpName`    | string | No       | Only branches under `lump/<lumpName>/…`                                             |
| `--contextName` | string | No       | Requires `--lumpName`; finds branches containing the marker commit for that context |


**Behavior:** Runs `git fetch --all` first, then deletes matching remote refs (`git push --delete origin …`) and local branches (`git branch -D …`).

**Rules:**

- `--contextName` without `--lumpName` is rejected.

**See also:** [lump-config.md](./lump-config.md#commit-messages) (marker format).

<a id="ref-cmd-reset-presets"></a>

### `lumpcode reset-presets`

**Description:** Reinstall shipped preset command modules into `~/.lumpcode/commands/presets/`, overwriting any files already there.

**Usage:** `lumpcode reset-presets [options]`


| Option   | Type | Default | Description      |
| -------- | ---- | ------- | ---------------- |
| `--json` | flag | No      | JSON output mode |


**Behavior:** Copies bundled presets (`cursor`, `copilot`, `claude-code`, `opencode`, `codex`, …) from the installed CLI package. Does not require a Lumpcode project directory. The same reinstall runs automatically on `npm install` / `npm update` of `@lumpcode/cli` and after standalone install via `install.sh`.

**See also:** [advanced-config.md](./advanced-config.md#shipped-presets) (preset resolution order).

---

<a id="ref-related-documentation"></a>

## Related documentation

- [get-started.md](./get-started.md) — Tutorial
- [concepts.md](./concepts.md) — Mental model and daemon
- [project-config.md](./project-config.md) — `project.json`
- [local-config.md](./local-config.md) — Per-machine `.lumpcode/local.json` (`mode`, `primaryBranch`)
- [lump-config.md](./lump-config.md) — Lump configuration
- [advanced-config.md](./advanced-config.md#hook-lifecycle) — Lifecycle schemas (shared / dedicated), dynamic prompts, custom commands

<a id="three-commands-that-mention-status"></a>

## Three commands that mention “status”

Do not confuse the **three CLI subcommands** below with the three per-context **status values** (`toDo`, `branchPushed`, `finished`) explained in [concepts.md](./concepts.md#core-terms).

| Command | What it checks |
|--------|----------------|
| **`lumpcode daemon-status`** | Is the **background daemon process** running? PID file, log path, `cronSetup` from meta. |
| **`lumpcode lump-status`** | For each lump, **recompute** `contextStatusRecord.json` from **remote git** (per-context `toDo` / `branchPushed` / `finished`). |
| **`lumpcode context-status`** | One **context** row after refresh; optional `--setToFinished` to push a marker on `baseBranch`. |