# Start your first run without the wizard

Hankweave runs a workflow definition – a **hank** – whose individual agent tasks are called **codons**. This page takes you from an empty directory to a finished run of the starter hank: you will scaffold one with `--init`, give the runtime the provider keys it looks for, run it explicitly, and learn to recognize the failures that happen before any codon starts. Each recipe ends with a check you can perform against your own terminal, so you know the step worked before moving on. The last section covers removing old executions, because a few trial runs will leave some behind.

<a id="avoid-the-bare-invocation-wizard-trap"></a>

## Choose a launch path and avoid the bare-invocation wizard trap

There are three ways to start Hankweave, and they do different things:

* To run an existing workflow, pass its configuration file and data paths explicitly.
* To create a starter workflow, enter an empty directory and use `--init`.
* To explore the welcome choices, run the command with no arguments – but do not expect it to run a hank.

That third option is the trap this page helps you avoid. A bare invocation opens an interactive wizard; it never loads your hank. The explicit form is the one this page uses throughout:

```bash
bunx hankweave@0.10.0 hank.json data/
```

These recipes launch the package's Node entry point (`dist/index.js` starts with `#!/usr/bin/env node`) and require Node.js >=22.19.0; `bunx` is the package launcher used here, and `npx` is the equivalent spelling for a Node/npm user.

How does the runtime decide between running your hank and showing the wizard? Any recognized hank, data, initialization, help, validation, cleanup, attach, headless, or replay input leaves the wizard path; an unrelated flag such as `hankweave -m opus` does not. A single positional argument ending in `.json` or a URL is treated as a hank path; anything else is a data path. With two positional arguments, the first is the hank path and the second is the data path. Use `--input` (`-i`) for inline data; it has the highest priority among data sources. For the full argument contract, see [the CLI reference](/reference/cli).

If you do choose the wizard, this is the sequence to expect:

1. See the tesseract splash.
2. With stdin closed, read the static information and return. Otherwise, continue to the environment check.
3. The environment check looks for the Claude Code executable, treats the Pi coding agent as embedded, and reads `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` directly from the process environment while resolving `GEMINI_API_KEY` through the runtime's key resolver. For the default direct-Anthropic route, a local Claude Code login alone is not a substitute for `ANTHROPIC_API_KEY`.
4. On the first wizard run, read a one-time telemetry disclosure. It covers anonymous usage statistics, not file contents or prompts. Set `DO_NOT_TRACK=1` or `HANKWEAVE_TELEMETRY=0` to opt out; see [telemetry](/reference/telemetry) for the full policy.
5. Choose an action from the menu.

If no usable harness – a component that connects Hankweave to a model – and key combination is available, the wizard warns, "No agent harnesses are fully configured yet." It offers initialization, documentation, GitHub, and learning actions, but no demo.

When a demo is available, the wizard makes a one-token call with the cheapest registry model for the chosen provider. That call catches a dead key or billing/credit failure before the demo. The demo uses `https://github.com/SouthBridgeAI/demo-hank`, analyzes a chosen folder, and builds an HTML page. The wizard advertises a typical time of "5–10 minutes" and a typical cost of "\~$0.50–1.00"; those are its own strings, not a measurement here.

If you choose the demo, the wizard invokes the Hankweave binary again with explicit arguments and writes to `./hankweave-demo-output`. If a completed demo exists for that folder, it offers `-n` for a new run. The demo is an ordinary explicit run after the wizard's choices, not wizard-only behavior. For the provider fallback and model spellings, use the [authentication and models](/operate/authentication-and-models) reference.

One wizard behavior matters even if you never use it interactively: in the stdin-closed path, bare `hankweave` prints a static splash, returns `0`, shows no environment panel, and creates no managed execution directory under `~/.hankweave-executions/`. That makes it a safe way to confirm the package runs at all.

**Check-it 1:** from an empty directory, invoke `bunx hankweave@0.10.0 </dev/null` so stdin is closed, then inspect the shell status:

```bash
mkdir wizard-check
cd wizard-check
bunx hankweave@0.10.0 </dev/null
printf 'shell exit status: %s\n' "$?"
```

Confirm that the splash says `No hank.json found in current directory.` and that the shell exit status is `0`. The captured evidence below also includes `exit=0` and `delta 0` annotations added by the capture helper; those annotations are not lines that the command promises to print.

```text

Hankweave v0.10.0

No hank.json found in current directory.

Quick start:
  npx hankweave --init            Create a new hank here
  npx hankweave --help            Show all options
  npx hankweave <hank.json>       Run a specific hank

Docs:   https://hankweave.southbridge.ai
GitHub: https://github.com/SouthBridgeAI/hankweave-runtime

exit=0
```

```text
managed execution directories before: 0, after: 0 (delta 0)
```

## Inspect what `--init` scaffolds

With the launch paths clear, the fastest route to a first run is the starter hank. Create an empty directory, enter it, and use `--init`. The flag takes no target argument and requires an empty directory; its full CLI contract belongs to [the CLI reference](/reference/cli).

```bash
mkdir my-first-hank
cd my-first-hank
bunx hankweave@0.10.0 --init
init_status=$?
printf 'shell exit status: %s\n' "$init_status"
```

The shipped scaffold creates ten files: the hank itself, four prompt files, three sample data files, a README, and a `.gitignore`. The file list below is taken from the artifact's `Created files` output:

```text
Created files:
  - hank.json
  - prompts/analyze-haiku.md
  - prompts/analyze-gemini.md
  - prompts/analyze-pi.md
  - prompts/analyze-gpt.md
  - data/sample1.txt
  - data/sample2.txt
  - data/notes.txt
  - README.md
  - .gitignore
```

**Check-it 2:** confirm that this generated file list contains ten paths and that the `--init` command returned shell status `0`.

The scaffold's `hank` array contains four codons, one per model route. After `--init`, open `hank.json` in the directory you created and compare it against this inventory; it is the basis for deciding which codons to keep or edit. See the [hank.json reference](/reference/hank-json) for the file contract:

| Codon            | Model                           | Prompt                      | Copied output        |
| ---------------- | ------------------------------- | --------------------------- | -------------------- |
| `analyze-haiku`  | `haiku`                         | `prompts/analyze-haiku.md`  | `analysis-haiku.md`  |
| `analyze-gemini` | `pi/google/gemini-2.5-flash`    | `prompts/analyze-gemini.md` | `analysis-gemini.md` |
| `analyze-pi`     | `pi/anthropic/claude-haiku-4-5` | `prompts/analyze-pi.md`     | `analysis-pi.md`     |
| `analyze-gpt`    | `pi/openai-codex/gpt-5.6-terra` | `prompts/analyze-gpt.md`    | `analysis-gpt.md`    |

All four scaffold codons use `continuationMode: "fresh"`, one `checkpointedFiles` entry named `analysis-<x>.md`, and an `outputFiles` block with a `copy` list. The `pi/...` spelling is provider-qualified; the complete file above remains the source of the exact configuration.
The scaffold's copy blocks produce no copied output on a default run. They materialize when you pass `-o` or `--output`; see [the runbook](/operate/runbook) for output-directory behavior.

One codon deserves a closer look before you run anything: `analyze-gpt` authenticates through a ChatGPT subscription rather than `OPENAI_API_KEY`. Its exact object is available when you need to edit or remove that codon:

<details>
<summary>Inspect the shipped <code>analyze-gpt</code> codon fragment</summary>

```json
    {
      "id": "analyze-gpt",
      "name": "Analyze Project (GPT)",
      "model": "pi/openai-codex/gpt-5.6-terra",
      "continuationMode": "fresh",
      "promptFile": "./prompts/analyze-gpt.md",
      "checkpointedFiles": ["analysis-gpt.md"],
      "outputFiles": [
        {
          "copy": ["analysis-gpt.md"]
        }
      ]
    }
```

</details>

The scaffold ships a README with an Auth section, quoted below. Its parenthetical Claude Code-login hedge is stale for the default direct-Anthropic route; use the explicit key guidance that follows instead. The embedded Pi coding agent's `pi login` flow, described in [authentication and models](/operate/authentication-and-models), puts the ChatGPT-subscription credential in Pi's store:

```text
- The `haiku`, `pi/anthropic/...`, and `pi/google/...` codons need `ANTHROPIC_API_KEY` (or a Claude Code login) and `GEMINI_API_KEY`.
- The `pi/openai-codex/gpt-5.6-terra` codon runs on a **ChatGPT subscription** (no `OPENAI_API_KEY`): the OAuth credential is read from Pi's store at `~/.pi/agent/auth.json`. Put it there with `pi login` (choose "OpenAI (ChatGPT Plus/Pro)"). No subscription? Delete that codon, or switch its model to a keyed spelling like `gpt-5.5` with `OPENAI_API_KEY` set.
```

Read that quote with two corrections in mind. For the default direct-Anthropic route, use `ANTHROPIC_API_KEY`; a local Claude Code login alone fails the normal startup self-test. The internal `HW_INTERNAL_CLAUDE_LEGACY_AUTH` flag changes that behavior, but it is not a setup recipe. For the remaining scaffold routes, provide `GEMINI_API_KEY` for the Google route and `ANTHROPIC_API_KEY` for the Anthropic routes. If you do not have the ChatGPT subscription, delete the `analyze-gpt` codon object or change it to a keyed spelling such as `gpt-5.5` with `OPENAI_API_KEY` set. Keep at least one codon in the `hank` array; its configuration schema – the rule set for hank files – requires one or more items.

Once the codons match the credentials you actually have, run the scaffold explicitly:

```bash
npx hankweave@0.10.0 hank.json data/
```

> **Pitfall:** The init README tells you to run bare `npx hankweave`; that launches the wizard. Use the explicit `npx hankweave@0.10.0 hank.json data/` form for the scaffold.

## Set the keys the runtime can find

The scaffold run only succeeds if the runtime can resolve a key for each codon's route. Set provider keys in the process environment using these exact spellings: `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, and `ZAI_API_KEY`. The complete environment-variable catalog belongs to [environment variables](/reference/environment-variables).

```bash
export ANTHROPIC_API_KEY="your-anthropic-key"
export GEMINI_API_KEY="your-gemini-key"
export OPENAI_API_KEY="your-openai-key"
```

Use `GEMINI_API_KEY` for Google models. `GOOGLE_API_KEY` is not an alias in this release.

> **VersionNote:** Since 0.8.0, `--init` scaffolds four codons. The fourth authenticates through a ChatGPT subscription, and Google's key is `GEMINI_API_KEY` only.

Beyond the provider keys, the runtime passes any `HANKWEAVE_<VAR>` setting to the agent environment as `<VAR>`, with the prefix removed. That rule excludes `HANKWEAVE_RUNTIME_*` server configuration and `HANKWEAVE_SENTINEL_*` secrets. Set the value literally to `unset` – for example, `HANKWEAVE_FOO=unset` – to delete `FOO` from the agent environment, keeping secrets out of `hank.json`.

Lookup order depends on which part of the runtime asks for the variable. A `requirements.env` entry checks `<VAR>` first and then `HANKWEAVE_<VAR>`; a non-empty direct value wins. A sentinel – a separate observer of the run – checks `HANKWEAVE_SENTINEL_<VAR>` first, so the sentinel-prefixed value wins there. These lookup rules are distinct from the pass-through rule above.

The Hankweave runtime does not load a `.env` file. Put keys in the process environment. Do not assume a harness handles `.env` the same way; see [environment variables](/reference/environment-variables).

## Diagnose failures before a codon runs

If the output does not show a codon starting, inspect startup checks first. A plain run performs its self-tests even without `--validate`, so a missing key or model can stop the run before any codon runs. The failure modes below are ordered roughly by how early they strike.

**If authentication fails,** check the provider key before changing the hank. The following expected-failure capture is from the `minimal-single-provider` fixture: it shows a plain run creating an execution directory and then dying during startup self-tests. Its one-model count and model name are specific to that fixture, not a promise about the four-codon scaffold:

```text
[<ts>] [ERROR] Self-test completed: FAILED
[<ts>] [ERROR] Self-test FAILED: Some checks failed
[<ts>] [ERROR]   - authentication: ✗ No authentication found (set ANTHROPIC_API_KEY)
[ERROR] Server startup failed!
Error message: Self-test failed for 1 model(s):
  - Claude Haiku 4.5 (latest) (anthropic/claude-haiku-4-5): Some checks failed
      • authentication: No authentication found (set ANTHROPIC_API_KEY)
…
```

Use `--validate` to hash the data source, resolve and validate the hank configuration, and perform harness setup, credential, and model-catalog checks. It exits without starting the server or executing codons. Its provider registry disables provider health checks, so validation does not make a model-generation self-test. Validation can add `$schema` to the hank and write a temporary log; Bedrock credential discovery can probe instance metadata, so do not treat it as fully offline or write-free. A normal startup separately performs provider health checks, which can make `generateText("Hi", maxOutputTokens:16)` calls; see [authentication and models](/operate/authentication-and-models) for that startup mechanism.

**If the provider reports exhausted credits,** treat the result as a permanent billing-quota failure, not a retryable codon failure. The wizard's one-token demo check catches this class earlier. See [errors and exit codes](/reference/errors-and-exit-codes) for the classification.

**If you see `Pi model not found: <provider>/<id>. Available '<provider>' models: …`,** the startup `model_catalog` check could not find a Pi-routed codon's model in Pi's catalog. `Unknown pi provider '<provider>'` is the corresponding provider diagnostic. The check fails before earlier codons run and spend money. Correct the provider-qualified model or provider; model-selection details belong to [authentication and models](/operate/authentication-and-models).

If an error survives editing `hank.json`, check the provider health-check models and the two-plane mechanism in [authentication and models](/operate/authentication-and-models).

**If you see `Cannot create execution inside another execution directory`,** an explicit `-e`/`--execution` target has landed inside a managed execution directory's data path. Targeting `~/.hankweave-executions/` directly is also refused because it is reserved. Correct the `--execution` argument: choose a different explicit execution directory, or omit `-e` so the runtime allocates one, and keep the input source distinct from the execution directory. The guard checks the explicit `-e` path, not the shell's current working directory.

**Check-it 3:** in a project whose hank includes the direct-Anthropic route, unset the default key and make a plain run with its explicit hank and data paths. This deliberately reproduces the authentication failure so you can recognize it later:

```bash
env -u ANTHROPIC_API_KEY bunx hankweave@0.10.0 hank.json data/
printf 'shell exit status: %s\n' "$?"
```

Inspect the startup output for an authentication diagnostic and the nonzero status printed immediately after the run. The pinned `minimal-single-provider` capture above supplies the invariant lines `Self-test FAILED: Some checks failed`, `No authentication found (set ANTHROPIC_API_KEY)`, and `[ERROR] Server startup failed!`; its one-model count, model name, timestamps, and execution identifiers are capture-specific. On the initialized four-codon scaffold, check the diagnostic and that nonzero status rather than expecting that capture's model count or name; different routes and missing keys can produce additional startup failures.

## Remove old executions safely

Trial runs accumulate execution directories, so the last skill is deleting them without deleting the wrong thing. For the complete `--cleanup` contract, see [the CLI reference](/reference/cli). **Warning:** cleanup is destructive. With `-e`/`--execution <path>`, it selects the named directory itself and recursively removes it, including other files it contains; the data-source selection instead chooses the newest execution for a matching data source.

If the target contains `.hankweave/runtime.lock`, cleanup refuses it with `Cannot remove <dir>: Server is running` and skips it. This is a file-presence check; it does not independently prove a live process or silently remove a stale lock. Without `-y`, cleanup prompts `Proceed with cleanup? This cannot be undone! (y/N)` and proceeds only for `y` or `yes`; another response cancels without removing anything.

Keep these locations distinct, because they look similar and are easy to confuse:

* `~/.hankweave-executions/` stores managed runs. Move this pool only with `HANKWEAVE_RUNTIME_EXECUTION_BASE_DIR`.
* `~/.hankweave/` stores extracted harness components, such as `claude-sdk/<version>/`. Move this cache with `HANKWEAVE_CACHE_DIR`.
* `~/.hankweave-cache/inputs/` stores cached inline-input data.

The `executionBaseDir` field is in the separate `hankweave.json` runtime-settings file, not the scaffold's `hank.json`; it is informational-only, and nothing consumes it to relocate the executions pool. Use the `HANKWEAVE_RUNTIME_EXECUTION_BASE_DIR` environment variable when you need to move that pool. See [the hankweave.json reference](/reference/hankweave-json) for the field's contract.