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 – which flags the parser accepts, what values they take, what they default to, and how the shipped --help text, the parser and the runtime agree or differ. It assumes you already know what a hank is and have run one at least once; if not, start with 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.11.0, so you can see exactly what the parser prints when it accepts or rejects an invocation.

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.

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. Every one of them has a long form; -y's long alias is --yes.

The table below is the full inventory: all 34 long flags the parser accepts, each with whether it appears in shipped --help. At this release every parser-real flag is help-documented – including --replay, --max-cost, --max-time, --without-proxy and the deprecated --ignore-data-mismatch – and a help/parser parity test keeps the two lists in sync.

Since markers use the earliest release in the pinned changelog that introduced a flag; where the changelog does not record the release, the entry carries no marker. 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#

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, --cleanup, --diet-journal and --restore-journal take early-exit paths before run startup. --attach attaches the TUI without starting a run; shipped help labels it read-only, and the attached TUI's guards are client-side, while the server enforces a readonly handshake for clients that request one. --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. 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.

The wizard opens when none of the 16 inputs that leave the wizard path is present, so a flag-only invocation such as hankweave -m opus, hankweave -o ./results or hankweave --start-new launches it; a positional path or an -e <dir> execution leaves that path. The full list is documented in 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.11.0.

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

Boolean with a value; output=v0.11.0.

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

Missing value; output=v0.11.0.

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

Too many positionals; output=v0.11.0.

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.11.0; its banner line is the capture's own record of the machine that ran the command.

⚠️  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.11.0                                                 │
│  linux x64 • node v22.23.2                                         │
╰────────────────────────────────────────────────────────────────────╯

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>

Environment Variables:

  From System (HANKWEAVE_ prefixed):
    - CAPTURE_VERSION: 0.11.0
exit=0

The path-resolution rules behind these cases are covered in hank JSON paths and the runbook. The wizard cases are owned by 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.

Only an explicit -e resume compares the recorded hank hash with the current hank.json. In non-interactive mode without -y or --force it refuses with Execution setup failed: hank.json does not match the configuration recorded for this execution …; refusing to resume in non-interactive mode (exit 1); interactively it asks Continue with modified config? [y/N]. A managed resume (no -e) never reads the hank hash, so an edited hank does not stop it; --start-new is how to run the edited hank.

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

execution recovery.

-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.11.0 ./my-project -n starts a fresh managed execution.

runbook recovery.

-f, --force#

[since 0.1.34] -f, --force is available.

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.

For a prepared hank and data source, npx hankweave@0.11.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.

--no-wipe#

[since 0.7.3] --no-wipe is available.

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.

-y, --yes#

[added 0.11.0] --yes is the long alias for -y.

Skips confirmation prompts for non-interactive operation.

Boolean flag; aliases -y and --yes; // default: unset.

-y also skips the confirmation used by --cleanup. It does not change which execution a run selects, but on an explicit -e resume whose recorded hank hash differs it is what lets a non-interactive run proceed instead of refusing.

npx hankweave@0.11.0 --cleanup -y skips the cleanup confirmation prompt.

--cleanup.

--ignore-data-mismatch#

[since 0.1.44] --ignore-data-mismatch is available.

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

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

Documented in shipped help, marked [Deprecated] Use --force instead. The parser prints ⚠️ --ignore-data-mismatch is deprecated. Use --force instead.; use --force to override a data-source mismatch.

--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.

Rerunning a completed execution is announced, not silent. Without --start-new, the runtime resumes the newest managed execution whose recorded data hash matches; when that execution has already completed it prints Resumed completed execution <id> — nothing to do. All codons already completed. Use --start-new to run fresh. (on stdout under --headless; as an Info: line in the TUI), runs no codon and exits 0. --start-new remains the way to run fresh.

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 the execution directory's agent workspace (~/.hankweave-executions/{id}/agentRoot for a managed run; inside the named directory with -e).

Without an output directory, outputs remain in the execution directory's agentRoot/. There is no default results directory. The copy runs for a completed codon that declares outputFiles when an output directory is set: by -o/--output first, otherwise by the resolved outputDirectory setting (outputDirectory in hankweave.json, or HANKWEAVE_RUNTIME_OUTPUT_DIRECTORY); with neither set, outputs stay in agentRoot/. The gate is the codon's own completion, so a later codon's failure does not retract an earlier codon's copy.

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

runbook output locations.

--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.

--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.

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.

--data <path>#

Names the data source.

Value flag; no short alias; path is a data-source path; // default: the directory the command was launched from (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, whatever --config names; when resuming an existing -e execution whose .hankweave/execution-meta.json records a readOnlySourceDataPath that still exists, Hankweave reuses that recorded path and prints > Using data source from execution metadata: <path>. (--replay reads the source execution's metadata the same way.) 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. The shipped help's default: config directory line for this flag is stale.

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

--input.

-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.

-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 is stamped onto every codon at load, but it takes effect only when a plan is built: a resumed or rolled-back run reuses the models persisted in .hankweave/state.json executionPlan regardless of the startup line, so changing a model needs --start-new with a new execution directory. A loop iteration first expanded during the continued run carries the current override. See Model resolution for shortcut expansion.

npx hankweave@0.11.0 --config ./hank.json --data ./data --execution ./my-exec --start-new --model opus applies the opus shortcut to all codons in a fresh plan; without --start-new, a matching execution resumes on its saved models.

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.

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. Sentinel behavior and output-path rules are documented on sentinels and sentinel configuration. The field name sentinel is retained here; its behavior belongs to the linked pages.

hank JSON, Hankweave JSON, sentinel configuration, and 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: it accepts the client's requested handshake mode, and even its read-only command set includes shutdown commands. It does enforce a readonly handshake mode for clients that connect that way – state-modifying commands are refused server-side. 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.11.0, shows both lines.

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

Running in headless mode on port <port>

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.

--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.

--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.

--without-proxy#

Keeps the internal LLM proxy disabled.

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

Documented in shipped help. This backward-compatibility spelling is redundant because the proxy is already disabled by default. See Hankweave JSON for the withoutProxy configuration key.

--proxy.

--attach#

[since 0.1.46] --attach is available.

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 prints READ-ONLY: Commands are disabled, disables the n, s, f, and r mutating hotkeys, and makes q disconnect; those are client-side guards. The server itself enforces a readonly handshake mode for clients that request one; that protocol contract is owned by the protocol reference.

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

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. One of them (--idle-timeout) is parsed but not wired to any runtime behavior, and one (--max-time) has an enforcement caveat worth reading before you rely on it.

--idle-timeout <seconds>#

Declares a WebSocket-and-proxy idle timeout that this runtime does not consume.

Value flag; no short alias; seconds is a strict integer 0–255; // default: 0.

Shipped help documents (0-255, 0 disables, default: 0), and the parser now accepts the full range, including 0. The merged value, however, is not consumed: the WebSocket server startup and both proxy constructions omit it, so the flag sets, bounds or disables no WebSocket or proxy idle timeout. Parser acceptance, the configured default and runtime wiring are separate; the harness-level knob is --shim-idle-timeout. The captured diagnostic below, marked output=v0.11.0, shows --idle-timeout 0 accepted in a successful --validate.

╭────────────────────────────────────────────────────────────────────╮
│  Hankweave v0.11.0                                                 │
│  linux x64 • node v22.23.2                                         │
╰────────────────────────────────────────────────────────────────────╯

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>

Environment Variables:

  From System (HANKWEAVE_ prefixed):
    - CAPTURE_VERSION: 0.11.0
exit=0

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: unset (harness fallback: 180 s Claude Agent SDK, 120 s Pi SDK).

This is the harness/agent-event idle knob. A harness is an in-process agent runner. Hankweave dispatches codons through the Claude Agent SDK harness or the embedded Pi SDK harness; when neither the flag nor a hank or codon override is set, their stream-inactivity fallbacks are 180 seconds and 120 seconds, respectively. The value merges with hank overrides.shimIdleTimeout and hankweave.json (CLI highest), and a codon's own shimIdleTimeout wins over the run default. The shim in the name is historical. This timeout is distinct from --idle-timeout, the (non-operative) WebSocket-and-proxy server setting.

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

model resolution and harnesses.

--max-cost <dollars>#

[since 0.6.1] --max-cost <dollars> is available.

Sets a run-level dollar cap.

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

Documented in shipped help. A non-numeric value is rejected, as the captured diagnostic below shows; it is marked output=v0.11.0.

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

budgets.

--max-time <seconds>#

[since 0.6.1] --max-time <seconds> is available.

Sets a run-level time cap.

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

Documented in shipped help. 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.

--replay <dir>#

[since 0.5.6] --replay <dir> is available.

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 output: it makes no new codon model calls and skips rig setup, sentinels, the per-model self-tests and the Pi catalog preflight, so it does not prove changed rigs or external side effects. It does not skip the runtime's startup provider health checks, which send a short billable generateText request to every credentialed provider, so a replay is not offline or zero-bill when provider credentials are set. A clean exit 0 is a valid outcome, and a capture-imposed timeout is not a runtime failure code.

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

╭────────────────────────────────────────────────────────────────────╮
│  Hankweave v0.11.0                                                 │
│  linux x64 • node v22.23.2                                         │
╰────────────────────────────────────────────────────────────────────╯

[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-1790499103051-okkd
Removed a stale diet pair found beside the live events.jsonl (verified duplicate of the journal; interrupted prune or diet)
Resuming: hankweave-replay-1790499103051-okkd
  Source → data
  Exec   → <capture-attempt><tmp>/hankweave-replay-1790499103051-okkd
  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 and recovery.

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 fallbacks are 180 seconds and 120 seconds, respectively.

The normal precedence and the budget min() exception are defined in 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 and 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 the data, resolves and validates the configuration, and runs the same per-model harness self-test as startup: SDK availability, credential presence and, for Pi models, the model_catalog preflight. A missing key therefore fails --validate with exit 1. What validation does not prove is that the key is valid or the provider healthy: the credential check is presence-only and provider health checks are off 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; those calls happen at startup, not in --validate. -v is the short alias for validation, not version; use --version to print the version. The abort-in-loop warning is supported. 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.

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

what happens when a codon fails.

--init#

Initializes a new hank in the current directory.

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

[changed 0.8.0] The demo-hank scaffold changed.

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:

mkdir my-hank && cd my-hank && npx hankweave@0.11.0 --init

The scaffold's codon table is owned by first run. Its four entries are:

npx hankweave@0.11.0 --init initializes the current empty directory.

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.11.0, shows one execution removed and the remaining directories listed.

╭────────────────────────────────────────────────────────────────────╮
│  Hankweave v0.11.0                                                 │
│  linux x64 • node v22.23.2                                         │
╰────────────────────────────────────────────────────────────────────╯

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: 355.4 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.

--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.

npx hankweave@0.11.0 --help shows the shipped help.

--version#

Shows the Hankweave version and exits before run startup.

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

npx hankweave@0.11.0 --version prints the release documented here.

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. Configuration keys and model-shortcut expansion are documented on Hankweave JSON and model resolution.

Shipped help#

The captured help flag and execution-safety entries for output=v0.11.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. The help's --idle-timeout line says 0 disables; the shipped bytes stay as published, but the merged value is not consumed by this runtime (see the entry above).

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
  --replay <path>           Replay an execution from recorded logs (no LLM calls)
                            Mutually exclusive with --execution
  -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, --yes                 Skip confirmation prompts
  --max-cost <dollars>      Set a run-wide cost ceiling in USD
  --max-time <seconds>      Set a run-wide wall-clock limit in seconds

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)

  -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)
  --without-proxy           Disable the LLM proxy (this is the default)
  --anthropic-base-url <url>  Custom Anthropic API base URL
  --idle-timeout <seconds>  Idle timeout for WebSocket and proxy servers (0-255, 0 disables, default: 0)

Other:
  --init                    Initialize a new hank in current directory
  -v, --validate            Validate configuration without running
  --cleanup                 Remove execution artifacts
  --restore-journal <path>  Rebuild a dieted execution's event journal (byte-for-byte, verified)
  --diet-journal <path>     Compress a finished execution's event journal (restorable)
  --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)
  --ignore-data-mismatch    [Deprecated] Use --force instead
  -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:

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

Two scopes qualify the shipped lines. The Tier 1 refusal applies only when -e would create a new execution under the managed root; an existing managed execution can be passed to -e and resumed. The Tier 2 and Tier 3 checks run only with --start-new: a plain -e on a non-empty directory without .hankweave/ prints Using existing directory as execution directory: <path> and adopts it with no warning or prompt.

The -e state behavior and --force data-signature behavior appear in 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 and --no-wipe.

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

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

--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.11.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 and model configuration.

Exit codes#

Exit statuses and failure classification are documented on their own page: see Errors and exit codes.

Journal diet and restore#

Two early-exit maintenance commands compress or reconstruct a finished run's event journal. Both take the execution directory as their argument and exit before any hank configuration, SDK or server starts.

--diet-journal <execution-dir>#

[since 0.11.0] --diet-journal <execution-dir> is available.

Compresses a finished run's journal into its restorable form.

Value flag; no short alias; the argument is an execution directory; // default: unset.

The diet produces events.jsonl.zst plus journal.meta.json, and an events/cas/ store only when a body of at least 4 KB was extracted. It verifies the round-trip from disk before removing the original, and it is idempotent: a second run reports ✓ Journal already dieted (…). For its duration the command claims <exec>/.hankweave/runtime.lock, refusing a live or unprovably stale lock and leaving the original journal intact. It is not a hank launch.

npx hankweave@0.11.0 --diet-journal ./my-exec diets that execution's journal.

--restore-journal <execution-dir>#

[since 0.11.0] --restore-journal <execution-dir> is available.

Reconstructs the original journal from the dieted pair.

Value flag; no short alias; the argument is an execution directory; // default: unset.

Restore rebuilds events.jsonl byte-for-byte and verifies it against journal.meta.json's originalSha256, reporting ✓ Journal restored: … verified byte-for-byte (or ✓ Journal already restored and verified). It leaves events.jsonl.zst and journal.meta.json beside the restored file.

npx hankweave@0.11.0 --restore-journal ./my-exec restores that execution's journal for offline inspection.

Resuming or rerunning a dieted execution restores the journal in place automatically, and the runtime's own readers serve a dieted journal transparently. The journal format and the finalize-diet contract are owned by the event journal reference; this page states only the two commands.