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

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

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#

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

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.

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

Boolean with a value; output=v0.10.0.

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

Missing value; output=v0.10.0.

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

Too many positionals; output=v0.10.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.10.0.

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

npx hankweave@0.10.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.10.0 ./my-project -n starts a fresh managed execution.

runbook recovery.

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

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.

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

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

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

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

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.

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: 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>#

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 applies to every codon. See 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.

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

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

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 for the withoutProxy configuration key.

--proxy.

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

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.

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

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.

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

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

budgets.

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

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

╭────────────────────────────────────────────────────────────────────╮
│  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 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 defaults 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 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.

npx hankweave@0.10.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.

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:

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

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

npx hankweave@0.10.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.10.0, shows one execution removed and the remaining directories listed.

╭────────────────────────────────────────────────────────────────────╮
│  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.

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

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

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)

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

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:

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

Exit codes#

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