CLI Reference

The Hankweave CLI is your primary interface for running hanks, validating configurations, and managing execution directories. This page covers every command, flag, and option.

Basic Usage

A Hankweave command follows this pattern:

hankweave [hank-path] [data-path] [options]

Positional Arguments:

Both positional arguments are optional. If you don't specify a hank-path, Hankweave looks for hank.json in the current directory. If you don't specify a data-path, it uses the current directory.

If you provide a single positional argument, Hankweave infers its type:

• A path ending in .json is treated as a hank-path.
• Any other path is treated as a data-path.

Quick Examples

# Run with defaults: hank.json in the current directory
hankweave
 
# Run a specific hank with data from the current directory
hankweave ./my-workflow.json
 
# Run a specific hank with a specific data directory
hankweave ./workflow.json ./my-data
 
# Run a hank from a public GitHub repository
hankweave https://github.com/user/repo ./data

Core Operations

By default, hankweave runs a hank. You can select a different operation by providing one of the following flags. These operations—run, init, validate, and cleanup—are mutually exclusive.

run (Default Operation)

Without an operation flag, hankweave runs a hank using the specified or default paths.

hankweave [hank-path] [data-path]

This is the primary mode for executing a workflow. It either starts a new execution or resumes an existing one based on the state found in the execution directory.

hankweave --init

Creates a new hank in the current directory with a set of starter files. This is a quick way to scaffold a new project and see what a complete hank looks like.

hankweave --init

This command creates:

• hank.json: A starter workflow with two example codons (using Claude Haiku and Google Gemini).
• prompts/analyze-haiku.md: A prompt template for the Claude Haiku codon.
• prompts/analyze-gemini.md: A prompt template for the Google Gemini codon.
• data/sample1.txt, data/sample2.txt, data/notes.txt: Sample data files.
• README.md: Basic documentation for your new hank.

hankweave --validate

Runs comprehensive preflight checks on a hank and its data without creating any directories or writing files. Use this to catch errors before committing a hank or running it in a CI environment.

hankweave --validate ./workflow.json ./data
# or with the short flag
hankweave -v ./workflow.json ./data

Validation catches common problems early: malformed configuration, missing prompt files, invalid rig paths, unavailable models, broken continuation dependencies, and missing environment variables. The output includes an ASCII tree visualization of the hank's structure—showing codons, loops, and their nesting—along with summaries of prompt files, rig operations, and file tracking settings.

┌─ Hank Structure ─────────────────────────────────────────┐
│  1. setup-environment                                    │
│  2. [loop: data-processing] (3 iterations)               │
│     ├─ extract-data                                      │
│     ├─ transform-data                                    │
│     └─ validate-output                                   │
│  3. generate-report                                      │
└──────────────────────────────────────────────────────────┘

hankweave --cleanup

Removes execution directories associated with a data source. As you iterate on a hank, you may accumulate multiple execution directories; this command helps you clean them up.

# Interactively clean up the latest execution for ./data
hankweave --cleanup ./data
 
# Clean up without a confirmation prompt
hankweave --cleanup -y ./data

By default, cleanup removes only the most recently created execution directory for the specified data source. Before deleting, it shows the directory's creation time, size, and data link. If a server is still running in that directory, cleanup will refuse to proceed. It also lists any other execution directories associated with the data source for your reference but does not remove them.

Options and Flags

These flags modify the behavior of the run operation.

Path and Input Options

When multiple input sources are provided, Hankweave uses this priority order:

1. --input flag
2. stdin (when data-path is -)
3. data-path file or directory

# Use inline text as input
hankweave hank.json --input "Analyze this text for sentiment."
 
# Pipe from stdin
echo "Design a REST API" | hankweave hank.json -
 
# Pipe file contents using cat
cat spec.md | hankweave hank.json --data -

Execution Control

These flags control how Hankweave manages execution directories and codon behavior.

# Force a fresh start, even if a resumable execution exists
hankweave --start-new --force
 
# Copy data instead of symlinking (e.g., for Docker volumes)
hankweave --copy ./data

Server Configuration

Hankweave runs a WebSocket server to stream events and accept commands. These flags configure it.

# Run on a specific port
hankweave --port 8080
 
# Run in headless mode for a CI/CD pipeline
hankweave --headless --autostart
 
# Attach to a running server (read-only)
hankweave --attach ws://localhost:8080
 
# Enable the LLM proxy (runs on port 8081 if main is 8080)
hankweave --proxy --port 8080

Model Configuration

Override model selection from the command line. This is useful for quick tests or for running a hank with a different model than specified in its configuration.

# Test workflow structure cheaply with Haiku (~10-20x cheaper)
hankweave --model haiku
 
# Once structure works, run with production model
hankweave --model opus
 
# Use a custom API endpoint for Anthropic models
hankweave --anthropic-base-url https://api.example.com/v1

Model shortcuts are available: opus, sonnet, haiku. For complete model configuration and authentication, see the Configuration Reference.

Help and Information

Remote Hanks

You can run a hank directly from a public Git repository without cloning it first.

# Run from the main branch of a GitHub repository
hankweave https://github.com/user/repo ./my-data
 
# Run from a specific branch or tag
hankweave https://github.com/user/repo#v1.0.0 ./data
hankweave https://github.com/user/repo/tree/feature-branch ./data

Hankweave caches remote hanks locally. Before each run, it shows when the hank was last fetched and displays a summary of its configuration, so you always know what code you're about to execute.

Execution Safety

Hankweave includes a three-tier safety system to prevent accidental data loss or corruption of existing executions.

• Tier 1: The ~/.hankweave-executions/ directory is reserved for automatically managed executions. You cannot specify it as a custom execution path.
• Tier 2: A directory with an existing .hankweave/ state folder requires the --force flag to proceed. This ensures you don't accidentally overwrite an in-progress execution.
• Tier 3: Running in a non-empty directory that doesn't meet Tier 2 conditions triggers a warning and requires confirmation before proceeding.

Execution Isolation

Hankweave never runs directly in your data directory. It creates an isolated execution directory and links to your data as read-only. This separation keeps your original data pristine, allows you to run multiple independent executions against the same data source, and preserves a complete checkpoint history for each run.

Your data is accessible inside the execution environment via a symlink (or copy, with --copy):

<execution-dir>/read_only_data_source/

Template Variables

Your prompts and hank.json configuration can reference execution paths using these template variables:

Exit Codes

Hankweave uses simple exit codes for scripting and automation:

An exit code of 1 can indicate a configuration validation failure, a missing data source, an unavailable agent SDK, a server startup failure, or a cleanup failure (such as trying to clean up an active execution).

Environment Variables

Hankweave respects several environment variables for configuration. See the Configuration Reference for a complete list. Key variables include:

Common Workflows

These patterns are common when working with the Hankweave CLI.

Development Iteration

# Start an initial run
hankweave
 
# After editing prompts or config, resume the last execution
hankweave --execution ~/.hankweave-executions/<dir-name>
 
# Force a completely new run after major changes
hankweave --start-new --force

CI/CD Pipeline

# First, validate the configuration to catch errors early
hankweave --validate ./workflow.json ./data
 
# Then, run in headless mode for automation (with autostart)
hankweave --headless --autostart ./workflow.json ./data

Testing with Different Models

# Test the workflow with a fast, cheap model
hankweave --model haiku
 
# Once validated, run with a more powerful model for final results
hankweave --model opus

Cleaning Up After Experiments

# Interactively review and remove the last execution for a data source
hankweave --cleanup ./data
 
# Non-interactively remove the last execution (e.g., in a script)
hankweave --cleanup -y ./data

Related Pages

• Getting Started — A tutorial for first-time users.
• Configuration Reference — A detailed guide to all options in hank.json.
• Debugging Guide — Strategies for troubleshooting when things go wrong.