# Command-line reference

Every Hankweave run starts from one command: `hankweave [options] [config-or-data-path]`. This page is the complete contract for that command in version 0.10.0 - which flags the parser accepts, what values they take, what they default to, and where the shipped `--help` text disagrees with actual parser behavior. It assumes you already know what a hank is and have run one at least once; if not, start with [first run](/0.10.0/files/start/first-run) and come back here when you need exact flag semantics.

The flags are grouped by task rather than alphabetically, so you can scan the section that matches what you are trying to do: controlling executions, placing output, supplying configuration and input, running the server, setting timeouts and budgets, or selecting a mode such as validation or cleanup. Captured command output appears throughout, marked `output=v0.10.0`, so you can see exactly what the parser prints when it accepts or rejects an invocation.

<a id="how-to-read-this-page"></a>

## Flag inventory and version notes

A **hank** is a workflow configuration. A **codon** is one agent task in its sequence. Those two terms appear throughout the flag descriptions below.

<a id="generation-and-entry-anatomy"></a> <a id="entry-anatomy"></a>

Each flag entry lists its value type, aliases, and default, followed by constraints and examples where needed. Defaults use `// default: …`. Ten short aliases are help-documented: `-e`, `-n`, `-f`, `-y`, `-o`, `-p`, `-i`, `-m`, `-v`, and `-h`. Of these, `-y` is the only short alias without a long form.

The table below is the full inventory: every flag the 0.10.0 parser accepts, and whether it also appears in shipped `--help`. A "no" in the second column means the flag works but is undocumented in help - a help-parity gap, not a dead flag.

| Flag                     | In shipped help? |
| ------------------------ | ---------------- |
| `--anthropic-base-url`   | yes              |
| `--attach`               | yes              |
| `--cleanup`              | yes              |
| `--config`               | yes              |
| `--copy`                 | yes              |
| `--data`                 | yes              |
| `--execution`            | yes              |
| `--force`                | yes              |
| `--headless`             | yes              |
| `--help`                 | yes              |
| `--idle-timeout`         | yes              |
| `--ignore-data-mismatch` | no               |
| `--ignore-rig-failures`  | yes              |
| `--init`                 | yes              |
| `--input`                | yes              |
| `--max-cost`             | no               |
| `--max-time`             | no               |
| `--model`                | yes              |
| `--new`                  | yes              |
| `--no-autostart`         | yes              |
| `--no-wipe`              | yes              |
| `--output`               | yes              |
| `--overwrite-output`     | yes              |
| `--port`                 | yes              |
| `--proxy`                | yes              |
| `--replay`               | no               |
| `--shim-idle-timeout`    | yes              |
| `--start-new`            | yes              |
| `--validate`             | yes              |
| `--version`              | yes              |
| `--without-proxy`        | no               |

> **VersionNote:** In 0.10.0, five flags are parsed but missing from shipped `--help`: `--replay`, `--max-cost`, `--max-time`, `--without-proxy`, and `--ignore-data-mismatch`. Their entries identify the help-parity gap.

Since markers use the earliest release in the pinned changelog range, `0.1.26` through `0.10.0`, that introduced a flag. Supported markers here are `--replay` (0.5.6), `--no-wipe` (0.7.3), `--force` (0.1.34), `--attach` (0.1.46), `--max-cost` and `--max-time` (0.6.1), and `--ignore-data-mismatch` (0.1.44). The `--validate` abort-in-loop warning dates from 0.7.3. The `--no-autostart` since-version and the deprecation version for `--ignore-data-mismatch` are not recorded in the pinned changelog, so those markers remain absent.

For rejected argument forms, see the captured diagnostics under [Command grammar](#command-grammar-one-binary-no-subcommands).

## Command grammar: one binary, no subcommands

Before the individual flags, it helps to know how the parser reads a command line, because several flags only make sense relative to the positional arguments. Hankweave accepts `hankweave [options] [config-or-data-path]`. Running a hank is the default operation; there are no subcommands.

The parser accepts at most two positional paths. When both are present, the first is the hank path and the second is the data path. The preferred value form is `--flag <value>`.

A mode is a flag, not a subcommand. `--version`, `--help`, `--init`, `--validate`, and `--cleanup` take early-exit paths before run startup. `--attach` attaches the TUI without starting a run; shipped help labels it read-only, but its authority is client-side rather than server-enforced. `--replay` is a run mode rather than an early exit.

How a single positional is interpreted depends on its shape. A positional ending in `.json` or matching the parser's remote heuristic (`https://`, `http://`, or `git@`) is the hank path; the resolver accepts only the hosts listed in [Remote hank reference](#remote-hank-reference). Any other single positional is the data path, and the hank defaults to `hank.json`. A lone positional `-` reads stdin as the data source; `--data -` is not that spelling, because `--data` requires a value and a following `-` is rejected as a missing value. Two positionals are the hank path followed by the data path. More than two are rejected.

The deprecated `--flag=value` form is accepted for value flags and prints a deprecation warning. A boolean written with `=value` is rejected with `Flag '…' does not take a value.` A value flag without a value is rejected with `Flag '…' requires a value.`

Two inputs do not reach the parser's normal path at all: bare `hankweave` and `hankweave -m opus` launch the welcome wizard and exit without running anything. The inputs that trigger this welcome flow are documented in [first run](/0.10.0/files/start/first-run).

The four captures below show the parser's rejection diagnostics, one per failure class: an unknown flag, a boolean given a value, a value flag missing its value, and a third positional. Each exits with status 1 and a single-line error.

*Unknown argument; output=v0.10.0.*

```text
Error: Unknown argument '--frobnicate'. Run with --help for available options.
exit=1
```

*Boolean with a value; output=v0.10.0.*

```text
Error: Flag '--headless' does not take a value.
exit=1
```

*Missing value; output=v0.10.0.*

```text
Error: Flag '--port' requires a value.
exit=1
```

*Too many positionals; output=v0.10.0.*

```text
Error: Too many positional arguments. Expected at most 2 (hank-path, data-path), got 3.
exit=1
```

By contrast, the next capture shows the deprecated `--flag=value` spelling being accepted: two deprecation warnings print, then validation proceeds normally and exits 0. It is marked `output=v0.10.0`.

```text
⚠️  Deprecation warning: '--config=hank.json' uses deprecated syntax. Use '--config <value>' instead.
⚠️  Deprecation warning: '--data=data/' uses deprecated syntax. Use '--data <value>' instead.

╭────────────────────────────────────────────────────────────────────╮
│  Hankweave v0.10.0                                                 │
│  darwin arm64 • node v23.8.0                                       │
╰────────────────────────────────────────────────────────────────────╯

Calculating data signature for validation...

> Validating configuration: <workspace>/fixtures/scenarios/cli-flags/hank.json

  Data source:    <workspace>/fixtures/scenarios/cli-flags/data
  Execution path: ~/.hankweave-executions/validation-<id>

✓ Configuration is valid!

╭──────────────────────────────────────────────────────────────────────────────╮
│  CLI flags v1.0.0                                                            │
│  1 codon • 0 loops                                                           │
╰──────────────────────────────────────────────────────────────────────────────╯

└─ [1] write-line (Write one line)
      model: haiku │ mode: fresh │ prompts: 1 (2 lines)
      checkpointedGlobs: 1

╭─ GOOD TO RUN! ─────────────────────────────────────────────────────╮
│  1 codons • 1 prompts • 0 system prompts • 0 rigs • 1 checkpoints  │
╰────────────────────────────────────────────────────────────────────╯

Run it:  hankweave hank.json <data_path>

exit=0
```

The path-resolution rules behind these cases are covered in [hank JSON paths](/0.10.0/files/reference/hank-json) and [the runbook](/0.10.0/files/operate/runbook). The wizard cases are owned by [first run](/0.10.0/files/start/first-run).

## Execution control flags

These flags decide which execution directory a run uses, whether it resumes or starts fresh, and how much of the previous state survives.

### `-e, --execution <path>`

Uses a specific execution directory, creating it when absent and resuming it when it has state.

Value flag; alias `-e`; `path` is an execution-directory path; `// default: unset`.

The state is the `.hankweave/` state folder inside the execution directory. A clean `-e` resume requires `.hankweave/execution-meta.json` whose recorded `dataHash` matches the freshly computed data hash. A mismatch errors and requires `--force` or the deprecated `--ignore-data-mismatch`. The separate Tier 2 case is `--start-new` over a directory that already contains `.hankweave/`; it requires `--force` before the old state is moved aside.

`npx hankweave@0.10.0 --execution ./my-exec` selects a specific execution directory.

[execution recovery](/0.10.0/files/operate/resume-rollback-and-retry).

### `-n, --new, --start-new`

Starts a new execution and never resumes.

Boolean flag; aliases `-n`, `--new`, and `--start-new`; `// default: unset`.

Without `-e`/`--execution`, `--start-new` creates a new managed execution directory; `--force` does not select or overwrite a previous managed workspace. When an existing execution is explicitly selected with `-e`, `--start-new --force` starts fresh there; the existing `agentRoot/` is removed unless `--no-wipe` is also passed.

`npx hankweave@0.10.0 ./my-project -n` starts a fresh managed execution.

[runbook recovery](/0.10.0/files/operate/resume-rollback-and-retry).

<a id="-f---force"></a>

### `-f, --force` (0.1.34+)

Overrides safety checks for a data-source signature mismatch or existing state.

Boolean flag; alias `-f`; `// default: unset`.

The data-source signature is recorded silently at ordinary execution setup (`dataHash`) and compared when an execution resumes. `--validate` prints `Calculating data signature for validation…`; a resume mismatch either errors with the data-source-changed message and Expected/Current hashes or, with `--force`, warns `Data source mismatch (ignored via --force)` with those hashes. `--force` does not choose a prior managed execution: backup and workspace handling apply when an existing execution is explicitly selected with `-e`. In that case, `--start-new --force` wipes the selected `agentRoot/` unless `--no-wipe` is passed. Tier-2 backup and recovery are defined in [three tiers for an execution directory](#three-tiers-for-an-execution-directory).

For a prepared hank and data source, `npx hankweave@0.10.0 --config ./test-hank.json --data ./prepared-data --execution ./named-execution --start-new --force --no-wipe` starts fresh in the named execution while retaining its `agentRoot/`.

[execution-directory safety](#keep-execution-directories-safe).

<a id="--no-wipe"></a>

### `--no-wipe` (0.7.3+)

With `--start-new --force`, preserves the existing `agentRoot/` workspace instead of wiping it.

Boolean flag; no short alias; `// default: unset`.

It changes the workspace outcome only for the `--start-new --force` combination. It does not itself request a new execution.

With prepared `./test-hank.json`, `./prepared-data`, and `./named-execution` paths, add `--no-wipe` to an explicit `--execution ./named-execution --start-new --force` invocation to retain that execution's `agentRoot/`.

[execution-directory safety](#keep-execution-directories-safe).

### `-y`

Skips confirmation prompts for non-interactive operation.

Boolean flag; no long alias; `// default: unset`.

`-y` also skips the confirmation used by `--cleanup`.

`npx hankweave@0.10.0 --cleanup -y` skips the cleanup confirmation prompt.

[`--cleanup`](#--cleanup).

<a id="--ignore-data-mismatch"></a>

### `--ignore-data-mismatch` (0.1.44+)

Is a deprecated spelling for overriding a data-source mismatch.

Boolean flag; no short alias; `// default: unset`.

Absent from shipped help. Prints `⚠️  --ignore-data-mismatch is deprecated. Use --force instead.` Use `--force` to override a data-source mismatch.

[`--force`](#-f---force).

### `--ignore-rig-failures`

Tells the runtime to ignore setup failures.

Boolean flag; no short alias; `// default: unset`.

A **rig** is the workspace preparation - shell commands and file copies - that executes before the agent process starts. `rigSetup` configures that preparation in a codon definition. This flag is present in the parser and shipped-help inventory.

[rigs](/0.10.0/files/concepts/rigs).

## Keep or replace output files

By default a run's outputs stay inside its execution directory. These flags control whether they are copied elsewhere, how name collisions are handled, and how the data source itself is connected.

### `-o, --output <path>`

Copies outputs to the specified path.

Value flag; aliases `-o` and `--output`; `path` is an output destination; `// default: stay in ~/.hankweave-executions/{id}/agentRoot`.

Without this flag, outputs remain in the execution directory's `agentRoot/`. There is no default results directory.

> **Pitfall:** If a hank declares no `outputFiles`, `-o <path>` copies nothing; its artifacts remain in the execution's `agentRoot/`.

This is a command fragment; add `--output ./results` to an invocation that names its hank and data paths.

[runbook output locations](/0.10.0/files/operate/runbook).

### `--overwrite-output`

Overwrites existing output files instead of renaming them.

Boolean flag; no short alias; `// default: unset`.

Without this flag, an existing `file.txt` stays in place and the incoming output is written beside it as `file_1_<timestamp>.txt`.

[`--output`](#-o---output-path).

### `--copy`

Copies the data source into the execution directory instead of symlinking it.

Boolean flag; no short alias; `// default: unset`.

The default data-source connection is a symbolic link, a filesystem entry that points to another path. `--copy` selects a copy instead.

This is a command fragment; add `--copy` to an invocation that names its hank and data paths.

[runbook data handling](/0.10.0/files/operate/runbook).

## Configuration and input flags

A run needs a hank, a data source, and a model. These flags supply or override each of them, and the precedence rules between them matter: when several spellings are present, only one wins.

### `--config <path>`

Names the hank file explicitly.

Value flag; no short alias; `path` is a hank path; `// default: resolved by the config search order`.

Config resolution checks explicit `--config` or a positional hank path first; a directory resolves to the `hank.json` inside it. It then discovers `hank.json` in the data directory, and finally uses `./hank.json`. This flag is an alternative spelling for the hank-path positional.

`--config ./hank.json` names the configuration file.

[hank JSON paths](/0.10.0/files/reference/hank-json).

### `--data <path>`

Names the data source.

Value flag; no short alias; `path` is a data-source path; `// default: original working directory (or the recorded -e data path when resuming)`.

`--data` is an alternative spelling for the data-path positional. With no explicit data path, the data source defaults to the original working directory; when resuming an existing `-e` execution without an explicit data path, Hankweave reuses the recorded path from `<exec>/.hankweave/execution-meta.json`. Data selection is subordinate to inline `--input` and the positional data path: when both a positional data path and `--data` are supplied, the positional path wins; `--input` wins over both.

`--data ./data` names the data source when no positional data path takes precedence.

[`--input`](#-i---input-text).

### `-i, --input <text>`

Uses inline text as the data input.

Value flag; aliases `-i` and `--input`; `text` is inline data; `// default: unset`.

Input precedence is `--input` first, the positional data path second, and `--data` third.

`--input '<text>'` supplies inline data.

[`--data`](#--data-path).

### `-m, --model <model>`

Overrides the model for all codons.

Value flag; aliases `-m` and `--model`; `model` is a model shortcut or spelling; `// default: per-codon configuration`.

Shortcuts such as `sonnet`, `opus`, and `gemini-flash` are resolved and validated when the hank loads. The override applies to every codon. See [Model resolution](/0.10.0/files/reference/model-resolution) for shortcut expansion.

`npx hankweave@0.10.0 --config ./hank.json --data ./data --model opus` applies the `opus` shortcut to all codons.

[model resolution](/0.10.0/files/reference/model-resolution).

### `--anthropic-base-url <url>`

Provides the Anthropic API base URL.

Value flag; no short alias; `url` is a URL; `// default: unset`.

### Hank-level overrides

CLI flags are not the only source of configuration. A hank's root-level `overrides` object contributes configuration before command-line run caps are applied.

The object contains `model`, `dataHashTimeLimit`, `sentinel`, `shimIdleTimeout`, and `budget`; its field shape is owned by [hanks](/0.10.0/files/concepts/hanks).

For normal runtime fields, precedence is CLI > `HANKWEAVE_RUNTIME_*` environment > hank `overrides` > `hankweave.json` > defaults. Budget ceilings are special: runtime-config and hank-override `maxDollars`/`maxTimeSeconds` combine with `min()` (the tighter ceiling), while an explicit CLI `--max-cost`/`--max-time` replaces that result; runtime environment parsing does not provide budget settings. A per-codon `shimIdleTimeout` overrides hank-level and runtime defaults. The `hankweave.json` keys `dataHashTimeLimit` and `withoutProxy` are documented on [Hankweave JSON](/0.10.0/files/reference/hankweave-json). Sentinel behavior and output-path rules are documented on [sentinels](/0.10.0/files/concepts/sentinels) and [sentinel configuration](/0.10.0/files/reference/sentinel-config). The field name `sentinel` is retained here; its behavior belongs to the linked pages.

[hank JSON](/0.10.0/files/reference/hank-json), [Hankweave JSON](/0.10.0/files/reference/hankweave-json), [sentinel configuration](/0.10.0/files/reference/sentinel-config), and [budgets](/0.10.0/files/concepts/budgets).

## Server, TUI and connection flags

A terminal user interface (TUI) is Hankweave's terminal interface. The runtime also starts a WebSocket server, a network connection that streams events and accepts commands. The server binds without an explicit hostname, and the control channel has no authentication or isolated read-only authority: it accepts the client's requested handshake mode, and even its read-only command set includes shutdown commands. Keep a published port on a trusted local or private network; an attached TUI's client-side guards do not secure the channel. LLM-proxy traffic is a separate concern.

### `-p, --port <port>`

Sets the WebSocket server port.

Value flag; aliases `-p` and `--port`; `port` is a port number; `// default: 0 (OS-assigned free port)`.

The selected port appears in the startup box as `WebSocket: ws://localhost:<port>` and, in headless mode, as `Running in headless mode on port <n>`. It is persisted at `<execution-dir>/.hankweave/runtime.lock`; `--attach` also uses that file. The captured startup excerpt below, marked `output=v0.10.0`, shows both lines.

```text
══════════════════════════════════════════════════
  Hankweave Server Started
  WebSocket: ws://localhost:<port>
══════════════════════════════════════════════════

Running in headless mode on port <port>
```

[WebSocket quickstart](/0.10.0/files/integrate/websocket-quickstart).

### `--headless`

Runs without the TUI.

Boolean flag; no short alias; `// default: unset`.

Headless mode is intended for continuous integration and delivery (CI/CD) and scripts. It still starts the WebSocket server and reports the selected port in the headless startup line.

This is a command fragment; add `--headless` to an invocation that names its hank and data paths.

[runbook headless operation](/0.10.0/files/operate/runbook).

### `--no-autostart`

Prevents codons from starting automatically.

Boolean flag; no short alias; `// default: autostart true`.

Autostart means codons start running as soon as a client connects; in headless mode, the runtime triggers autostart immediately after the server starts without waiting for a client handshake. With this flag, the server remains available and prints `Autostart disabled, waiting for WebSocket commands...`. An operator can attach a client or inspect state before a codon or spend begins. There is no `--autostart` flag.

This is a command fragment; add `--no-autostart` to an invocation that names its hank and data paths.

[runbook server control](/0.10.0/files/operate/runbook).

### `--proxy`

Enables the internal LLM-proxy server.

Boolean flag; no short alias; `// default: disabled`.

The configuration counterpart is `withoutProxy`; it is true by default, so this flag enables the proxy.

This is a command fragment; add `--proxy` to an invocation that names its hank and data paths.

[LLM proxy](/0.10.0/files/reference/llm-proxy).

### `--without-proxy`

Keeps the internal LLM proxy disabled.

Boolean flag; no short alias; `// default: disabled`.

Accepted by the parser but absent from shipped help. This backward-compatibility spelling is redundant because the proxy is already disabled by default. See [Hankweave JSON](/0.10.0/files/reference/hankweave-json) for the `withoutProxy` configuration key.

[`--proxy`](#--proxy).

<a id="--attach"></a>

### `--attach` (0.1.46+)

Attaches the TUI to an already-running server; shipped help labels the attachment read-only.

Boolean flag; no short alias; `// default: unset`.

Port discovery checks an explicit `--port` first, then the port in `<execution>/.hankweave/runtime.lock`, then `7777`. An unreadable lock file exits with status 1 and prints `Use --port to specify the server port directly.` The attach path does not start a run. Its handshake requests read-and-write access, while the attached TUI disables the `n`, `s`, `f`, and `r` mutating hotkeys and makes `q` disconnect; those are client-side guards, not server-enforced read-only authority.

`npx hankweave@0.10.0 --execution ./my-exec --attach` connects to the server recorded for that execution.

[execution directory](/0.10.0/files/reference/execution-directory).

## Timeouts, budgets and limits

These flags bound how long a run may idle, how much it may spend, and how long it may take. Two of them - `--max-cost` and `--max-time` - work but are missing from shipped help, and one (`--max-time`) has an enforcement caveat worth reading before you rely on it.

### `--idle-timeout <seconds>`

Bounds WebSocket and proxy idle time.

Value flag; no short alias; `seconds` is a positive integer from 1 through 255 at the command line; `// default: 0 (disabled)`.

Shipped help documents `0-255, default: 0` (disabled). The parser rejects an explicit `0` with `Invalid --idle-timeout value: "0" (must be a positive integer, max 255)`, so `0` cannot currently be passed on the command line even though it is the documented default. The runtime configuration schema accepts the full `0-255` range, including `0`. The captured diagnostic below is marked `output=v0.10.0`.

```text
Error: Invalid --idle-timeout value: "0" (must be a positive integer, max 255)
exit=1
```

[Hankweave JSON](/0.10.0/files/reference/hankweave-json).

### `--shim-idle-timeout <seconds>`

Sets the per-codon harness - an in-process agent runner - idle timeout.

Value flag; no short alias; `seconds` is a positive integer up to 1800; `// default: 180 (Claude SDK) or 120 (Pi SDK), per codon`.

This is the harness/agent-event idle knob. A **harness** is an in-process agent runner. Hankweave dispatches codons through the embedded Pi SDK harness or the Claude Agent SDK harness; their stream-inactivity defaults are 120 seconds and 180 seconds, respectively. The `shim` in the name is historical; subprocess shims were removed in 0.8.0. This timeout is distinct from `--idle-timeout`, the WebSocket-and-proxy server timer.

`npx hankweave@0.10.0 --config ./hank.json --data ./data --shim-idle-timeout 120` sets the Pi SDK's documented default explicitly.

[model resolution and harnesses](/0.10.0/files/reference/model-resolution).

<a id="--max-cost-dollars"></a>

### `--max-cost <dollars>` (0.6.1+)

Sets a run-level dollar cap.

Value flag; no short alias; `dollars` is a positive number stored as `budget.maxDollars`; `// default: unset`.

Accepted by the parser but absent from shipped `--help`. A non-numeric value is rejected, as the captured diagnostic below shows; it is marked `output=v0.10.0`.

```text
Error: Invalid --max-cost value: "abc" (must be a positive number)
exit=1
```

[budgets](/0.10.0/files/concepts/budgets).

<a id="--max-time-seconds"></a>

### `--max-time <seconds>` (0.6.1+)

Sets a run-level time cap.

Value flag; no short alias; `seconds` is a positive number stored as `budget.maxTimeSeconds`; `// default: unset`.

This parser-real flag is absent from shipped `--help` and carries a help-parity note. The budget tracker checks elapsed time on cost updates and on an independent 1000 ms watchdog. When the cap is exceeded it emits a duration-exceeded event and the codon runner requests SIGTERM; that request does not prove prompt harness teardown. An older observed attempt ran a codon for roughly 24,923 seconds against a 2,400-second cap; the source/runtime cause is unresolved. For unattended work, use an external process deadline; this flag does not promise recovery of saved run state.

[budgets](/0.10.0/files/concepts/budgets).

### `--replay <dir>` (0.5.6+)

Replays from an execution-directory dump.

Value flag; no short alias; `dir` is an execution directory; `// default: unset`.

An execution-directory dump is a kept or copied execution directory. Replay copies it to a temporary location, preserves the source as read-only, and removes the copied runtime lock. When they are not supplied explicitly, the hank configuration and data source come from `<dir>/.hankweave/execution-meta.json`. `--replay` and `--execution` are mutually exclusive. Replay starts a fresh run that reproduces recorded codon LLM output; it skips rig setup, sentinels, and self-tests, so it does not prove changed rigs or external side effects. The copied directory is removed when the process exits. This parser-real flag is absent from shipped `--help` and carries a help-parity note. A completed-execution capture exited 0 and left the original state and journal byte-identical; a capture-imposed timeout is not a runtime failure code. Replay is not an absolute offline or zero-bill guarantee.

The capture below, marked `output=v0.10.0`, shows a completed-execution replay where the hank and data source were discovered from metadata. Invoke it with `npx hankweave@0.10.0 --replay ./saved-execution`; supply neither `--execution` nor a second execution path.

```text

╭────────────────────────────────────────────────────────────────────╮
│  Hankweave v0.10.0                                                 │
│  darwin arm64 • node v23.8.0                                       │
╰────────────────────────────────────────────────────────────────────╯

[REPLAY] Using hank config from execution metadata: <workspace>/fixtures/scenarios/silent-reuse/hank.json
[REPLAY] Using data source from execution metadata: <workspace>/fixtures/scenarios/silent-reuse/data
[REPLAY] Copied execution dir to <capture-attempt><tmp>/hankweave-replay-1788702367070-4s0v
Resuming: hankweave-replay-1788702367070-4s0v
  Source → data
  Exec   → <capture-attempt><tmp>/hankweave-replay-1788702367070-4s0v
  SDKs   → Claude node_modules ✓

╭──────────────────────────────────────────────────────────────────────────────╮
│  Silent reuse v1.0.0                                                         │
│  1 codon • 0 loops                                                           │
╰──────────────────────────────────────────────────────────────────────────────╯

└─ [1] write-line (Write one line)
      model: haiku │ mode: fresh │ prompts: 1 (2 lines)
      checkpointedGlobs: 1


══════════════════════════════════════════════════
  Hankweave Server Started
  WebSocket: ws://localhost:<port>
══════════════════════════════════════════════════

Running in headless mode on port <port>
➜ Listening on: http://localhost:<port>/ (all interfaces)

exit=0
```

[execution directory](/0.10.0/files/reference/execution-directory) and [recovery](/0.10.0/files/operate/resume-rollback-and-retry).

### Budget and harness terms

CLI run caps apply to the budget configuration; codons are dispatched through a harness.

The two in-process harnesses are the Claude Agent SDK harness and the embedded Pi SDK harness. Their stream-inactivity defaults are 180 seconds and 120 seconds, respectively.

The normal precedence and the budget `min()` exception are defined in [Hank-level overrides](#hank-level-overrides). These are the two CLI controls that can replace the combined budget ceiling; the CLI does not enumerate individual budget outcomes here.

[budgets](/0.10.0/files/concepts/budgets) and [model resolution](/0.10.0/files/reference/model-resolution).

## Mode flags and remote hanks

Mode flags replace the default run with a single operation - validate, initialize, clean up, print help or version - and exit before run startup. This section also covers remote hank references, which change where the hank path can point, and collects the shipped help text as an appendix.

### `-v, --validate`

Validates the configuration without running it.

Boolean flag; aliases `-v` and `--validate`; `// default: unset`.

Validation is an early-exit path. It hashes inputs, resolves and validates configuration, and performs local harness, credential, and catalog checks; it does not execute codons or make a model-generation self-test. The provider registry disables health checks during validation. Validation can add `$schema` to the hank and write a temporary validation log, and Bedrock credential discovery can probe instance metadata, so this is not a universal offline or no-write guarantee. Runtime startup separately performs provider health checks, which may call `generateText("Hi", maxOutputTokens: 16)` on available registry providers and may be billable. `-v` is the short alias for validation, not version; use `--version` to print the version. The abort-in-loop warning is supported since 0.7.3. The risky-configuration warning is:

> Validation also warns about risky-but-valid configurations. For example, a loop-body codon that uses the default failure policy (`onFailure: "abort"`) gets a warning: a single transient blip on any iteration - an idle-timeout abort or a one-off provider error - would halt the entire loop run, so the warning suggests `onFailure: "retry"` (with a `retryConfig`) or `"ignore"` instead. See [what happens when a codon fails](/0.10.0/files/concepts/codons#what-happens-when-a-codon-fails).

`npx hankweave@0.10.0 --config ./hank.json --data ./data -v` validates without starting a run.

[what happens when a codon fails](/0.10.0/files/concepts/codons#what-happens-when-a-codon-fails).

### `--init`

Initializes a new hank in the current directory.

Boolean flag; no short alias; `// default: unset`.

The demo-hank scaffold changed in 0.8.0. There is no `--init <target>` value form. The current working directory must be empty; a non-empty directory produces `Directory … is not empty. Please run init in an empty directory or specify a new directory.` Select an empty target before invoking the flag:

```bash
mkdir my-hank && cd my-hank && npx hankweave@0.10.0 --init
```

The scaffold's codon table is owned by [first run](/0.10.0/files/start/first-run). Its four entries are:

| id               | model                           | promptFile                    |
| ---------------- | ------------------------------- | ----------------------------- |
| `analyze-haiku`  | `haiku`                         | `./prompts/analyze-haiku.md`  |
| `analyze-gemini` | `pi/google/gemini-2.5-flash`    | `./prompts/analyze-gemini.md` |
| `analyze-pi`     | `pi/anthropic/claude-haiku-4-5` | `./prompts/analyze-pi.md`     |
| `analyze-gpt`    | `pi/openai-codex/gpt-5.6-terra` | `./prompts/analyze-gpt.md`    |

`npx hankweave@0.10.0 --init` initializes the current empty directory.

[first run](/0.10.0/files/start/first-run).

### `--cleanup`

Runs the execution-cleanup mode.

Boolean flag; no short alias; `// default: unset`.

Cleanup is an early-exit mode. With `-e <dir>`, it removes that named directory itself recursively, including other files it contains, after confirmation; `-y` skips the confirmation. If the target contains `.hankweave/runtime.lock`, cleanup refuses with `Server is running`; this is a file-presence check, not proof of a live process, and stale locks are not silently removed. Without `-e`, the target is the newest execution sharing the current data signature. Success exits with status 0 and failure with status 1.

The captured cleanup result below, marked `output=v0.10.0`, shows one execution removed and the remaining directories listed.

```text

╭────────────────────────────────────────────────────────────────────╮
│  Hankweave v0.10.0                                                 │
│  darwin arm64 • node v23.8.0                                       │
╰────────────────────────────────────────────────────────────────────╯

Resuming execution in: ~/.hankweave-executions/<exec-id>
Resuming: <exec-id>
  Source → data-two-run
  Exec   → ~/.hankweave-executions/<exec-id>
  SDKs   →

🧹 Hankweave Cleanup Tool

The following execution directory will be removed:

📁 ~/.hankweave-executions/<exec-id>
   Created: <ts>
   Last used: <ts>
   Link type: symlink
   Original data: <workspace>/fixtures/scenarios/kill-and-resume/data-two-run
   Size: 146.2 KB

Other execution directories (will NOT be removed):
  - ~/.hankweave-executions/<exec-id>


🗑️  Removing execution directory...

✅ Removed: ~/.hankweave-executions/<exec-id>

==================================================

✅ Cleanup completed successfully!
   Removed 1 execution directory
exit=0
```

[execution directory](/0.10.0/files/reference/execution-directory).

### `--help`, `-h`

Shows the help message and exits before run startup.

Boolean flag; aliases `--help` and `-h`; `// default: unset`.

The captured help flag and execution-safety entries appear in [Shipped help](#shipped-help).

`npx hankweave@0.10.0 --help` shows the shipped help.

### `--version`

Shows the Hankweave version and exits before run startup.

Boolean flag; no short alias; `// default: unset`.

The published version is `0.10.0`; the banner identifies the artifact release.

`npx hankweave@0.10.0 --version` prints the published version.

[upgrading](/0.10.0/files/start/upgrading).

### Remote hank reference

A single positional remote reference is taken as the hank path.

A remote reference is a value; `--data` or a second positional supplies the data source.

Hankweave clones the referenced repository tree into a local cache. HTTP(S) remotes must use `github.com`, `gitlab.com`, or `bitbucket.org`; `git@…` SSH references are accepted. The ref defaults to `main` and the hank path to `hank.json`; `#ref`, `#ref/path/to/hank.json`, and `/tree/<ref>[/path]` or `/blob/<ref>[/path]` forms select a ref and in-repository hank path. A fresh fetch reports `✓ Cloned to cache`; a cached version reports `> Using cached version (fetched <date>)`. The cache lives at `os.tmpdir()/hankweave-hanks/<sha256(cloneUrl) prefix>`, and there is no explicit refresh flag. Tags and commits remain cached as immutable references. Branch caches re-check the remote tip with `git ls-remote` and refetch when it moves. The hank file and prompts come from the cloned tree, while the data source remains separately supplied.

`https://github.com/example/hankweave-hank.git#main/hank.json` supplies a supported remote hank reference; add `--data ./data` or a second positional for its data source.

[hank JSON paths](/0.10.0/files/reference/hank-json). Configuration keys and model-shortcut expansion are documented on [Hankweave JSON](/0.10.0/files/reference/hankweave-json) and [model resolution](/0.10.0/files/reference/model-resolution).

### Shipped help

The captured help flag and execution-safety entries for `output=v0.10.0` are collected here as an appendix; the lookup entries above add runtime details and constraints. The shipped `--data` and `--shim-idle-timeout` help lines are omitted because their printed defaults are stale; the lookup entries above state the current behavior.

```text
Hankweave Runtime - Codon Orchestration

Usage: hankweave [options] [config-or-data-path]

Arguments:
  config-or-data-path       Path to hank.json or project directory
                            When only one argument provided:
                            - If ends with .json: treated as hank-path
                            - Otherwise: treated as data-path

Execution Control:
  -e, --execution <path>    Use specific execution directory
                            Creates if doesn't exist, resumes if has state
  -n, --new, --start-new    Start new execution, never resume
                            Use -n -f to overwrite existing state
  -f, --force               Override safety checks (hash mismatch, existing state)
  --no-wipe                 With --start-new --force, preserve the existing
                            agentRoot/ workspace instead of wiping it
  -y                        Non-interactive mode, skip confirmation prompts

Output:
  -o, --output <path>       Copy outputs to this path (default: stay in execution dir)
  --overwrite-output        Overwrite existing output files instead of renaming

Configuration:
  --config <path>           Path to hank.json (alternative to positional arg)
```

```text
  -i, --input <text>        Use inline text as data input (highest priority)
  -m, --model <model>       Model override (sonnet|opus|gemini-flash|etc)

Server:
  -p, --port <port>         WebSocket server port (default: auto-select free port)
  --headless                Run without TUI (for CI/CD and scripts)
  --no-autostart            Don't automatically start codons
  --proxy                   Enable the LLM proxy server (disabled by default)
  --anthropic-base-url <url> Custom Anthropic API base URL
  --idle-timeout <seconds>  Idle timeout for WebSocket and proxy servers (0-255, default: 0)
```

```text

Other:
  --init                    Initialize a new hank in current directory
  -v, --validate            Validate configuration without running
  --cleanup                 Remove execution artifacts
  --copy                    Copy data instead of symlinking (for compatibility)
  --ignore-rig-failures     Ignore rig setup failures
  --attach                  Connect TUI to an already-running server (read-only mode)
  -h, --help                Show this help
  --version                 Show version

Execution Safety:
  Hankweave implements a three-tier safety system for execution directories:
  - Tier 1: Cannot use ~/.hankweave-executions/ directly (reserved for auto-managed)
  - Tier 2: Directories with existing .hankweave/ require --force (backs up existing)
  - Tier 3: Non-empty directories show warning and prompt for confirmation
```

## Keep execution directories safe

### Three tiers for an execution directory

Hankweave applies a three-tier safety contract to execution directories, so that pointing `-e` at the wrong directory fails loudly instead of destroying state.

Tier 1 is the auto-managed root; Tier 2 is a directory containing `.hankweave/`; Tier 3 is a non-empty directory without that state folder. The shipped help defines the tiers as follows:

```text
Execution Safety:
  Hankweave implements a three-tier safety system for execution directories:
  - Tier 1: Cannot use ~/.hankweave-executions/ directly (reserved for auto-managed)
  - Tier 2: Directories with existing .hankweave/ require --force (backs up existing)
  - Tier 3: Non-empty directories show warning and prompt for confirmation
```

The `-e` state behavior and `--force` data-signature behavior appear in [execution control flags](#execution-control-flags). In Tier 2, `--start-new --force` renames `.hankweave/` to `.hankweave.backup-{timestamp}` and prints `Backed up existing execution to: <path>`. Hankweave ships no restore command; recovery is renaming that backup back to `.hankweave/`. The backup keeps its checkpoint git store at `checkpoints/.hankweavecheckpoints`; legacy `.git` checkpoints migrate on load.

[`--force`](#-f---force) and [`--no-wipe`](#--no-wipe).

## Flags that don't exist (and what to type instead)

<a id="phantom-options-and-their-supported-forms"></a>

Several plausible spellings are not part of the 0.10.0 CLI. If you reach for one of them, use the replacement below.

| Requested spelling       | What to type instead                                                                                   |
| ------------------------ | ------------------------------------------------------------------------------------------------------ |
| `--autostart`            | Nothing; autostart is enabled by default, and `--no-autostart` disables it.                            |
| `--start-at`, `--end-at` | No codon-range flag exists.                                                                            |
| `--resume`               | `-e`/`--execution`, or rerun the same command. Use `-e` when the execution directory must be explicit. |
| `hankweave run`          | `hankweave [options] [config-or-data-path]`; running is the default operation.                         |
| `models list`            | No model-listing command exists; model validity is checked when the hank loads or with `--validate`.   |

`--autostart` is not an alternate spelling of `--no-autostart`. There is no `hankweave run` subcommand, and there are no `models list`, `--resume`, `--start-at`, or `--end-at` commands or flags. A bare rerun selects the newest execution sharing the current invocation's data signature.

`npx hankweave@0.10.0 --execution ./execution` selects an execution to resume. Add `--no-autostart` to a command that names its hank and data paths when the server must wait for a WebSocket command.

[command grammar](#command-grammar-one-binary-no-subcommands) and [model configuration](#-m---model-model).

<a id="find-exit-code-ownership"></a>

## Exit codes

<a id="where-exit-codes-are-documented"></a>

Exit statuses and failure classification are documented on their own page: see [Errors and exit codes](/0.10.0/files/reference/errors-and-exit-codes).