CLI Reference

Table of Contents

• Global Options
• Environment Variables
• Setup
  • hence plan init
  • hence plan validate
• Plan Views
  • hence plan board
  • hence plan status
  • hence plan summary
  • hence plan info
• Task Lifecycle
  • hence task next
  • hence task assign
  • hence task claim
  • hence task unclaim
  • hence task complete
  • hence task block
  • hence task unblock
  • hence task assert
• Query & Explanation
  • hence query explain
  • hence query why-not
  • hence query require
  • hence query what-if
  • hence query describe
  • hence query trace
• Agent Management
  • hence agent whoami
  • hence agent spawn
  • hence agent watch
• Remote Plans (hence.run)
  • hence remote new
  • hence remote cp
  • hence remote ls
  • hence remote rm
  • hence remote serve
  • hence remote forget
• Utility
  • hence llm
  • hence plan translate
  • hence plan review
  • hence repl
  • hence session
  • hence sessions
  • hence completions
  • hence skill install

Global Options

These flags are accepted by every hence command. They can appear before or after the subcommand. Values set via flags take precedence over environment variables.

Environment Variables

Environment variables provide defaults that apply across your shell session. They are convenient for interactive use and in CI pipelines where specifying flags on every command would be repetitive.

# Set once, omit from every command
export HENCE_AGENT=alice
export HENCE_PLAN=plan.spl

hence task next          # equivalent to: hence task next plan.spl --agent alice
hence plan board         # equivalent to: hence plan board plan.spl

Setup

Commands for creating and validating plan files before any agents start working.

hence plan init <file.spl>

Create a new plan file from a template. The generated .spl file contains a skeleton with all mandatory sections filled in with placeholder values: a (meta plan ...) block, an (agents ...) block, a sample task with readiness rules, and default assignment rules. Open the file and replace the placeholders to describe your actual project.

Synopsis

hence plan init <file.spl>

Arguments

Examples

hence plan init project.spl
hence plan init ~/work/my-feature/plan.spl

hence plan validate <file> [--strict] [--json]

Parse and type-check a plan file, reporting all errors and warnings. The validator checks for syntax errors, undefined task references in dependency edges, duplicate IDs, unreachable tasks, and other structural problems. Use this command in CI before merging changes to a plan.

Synopsis

hence plan validate <file> [--strict] [--json]

Arguments & Flags

Examples

# Basic validation — shows errors and warnings
hence plan validate plan.spl

# Fail on any warning (good for CI)
hence plan validate plan.spl --strict

# Machine-readable output for tooling
hence plan validate plan.spl --strict --json

Plan Views

Read-only commands that render different projections of a plan's current state. None of these commands modify the plan file.

hence plan board <file> [OPTIONS]

Render a Kanban-style task board in the terminal. Tasks are organised into five columns: BACKLOG (not yet ready), READY (assignable), IN PROGRESS (claimed), BLOCKED, and DONE. This is the primary day-to-day view for humans monitoring a running plan.

Synopsis

hence plan board <file> [--agent NAME] [-v] [--tree] [--dag] [--json] [--format FORMAT]

Flags

Examples

# Default Kanban board
hence plan board plan.spl

# Verbose board with descriptions
hence plan board plan.spl -v

# Show only alice's tasks
hence plan board plan.spl --agent alice

# Dependency tree view
hence plan board plan.spl --tree

# DAG view
hence plan board plan.spl --dag

# Machine-readable JSON for scripting
hence plan board plan.spl --agent alice --json

hence plan status <file> [OPTIONS]

Display every fact and rule conclusion currently provable by the defeasible reasoner. This is the authoritative low-level view of what the reasoner "knows" about a plan at a given moment. Useful for debugging unexpected board states — if a task is not appearing as READY, plan status will show you exactly which conclusions are present and which are absent.

Synopsis

hence plan status <file> [--json] [--trust] [--at TIME] [--policy FILE]

Flags

Examples

# List all derived conclusions
hence plan status plan.spl

# Machine-readable output
hence plan status plan.spl --json

# Show trust weights
hence plan status plan.spl --trust

# Reason as-of a historical point in time
hence plan status plan.spl --at 2026-01-15T10:00:00Z

hence plan summary <file> [--json]

Print a compact progress overview for the plan. Shows total task count, a breakdown of tasks by state (BACKLOG / READY / IN PROGRESS / BLOCKED / DONE), and an overall completion percentage. Intended for quick status checks and dashboard integrations.

Synopsis

hence plan summary <file> [--json]

Flags

Examples

hence plan summary plan.spl

# Machine-readable summary
hence plan summary plan.spl --json

Example output:

Plan: My Feature (v1.0)
Tasks:  8 total  |  2 done  |  1 in-progress  |  3 ready  |  2 backlog
Progress: 25% complete

hence plan info <file> [--json]

Show the plan's metadata as declared in its (meta plan ...) block. Displays the plan's id, title, version, status, description, and author fields. Use this to quickly confirm which plan version you are working with, or to extract metadata programmatically.

Synopsis

hence plan info <file> [--json]

Flags

Examples

# Human-readable metadata
hence plan info plan.spl

# JSON for scripting
hence plan info plan.spl --json

Task Lifecycle

Commands that advance tasks through their states: from READY through IN PROGRESS to DONE (or BLOCKED). All write commands append a timestamped (claims ...) block to the plan file — they never edit existing lines, preserving a full audit trail.

hence task next <file> [--agent NAME] [--json]

Show the next available actions for the current agent. Queries the reasoner for all tasks that are READY and assigned to the agent, then prints them with copy-pasteable hence task claim commands so you can proceed immediately. This is the recommended starting point at the beginning of each work session.

Synopsis

hence task next <file> [--agent NAME] [--json]

Flags

Examples

# Set your agent identity once
export HENCE_AGENT=alice

# See what to work on next
hence task next plan.spl

# Check tasks for a different agent
hence task next plan.spl --agent bob

# JSON output for automation
hence task next plan.spl --json

hence task assign [file] [--json]

Display all agent-to-task assignment conclusions currently derived by the reasoner. Lists every assign-to-TASK-AGENT fact that is currently provable.

Synopsis

hence task assign [file] [--json]

Flags

Examples

# All current assignments
hence task assign plan.spl

# Assignments as JSON
hence task assign plan.spl --json

hence task claim <task> [file] [--agent NAME] [--force]

Claim a task, marking it as IN PROGRESS. Appends a timestamped (claims ...) block to the plan file containing a (given claimed-TASK) assertion, signed with the agent's identity. A task must be in the READY state before it can be claimed. Claiming is idempotent — claiming an already-claimed task by the same agent is a no-op.

Synopsis

hence task claim <task> [file] [--agent NAME] [--force]

Arguments & Flags

Examples

# Claim the "setup" task (agent from HENCE_AGENT)
hence task claim setup plan.spl

# Claim on behalf of a specific agent
hence task claim setup plan.spl --agent alice

# Force claim a task that is not yet ready
hence task claim setup plan.spl --force

hence task unclaim <task> [file]

Release a previously claimed task, reverting it to the READY state. Useful when an agent needs to hand off work or when a claim was made in error. Appends a (retracts claimed-TASK) statement to the plan file. The agent identity is always resolved from the HENCE_AGENT environment variable.

Synopsis

hence task unclaim <task> [file]

Arguments & Flags

Examples

# Release the "setup" task so another agent can claim it
hence task unclaim setup plan.spl

hence task complete <task> [file]

Mark a task as DONE. Appends (given completed-TASK) to the plan inside a signed (claims ...) block. Completing a task unlocks any downstream tasks whose readiness rules depend on this task being done — they will transition to READY on the next board refresh. The agent identity is always resolved from the HENCE_AGENT environment variable.

Synopsis

hence task complete <task> [file]

Arguments & Flags

Examples

# Mark "setup" as done
hence task complete setup plan.spl

hence task block <task> <reason> [file]

Block a task with a human-readable reason string. The task will appear as BLOCKED on the board until explicitly unblocked. Blocking is recorded as a timestamped claim so the reason and who blocked it are part of the audit trail. Use this to signal that external action is required before the task can proceed. The agent identity is always resolved from the HENCE_AGENT environment variable.

Synopsis

hence task block <task> <reason> [file]

Arguments & Flags

Examples

# Block "deploy" pending security sign-off
hence task block deploy "waiting for security sign-off" plan.spl

# Block "integrate" with a multi-word reason
hence task block integrate "third-party API returning 503" plan.spl

hence task unblock <task> [file]

Remove a block from a previously blocked task, returning it to its natural state as determined by the reasoner (typically READY if prerequisites are met). Appends a retraction of the blocking claim to the plan file. The agent identity is always resolved from the HENCE_AGENT environment variable.

Synopsis

hence task unblock <task> [file]

Arguments & Flags

Examples

# Clear the block on "deploy"
hence task unblock deploy plan.spl

hence task assert <spl> [file] [--agent NAME] [--task TASK]

Assert arbitrary SPL facts or rules into a plan. The expression is appended inside a signed (claims ...) block. This is the general-purpose escape hatch for recording findings, intermediate results, or new defeasible rules that were not anticipated at plan-authoring time. Use --task to tag the assertion with the task you are currently working on, so the provenance is clear in the audit trail.

Synopsis

hence task assert <spl> [file] [--agent NAME] [--task TASK]

Arguments & Flags

Examples

# Assert a simple fact
hence task assert '(given tests-passing)' plan.spl

# Assert a fact tagged to the current task
hence task assert '(given integration-approved)' plan.spl --task review

# Assert a new defeasible assignment rule
hence task assert '(normally r-new (and ready-x agent-y-available) assign-to-x-y)' plan.spl

Query & Explanation

Commands for introspecting the reasoner's conclusions — both what is provable and why, and what is not provable and why not. These commands are read-only.

hence query explain <literal> <file> [--json]

Show the full proof tree for a given conclusion. Explains step-by-step why the reasoner considers a literal to be true, tracing back through each rule and supporting fact. Proof nodes are annotated with provability markers: +D means definitely provable (strict proof), +d means defeasibly provable (could be defeated by a stronger rule), and -D / -d indicate unprovability.

Synopsis

hence query explain <literal> <file> [--json]

Arguments & Flags

Proof notation

Examples

# Why is "ready-auth" true?
hence query explain ready-auth plan.spl

# Explain an assignment conclusion
hence query explain assign-to-auth-coder plan.spl

# JSON proof tree for tooling
hence query explain assign-to-auth-coder plan.spl --json

hence query why-not <literal> <file> [--json]

Debug why a conclusion is not provable. Shows which preconditions are missing or which defeating rules are active. This is the primary diagnostic tool when a task is stuck in BACKLOG or an expected assignment is not appearing.

Synopsis

hence query why-not <literal> <file> [--json]

Arguments & Flags

Examples

# Why isn't "ready-deploy" provable yet?
hence query why-not ready-deploy plan.spl

# Debug a missing completion fact
hence query why-not completed-auth plan.spl --json

hence query require <literal> [file] [-v] [--assume FACTS]

Abductive reasoning: given a goal literal, compute the minimal sets of additional facts that, if asserted, would make the literal provable. This is useful for planning — it tells you exactly what needs to happen before a task can become READY or before an assignment can be made.

Synopsis

hence query require <literal> [file] [-v] [--assume FACTS]

Arguments & Flags

Examples

# What's needed to make "ready-deploy" provable?
hence query require ready-deploy plan.spl

# Same, assuming ops availability is already guaranteed
hence query require assign-to-deploy-ops plan.spl --assume 'agent-ops-available'

# Verbose output with explanations
hence query require ready-deploy plan.spl -v

hence query what-if <file> <facts...> [--json]

Hypothetical reasoning: given a set of additional facts, compute which conclusions would change compared to the current plan state. Shows new conclusions that would become provable and existing conclusions that would be retracted. Useful for reasoning about the effect of completing tasks or asserting findings before actually committing those changes to the file.

Synopsis

hence query what-if <file> <facts...> [--json]

Arguments & Flags

Examples

# What happens if tests pass and review is approved?
hence query what-if plan.spl '(given tests-passing)' '(given review-approved)'

# Hypothetical agent availability
hence query what-if plan.spl '(given agent-ops-available)' --json

hence query describe <file> <labels...> [--json]

Show the definition and metadata for one or more labeled elements in the plan — tasks, rules, agents, or other named constructs. Useful for quickly looking up what a rule does or what a task's description says without opening the raw plan file.

Synopsis

hence query describe <file> <labels...> [--json]

Arguments & Flags

Examples

# Describe a task
hence query describe plan.spl task-auth

# Describe a rule
hence query describe plan.spl r-assign-security --json

# Describe multiple elements at once
hence query describe plan.spl task-auth task-deploy r-ready-deploy

hence query trace <file>

Emit a full reasoning trace showing every rule that was evaluated during the reasoning pass: which rules fired (produced a conclusion), which were considered but did not fire (preconditions not met), and which were defeated by a higher-priority rule. Intended for deep debugging of complex defeasible reasoning scenarios.

Synopsis

hence query trace <file>

Examples

# Full reasoning trace
hence query trace plan.spl

# Pipe through a pager for large plans
hence query trace plan.spl | less

Agent Management

Commands for managing agent identity and running automated agents against plan tasks.

hence agent whoami [--json]

Display the current agent's identity information. Prints four lines to stdout: the supervisor role identity, the agent identity (using the name from HENCE_AGENT if set, otherwise the Ed25519 short ID), the evaluator role identity, and the libp2p PeerId used for P2P networking.

Synopsis

hence agent whoami [--json]

Flags

Example output

supervisor:ed25519:a1b2c3d4
agent:alice
evaluator:ed25519:e5f6g7h8
PeerId: 12D3KooWExamplePeerIdentityString

If HENCE_AGENT is not set, the agent line shows agent:ed25519:SHORTID instead of the name.

Examples

# Print identity to terminal
hence agent whoami

# Machine-readable identity (includes publicKey field)
hence agent whoami --json

hence agent spawn [file] [OPTIONS]

Spawn an automated agent to execute a plan task. spawn runs a full supervisor loop that: selects a task (or uses --task), assembles context from the plan, launches the agent provider (e.g. Claude), manages the lease and liveness heartbeat, evaluates the result, and optionally merges the output and reports completion back to the plan. This is the core command for automated multi-agent execution.

Synopsis

hence agent spawn [file] [--task TASK] [--agent NAME] [OPTIONS]

Flags

Examples

# Auto-select and execute the next available task
hence agent spawn plan.spl

# Execute a specific task with a specific provider
hence agent spawn plan.spl --task auth --agent claude

# Spawn with cleanup and JSON result
hence agent spawn plan.spl --cleanup --json

# Stream events to stdout for monitoring
hence agent spawn plan.spl --events - --session my-run

# Inspect the assembled prompt without running the agent
hence agent spawn plan.spl --dry-run --show-prompt

# Spawn with a 30-minute lease and 2-hour wall-clock timeout
hence agent spawn plan.spl --lease-ttl PT30M --timeout PT2H

hence agent watch [file] [OPTIONS]

Watch a plan file for state changes. Polls the plan and emits events whenever a task transitions state, an assignment changes, or a new claim is appended. Can optionally auto-spawn agents when tasks become READY via --spawn. Useful as a long-running daemon in CI or as a lightweight orchestrator.

Synopsis

hence agent watch [file] [OPTIONS]

Flags

Examples

# Watch for changes and print to terminal
hence agent watch plan.spl

# Watch and log events to a file
hence agent watch plan.spl --events events.jsonl

# Auto-spawn agents for ready tasks
hence agent watch plan.spl --spawn

# Auto-spawn with cleanup and a limit of 5 tasks
hence agent watch plan.spl --spawn --cleanup --max-tasks 5

# Watch with JSON output and tagged session events
hence agent watch plan.spl --json --events - --session my-run-2026

Remote Plans (hence.run)

Commands for publishing plans to hence.run and synchronising between local, peer-to-peer, and hosted remote replicas. Hosted plans on hence.run are identified by https://hence.run/p/TOKEN URLs. P2P plans are identified by hence://PASSPHRASE addresses using BIP-39 passphrases (4 words, hyphen-separated).

hence remote new [file]

Publish a local plan file to hence.run. Creates a new hosted replica and returns the https://hence.run/p/TOKEN URL for that plan. Once published, any agent with the URL can sync the plan and append claims. The file argument is optional; if omitted, HENCE_PLAN is used.

Synopsis

hence remote new [file]

Arguments

Examples

# Publish plan.spl to hence.run
hence remote new plan.spl
# → https://hence.run/p/a1b2c3d4

hence remote cp <src> [dst] [--p2p]

Copy a plan between any combination of local file paths, P2P passphrases, and hence.run-hosted URLs. Use this to push a local plan to a remote, pull a remote plan to disk, or replicate between two remotes. The destination is optional. Use --p2p to create a new P2P plan with a randomly generated BIP-39 passphrase.

Synopsis

hence remote cp <src> [dst] [--p2p]

Arguments & Flags

Examples

# Push local plan to a hosted remote
hence remote cp plan.spl https://hence.run/p/a1b2c3d4

# Pull a hosted plan to a local file
hence remote cp https://hence.run/p/a1b2c3d4 local.spl

# Create a new P2P plan from a local file (passphrase generated)
hence remote cp plan.spl --p2p

# Copy to a specific P2P passphrase
hence remote cp plan.spl hence://abandon-ability-able-about

hence remote ls [-v] [--json]

List all plans known to this installation: locally tracked plans, P2P replicas, and registered hence.run-hosted plans. Displays the plan identifier, local path (if any), and sync status for each.

Synopsis

hence remote ls [-v] [--json]

Flags

Examples

# List all registered plans
hence remote ls

# Verbose listing
hence remote ls --verbose

# Machine-readable output
hence remote ls --json

hence remote rm <plan> [--dry-run]

Archive a remote plan on hence.run. The plan is no longer served or synchronised, but its history is retained for audit purposes. This does not delete local files.

Synopsis

hence remote rm <plan> [--dry-run]

Arguments & Flags

Examples

# Archive a remote plan
hence remote rm https://hence.run/p/a1b2c3d4

# Preview what would be removed
hence remote rm https://hence.run/p/a1b2c3d4 --dry-run

hence remote serve [--listen ADDR]

Start a persistent P2P sync daemon for all registered plans. The daemon listens for incoming sync requests and keeps all local replicas up to date with remote changes. Run this in the background on an always-on machine to enable real-time collaboration without relying on hence.run polling.

Synopsis

hence remote serve [--listen ADDR]

Flags

Examples

# Start sync daemon in the foreground
hence remote serve

# Listen on a custom port
hence remote serve --listen /ip4/0.0.0.0/tcp/9000

# Run as a background process
hence remote serve &

hence remote forget [passphrase] [--dry-run]

Remove a P2P plan from this installation, identified by its BIP-39 passphrase (4 words, hyphen-separated). Deletes the local replica and clears cached credentials. Other peers still retain their copies. The passphrase argument is optional — if omitted, it is read from stdin.

Synopsis

hence remote forget [passphrase] [--dry-run]

Arguments & Flags

Examples

# Forget a P2P plan by passphrase
hence remote forget abandon-ability-able-about

# Read passphrase from stdin (e.g. piped from a secrets manager)
hence remote forget

# Preview what would be forgotten
hence remote forget abandon-ability-able-about --dry-run

Utility

Miscellaneous commands for LLM integration, translation, interactive exploration, and shell setup.

hence llm [spl|dfl]

Print the LLM reference documentation for the SPL (Structured Plan Language) or DFL (Defeasible Logic) format to stdout. Pipe this into an LLM's context window so the model understands how to read and write .spl files. This is the recommended way to inject format knowledge into an agent before asking it to author or modify a plan.

Synopsis

hence llm [spl|dfl]

Arguments

Examples

# Print SPL reference to terminal
hence llm spl

# Save to a file for use in a prompt
hence llm spl > /tmp/spl-ref.txt

# Pipe directly into an LLM call
hence llm spl | llm "Given the following SPL spec, write a plan for..."

hence plan translate <spec> [--output FILE] [--agent NAME] [--context TEXT]

Translate a markdown specification file into a complete .spl plan using a headless agent. The agent reads the specification, infers tasks, dependencies, agents, and readiness/assignment rules, and writes a plan skeleton to --output (or stdout if omitted). Review the generated plan before use — machine-generated plans may need manual refinement.

Synopsis

hence plan translate <spec> [--output FILE] [--agent NAME] [--context TEXT]

Arguments & Flags

Examples

# Translate a requirements file into a plan (output to stdout)
hence plan translate requirements.md

# Translate and save to a file
hence plan translate requirements.md --output plan.spl

# Translate using a specific agent provider
hence plan translate requirements.md --output plan.spl --agent claude

# Translate and immediately validate
hence plan translate requirements.md --output plan.spl && hence plan validate plan.spl

hence plan review <file> [--agent NAME] [--context TEXT] [--json]

Use a headless agent to review a plan for logical issues, ambiguities, missing dependencies, and potential improvements. The agent outputs a structured review report highlighting concerns ranked by severity. Does not modify the plan file.

Synopsis

hence plan review <file> [--agent NAME] [--context TEXT] [--json]

Arguments & Flags

Examples

# Review a plan with the default agent
hence plan review plan.spl

# Review using a specific agent provider
hence plan review plan.spl --agent claude

# Machine-readable review output
hence plan review plan.spl --json

hence repl [file]

Start an interactive REPL (Read-Eval-Print Loop) for querying a plan. In the REPL you can run query commands, inspect conclusions, and explore hypothetical states interactively without constructing full shell commands. If no file is provided, the REPL starts without a plan loaded and you can open one with :load <file> inside the session.

Synopsis

hence repl [file]

Arguments

Examples

# Start REPL with a plan pre-loaded
hence repl plan.spl

# Start REPL with no plan (load later with :load)
hence repl

hence session <name> [--json]

Show details for a session by name: its plan path, status, task states, and progress. The argument is a session name string, not a file path.

Synopsis

hence session <name> [--json]

Arguments & Flags

Examples

# Show details for a named session
hence session my-run-2026-01-15

# Machine-readable output
hence session my-run-2026-01-15 --json

hence sessions [--json]

List all active and recent sessions managed by this hence installation. Displays session name, associated plan path, current status, and timestamps for the most recent activity. Useful for monitoring long-running agent pipelines from a control terminal.

Synopsis

hence sessions [--json]

Flags

Examples

# List all sessions
hence sessions

# Machine-readable output
hence sessions --json

hence completions <shell>

Generate shell completion scripts for hence. Completions enable tab-completion for subcommands, flags, and plan file paths in your shell. Supported shells include bash, zsh, fish, and others. Append the output to your shell's startup file to enable completions permanently.

Synopsis

hence completions <shell>

Arguments

Examples

# Enable bash completions permanently
hence completions bash >> ~/.bashrc

# Enable zsh completions permanently
hence completions zsh >> ~/.zshrc

# Enable fish completions
hence completions fish > ~/.config/fish/completions/hence.fish

hence skill install

Install the Claude Code skill for hence. This registers hence-specific instructions and tool definitions with the Claude Code environment so that Claude can natively read plans, claim tasks, assert findings, and call other hence commands during a coding session. Run this once per machine after installing hence and Claude Code.

Synopsis

hence skill install

Examples

hence skill install

All commands accept -h, --help for inline help. Run hence --version to confirm your installed version.