Command Line

-h, --help, and heph help [COMMAND...] show compact help wrapped at 80 columns, including when redirected. Flag descriptions have no blank lines between entries.

heph [OPTIONS] [SESSION FLAGS]
heph exec [OPTIONS] [FLAGS] [PROMPT]...
heph wire-check [OPTIONS] [--role ROLE] [--earlier-reasoning]
heph models [OPTIONS] [--all] [--provider ID]
heph tiers [OPTIONS] [--profile NAME] [--tier NAME=MODEL]... [--model MODEL]
heph profiles [OPTIONS]
heph skills [--ref REF] | check [PATH]... | show NAME
heph sessions [--name TEXT] [--branch TEXT] [--published] [--limit N]
              [--summary] [--json]
heph tmux status | list | next | conf

Text tables from sessions, models (including Ollama), tiers, profiles, and tmux list use serde_grid's default bordered renderer for column sizing and alignment, without command-specific padding or width rules. Chat Markdown tables are unchanged. For scripts, sessions --json and sessions --ids provide structured records or one full UUID per line.

Global options

These go before any subcommand and apply to all of them.

heph: the interactive session

With no subcommand, heph creates a fresh unnamed conversation. Trailing arguments joined with spaces supply an initial prompt; quotes preserve embedded whitespace and newlines. Session flags precede prompt arguments. Use -- for a prompt starting with a dash or a subcommand name, for example heph -- models need better error messages. Empty or whitespace-only input opens without a turn. A prompt and either resume flag are mutually exclusive. Session flags:

--review, --plan, --design, and --quick exclude each other. Session flags given beside a subcommand are refused with a message naming the flag; each subcommand takes its own.

--continue-branch BRANCH matches case-sensitively against current reserved branches and recorded local publications, never bases or names. Includes archives, not subtasks. No matches error without creating state. Multiple matches require a controlling terminal and show a numbered list with metadata and full cached /summary content and freshness, newest substantive activity first. Missing summaries are labelled; no summaries are generated to choose. Invalid numbers retry; Enter, EOF, or q cancels. There is no default, including with -y or --yes-really. Without a controlling terminal, use --continue FULL-UUID. Historical selection does not retarget the session's current branch. The flag excludes prompts, --continue, --fork, --adopt, and subcommands. See Resuming by publication branch.

--adopt UUID conflicts with a prompt, --continue, --continue-branch, --fork, and subcommands. It searches the effective data root, including archives, and adopts into the containing checkout root. Review its source/destination and saved-state details before answering y; empty input cancels. Without a controlling terminal, -y is required. This also retains the usual Level 2 tool auto-approval during the resumed session. See Adopting a session.

The session needs a terminal on stdout; without one it says to use heph exec.

heph exec: one turn

heph exec [FLAGS] [PROMPT]...

Runs one turn on the prompt and exits. The prompt is the arguments joined with spaces; if stdin is not a terminal, its contents are appended as context. With --continue REF the prompt may be omitted, in which case a review pending on the conversation is offered and nothing else happens.

exec takes the session flags above except interactive-only --adopt and --fork, and:

Stdout: the model's final text. Stderr: everything else. Exit codes are in Exit Codes and Errors.

heph skills

heph skills [--ref REF]
heph skills check [PATH]...
heph skills show NAME

The skills of the project at -C or the current directory, with no model configured and no database opened, except with --ref.

• heph skills prints the /skills report. --ref REF marks the skills active on that conversation.

• heph skills check parses and validates every discovered skill, or the SKILL.md files and directories given, prints each problem, and exits 1 if any skill is invalid. A frontmatter field the specification does not define is a warning and does not change the exit status.

• heph skills show NAME prints the skill's frontmatter, source, resources, and the activation payload exactly as the model would receive it.

heph sessions

Lists the current checkout's saved conversations, newest recorded work or publication first. Subdirectories select their containing checkout. Use --all-projects for the effective data root; it conflicts with -C. Archives are hidden unless --archived or --include-archived is selected. No tmux or provider is needed. Outside a recognized project, choose explicit scope. -C DIR also accepts a removed checkout's original root path. A missing path selects that former project directly, not a surviving parent checkout, without recreating project state. Relative paths are relative to the current directory. See Finding a saved session for the workflow.

Filters combine, and limits apply last. Subcommands take precedence over regex arguments; use --match show for that pattern or -- before dash-prefixed patterns. show ID [--diff] provides detailed inspection, including archives. IDs are full UUIDs or unique prefixes of at least six characters. A complete read-only diff may be unavailable when replay or recovery is needed; heph reports that limitation rather than mutating state. open ID jumps to a unique live pane or uses ordinary resume; ambiguity never creates a new session.

The compact table shows ID, name, reserved branch, work flags, runtime, and last substantive activity. Full records and paths are available through show and JSON. Global tables add PROJECT; requested disk accounting adds OWNED BYTES and RECLAIMABLE BYTES (EST.) when available. Empty inventories succeed. Project and probe failures are retained in JSON and cause a nonzero exit without hiding successful records.

--summary adds SUMMARY with the full cached body, - for a missing cache, and [stale] before a cache covering an older tip. It reads the same ref-local cache as /summary without refreshing it, probing Git/runtime, calling a model, or changing activity. With --summary --json, saved caches appear as summary objects with body, turn_id, and generated_at (UTC Unix seconds); missing caches omit the field. Without the flag, the listing and JSON shape stay unchanged.

A current branch can be reserved without a successful commit. Publication records track verified local /commit results from this version onward, not remote pushes. They survive branch changes and deletion. Earlier publications are unknown, not counted by --published. Older source directories are unknown until the project is opened again, or provided by -C for the listing.

Ordinary inventory batches metadata and labelled cached observations without Git/runtime probes. A missing observation is not-inspected; a cache is never current cleanup evidence. Work/runtime selectors and show probe fresh state. Current schemas open read-only without migration write admission; old schemas migrate once. Actual input/name edits count as substantive activity, unlike resume, searching, or summary reads.

find QUESTION [--limit N] [--max-cost USD] [--profile NAME] ranks all selected candidates from metadata and cached summaries. The default limit is five, positive; input is nonempty and at most 8,000 characters. Packets are bounded to 80,000 bytes, candidate fields are explicitly cut, and large inventories use batches plus compact finalist assessments. The default request cap is $0.50. JSON includes matches/explanations, freshness, coverage, cuts, requests, cost, and its detached accounting anchor. No tools or source/transcript input are used. Malformed/provider responses fail without lexical fallback. No candidates means no provider setup or request.

archive|clean|delete ID... or shared selectors preview exact sets. Require IDs or selectors, not both; global actions require --all-projects. --apply authorizes the resolved set; interactive deletion also confirms history loss with DELETE. Lifecycle JSON contains items and coverage diagnostics. Archive retains private state. Clean retains the session and required snapshots while removing only its reconstructible worktree. Delete removes the ref and exclusive canonical history, preserving shared nodes, request audits, and charges. No external branches, shared caches, or object stores are pruned. Clean/delete require proven merged or untouched empty work, with no blockers and no force option. Live, unknown, pending, drafted, or changed targets are skipped/refused. Any skipped/failed requested target or incomplete coverage exits nonzero. Retry interrupted actions by UUID with --apply; completed reference deletion does not lose its retry receipt. Pre-commit refusal restores quarantine; committed cleanup finishes without replaying the operation.

Existing databases are migrated on open, but no project or worktree is created, no process registered, and no startup recovery run. Missing source directories and worktrees do not hide their conversations. See Finding a saved session.

heph wire-check

Sends one streaming request through the configured provider with a tool and thinking, stores every block, reads it back, and confirms nothing changed. When the model calls the tool, as the prompt asks it to, heph answers the call itself and sends a second round, so the model's reasoning goes back to the API that produced it and a cache read shows. Prints the provider, model, blocks, rounds, token counts with the second round's cache read, cost, time to first token, and duration. --role ROLE picks the tier to test by role (default coding). The check's system prompt is padded past the smallest prefix a provider will cache, so the two rounds cost a cent or two.

--earlier-reasoning adds two paid requests after this replay check. Both send an identical new-turn prompt, first with the earlier Responses reasoning and then without it. The report shows both usage categories and the difference in total input, including cache reads and writes; uncached input alone cannot separate omission from a cache hit. It also shows the probe cost, included in the overall total. Choose a GPT reasoning tier that returns encrypted reasoning; absent reasoning, incomplete usage, or unfinished responses fail the comparison. This is a single paired observation, not a general billing guarantee. Normal session replay and stored history are unchanged.

heph models

Lists every provider heph can address and each model with its rates (USD per million tokens: input, output, cache write, cache read) and context window. --all includes providers whose protocol heph does not speak. These are the ids to use in tiers and with --tier and --model. Each provider's default large and small models are marked; they fill its built-in profile.

--provider ID restricts the list to one provider. For ollama, or a configured provider of that kind, the command contacts its native endpoint and lists exact installed names, digests, sizes, quantizations, capabilities, architectural ceilings, and runtime allocations. Unknown values are labeled unknown; models without known tool support remain visible but are ineligible for agent work. No weights are downloaded. See Providers.

heph tiers

Prints the tiers (name, roles, model, thinking) of the profile --profile names, or the default, with --tier and --model applied and marked (overridden). A new conversation given the same flags runs on these (Tiers and Profiles).

heph profiles

Lists every profile, each provider's built-in one and those in config, with its tiers and where it came from, the default first; or says why there is no default.

heph tmux

Reads the pane variables every session publishes under tmux. Opens no database and reads no config; safe to run from tmux's status line every few seconds.

See Working in tmux.