CLI reference

`heph run`

Build and run targets

Resolves the matched target(s), builds their dependency graph, and runs them — reusing cached results when inputs are unchanged. A single argument is a target address; two arguments are a label followed by a package matcher, selecting every target carrying that label. For richer selection use -e '<expr>' with the query language (see --help).

Examples:

heph run //cmd/server:bin — run a single target

heph run test //... — run every target labelled test

heph run //cmd/server:bin --shell — open a shell in the target sandbox

heph run -e '//cmd/... && label(test)' — run via a query expression

heph run -e '//... && !//vendor/...' — run, excluding a subtree

heph run <TARGET_ADDRESS>
heph run <LABEL> <PACKAGE_MATCHER>
heph run -e <EXPR>

Flag	Value	Default	Description
`<ARG1>`	`TARGET_ADDRESS/LABEL`		Target address (e.g., //pkg:name) OR Label
`<ARG2>`	`PACKAGE_MATCHER`		Package matcher (only if first argument is a Label)
`-e`, `--expr`	`EXPR`		Select targets with a query expression, e.g. -e '//pkg/... && !//vendor/...'. Supports &&, \|\|, !, parentheses, and the label()/tree_output() functions. Mutually exclusive with the positional TARGET arguments
`--force`			Force execution, ignoring any cached result
`--shell`	`TARGET`		Drop into an interactive shell in the target's sandbox instead of running it
`--cat-out`			Print output artifacts to stdout
`--list-out`			Print output file list to stdout
`--copy-out`	`DIR`		Copy output artifacts into DIR (created if needed). Relative paths resolve against the current directory
`--output`	`NAME`		Restrict --cat-out/--list-out/--copy-out to these output names (repeatable). When omitted, all of the target's outputs are considered
`--frozen`			Fail if generated output differs from the tree (CI check)
`--log-lines`	`N`	`10`	Number of trailing process-log lines to show in a failing target's diagnostic box. The full log is always saved as the `log.txt` artifact

Selecting targets:
  heph run //pkg:name                 a single target address
  heph run <label> //pkg/...          all targets with <label> under //pkg
  heph run -e '<expr>'                a query expression (see below)

  A label is [A-Za-z0-9_-]+ — the positional form takes one bare label, never
  an expression. For &&, ||, ! or grouping, use -e.

Query language (-e / --expr):
  Patterns:
    //pkg                package //pkg
    //pkg/...            every package under //pkg
    //pkg:name           one target address
    ./sub, ../x, .       relative to the current package
  Functions:
    label(x)             targets carrying label x   (e.g. label(go-lint))
    tree_output(pkg)     targets whose codegen tree writes into pkg
    addr(//pkg:name)     an explicit target address
    package(//pkg)       an explicit package
    package_prefix(//pkg) every package under //pkg
  Operators (precedence ! > && > ||, group with parentheses):
    a && b               both          a || b   either          !a   negate
  Evaluation follows grouping then left-to-right, bailing as early as possible.

  Examples:
    heph run -e '//some/... && label(foo)'
    heph run -e '//app/... && !label(slow)'
    heph run -e '//... && !//vendor/...'
    heph run -e '(//a/... || //b/...) && tree_output(gen)'

`heph inspect`

Inspect targets, packages, hashes, and deps

Read-only introspection of the build graph. Subcommands print a target's spec, resolved def, input/output hashes, or dependencies, and list packages or provider functions. Nothing is executed unless a provider must run a target to answer the query.

Examples:

heph inspect packages //...

heph inspect deps //cmd/server:bin

heph inspect hashin //cmd/server:bin

heph inspect [COMMAND]

`heph inspect packages`

List packages matching a matcher

Walks providers to discover packages and prints those matching the given matcher, one per line. With no argument, lists every package in the workspace.

Examples:

heph inspect packages

heph inspect packages //cmd/...

heph inspect packages [MATCHER]

Flag	Value	Default	Description
`<MATCHER>`	`MATCHER`		Package matcher (defaults to all packages)

`heph inspect labels`

List the unique labels declared across matching targets

Enumerates every target in the packages matching the given matcher, collects the labels each declares, and prints the sorted, deduplicated set one per line. With no argument, scans the whole workspace.

Examples:

heph inspect labels

heph inspect labels //cmd/...

heph inspect labels [MATCHER]

Flag	Value	Default	Description
`<MATCHER>`	`MATCHER`		Package matcher (defaults to all packages)

`heph inspect hashin`

Print a target's input hash

Computes and prints the content hash of all the target's declared inputs — the key heph uses to decide a cache hit. Does not run the target.

Example: heph inspect hashin //cmd/server:bin

heph inspect hashin <ADDR>

Flag	Value	Default	Description
`<ADDR>`	`ADDR`		Target address (e.g. //pkg:name)

`heph inspect hashout`

Print a target's output hashes

Runs the target (or reads its cached result) and prints the content hash of each output artifact, one per line.

Example: heph inspect hashout //cmd/server:bin

heph inspect hashout <ADDR>

Flag	Value	Default	Description
`<ADDR>`	`ADDR`		Target address (e.g. //pkg:name)

`heph inspect outputs`

Print the paths a target actually produces

Runs the target (or reads its cached result) and prints every path in its output artifacts, one per line — the paths as a consumer sees them in its sandbox, after any filtering or relocation.

This is the answer to "why did that file land there?" for a group target using include/exclude/strip_prefix/prefix/rename: compare the group's paths with its deps' to see exactly what the transform did.

Examples:

heph inspect outputs //cmd/server:bin

heph inspect outputs //cmd:dist --json — also lists support files

heph inspect outputs [OPTIONS] <ADDR>

Flag	Value	Default	Description
`<ADDR>`	`ADDR`		Target address (e.g. //pkg:name)
`--json`			Emit JSON instead of one path per line

`heph inspect spec`

Print a target's spec, as supplied by its provider

Prints the raw spec — the unresolved definition a provider returns before a driver parses it — as pretty JSON.

Example: heph inspect spec //cmd/server:bin

heph inspect spec <ADDR>

Flag	Value	Default	Description
`<ADDR>`	`ADDR`		Target address (e.g. //pkg:name)

`heph inspect def`

Print a target's resolved def (inputs, outputs, sandbox)

Parses the target's spec into a def and prints it as pretty JSON, including declared inputs, outputs, and sandbox configuration. By default transitive deps are applied; pass --no-transitive for the direct def only.

Examples:

heph inspect def //cmd/server:bin

heph inspect def //cmd/server:bin --no-transitive

heph inspect def [OPTIONS] <ADDR>

Flag	Value	Default	Description
`<ADDR>`	`ADDR`		Target address (e.g. //pkg:name)
`--no-transitive`			Show the direct def only, without applying transitive deps

`heph inspect deps`

Print a target's input dependencies

Resolves the target's def and prints the ref of each declared input, one per line. Pass -i/--interactive to browse the dependency tree in a TUI.

Examples:

heph inspect deps //cmd/server:bin

heph inspect deps //cmd/server:bin -i

heph inspect deps [OPTIONS] <ADDR>

Flag	Value	Default	Description
`<ADDR>`	`ADDR`		Target address (e.g. //pkg:name)
`-i`, `--interactive`			Explore the dependency tree in an interactive TUI (requires a terminal)

`heph inspect revdeps`

Print the targets that depend on a target ("where is this used?")

The reverse of deps: scans the workspace (or --scope packages) and prints every target that declares the given target as a direct input, one per line.

Examples:

heph inspect revdeps //lib:core

heph inspect revdeps //lib:core --scope //cmd/...

heph inspect revdeps [OPTIONS] <ADDR>

Flag	Value	Default	Description
`<ADDR>`	`ADDR`		Target whose users to find: a `//pkg:name` or relative (`:name`, `./pkg:name`) address, or a path to an existing file (sugar for its `fs` file target)
`--scope`	`PACKAGE_MATCHER`		Restrict the search to packages matching this matcher (e.g. //pkg/...); defaults to the whole workspace

`heph inspect path`

Print the chain of targets linking two targets

Prints the shortest chain of hops linking A and B, one target per line. Argument order does not matter: both directions are searched, and the chain is printed from the dependent to the dependency. Hops follow each target's resolved deps, so a dep pulled in by another dep's transitives counts; pass --no-transitive to follow only the directly declared ones. When the two are unconnected, nothing is printed on stdout — the reason is logged instead.

Examples:

heph inspect path //cmd/server:bin //lib:core

heph inspect path //lib:core //cmd/server:bin — same chain

heph inspect path //cmd/server:bin main.go

heph inspect path //cmd/server:bin //lib:core --no-transitive

heph inspect path [OPTIONS] <A> <B>

Flag	Value	Description
`<A>`	`A`	One end of the chain (e.g. //cmd/server:bin)
`<B>`	`B`	The other end of the chain (e.g. //lib:core) — order does not matter
`--no-transitive`		Follow only directly declared deps, without applying transitive deps

`heph inspect states`

Show the provider_state(...) declared across the package tree

A provider_state(provider="X", …) call in a BUILD file configures provider X for that package and — depending on the provider — its descendants. This prints where those declarations live and what they carry: a //pkg header per package, then one line per state as <provider> <field>=<json> …. Packages declaring nothing are omitted, so empty output means "no state here".

Pass --inherited to see the whole chain a provider is handed for a package — its own declarations plus every ancestor's — each line prefixed with the package that declared it, root first. Which of two declarations wins is the provider's own policy; this only reports what applies.

Examples:

heph inspect states — every declaration in the workspace

heph inspect states //cmd/...

heph inspect states //cmd/server --inherited — what applies there

heph inspect states -p go --json

heph inspect states [OPTIONS] [MATCHER]

Flag	Value	Description
`<MATCHER>`	`MATCHER`	Package matcher (defaults to all packages)
`--inherited`		Also show the states a package inherits from its ancestors
`-p`, `--provider`	`PROVIDER`	Only show states addressed to this provider
`--json`		Emit JSON instead of the text listing

`heph inspect functions`

List provider-exposed functions (heph.<provider>.<fn>)

Prints every function registered by a provider for use in BUILD files, in heph.<provider>.<function> form, one per line.

Example: heph inspect functions

heph inspect functions

`heph query`

Query targets

Prints the address of every target matched by the argument(s), one per line. Accepts the same address / label+matcher forms as run, plus -e '<expr>' for the query language (see --help). Useful for scripting and for previewing what a selection matches before running it.

Examples:

heph query //cmd/server:bin — resolve a single address

heph query test //cmd/... — every target labelled test

heph query -e '//...' — every target in the workspace

heph query -e '//... && !//vendor/...' — select with exclusion

heph query -e '//cmd/... && !label(slow)' — select via a query

heph query <TARGET_ADDRESS>
heph query <LABEL> <PACKAGE_MATCHER>
heph query -e <EXPR>

Flag	Value	Description
`<ARG1>`	`TARGET_ADDRESS/LABEL`	Target address (e.g., //pkg:name) OR Label
`<ARG2>`	`PACKAGE_MATCHER`	Package matcher (only if first argument is a Label)
`-e`, `--expr`	`EXPR`	Select targets with a query expression, e.g. -e '//pkg/... && !//vendor/...'. Supports &&, \|\|, !, parentheses, and the label()/tree_output() functions. Mutually exclusive with the positional TARGET arguments

Selecting targets:
  heph run //pkg:name                 a single target address
  heph run <label> //pkg/...          all targets with <label> under //pkg
  heph run -e '<expr>'                a query expression (see below)

  A label is [A-Za-z0-9_-]+ — the positional form takes one bare label, never
  an expression. For &&, ||, ! or grouping, use -e.

Query language (-e / --expr):
  Patterns:
    //pkg                package //pkg
    //pkg/...            every package under //pkg
    //pkg:name           one target address
    ./sub, ../x, .       relative to the current package
  Functions:
    label(x)             targets carrying label x   (e.g. label(go-lint))
    tree_output(pkg)     targets whose codegen tree writes into pkg
    addr(//pkg:name)     an explicit target address
    package(//pkg)       an explicit package
    package_prefix(//pkg) every package under //pkg
  Operators (precedence ! > && > ||, group with parentheses):
    a && b               both          a || b   either          !a   negate
  Evaluation follows grouping then left-to-right, bailing as early as possible.

  Examples:
    heph run -e '//some/... && label(foo)'
    heph run -e '//app/... && !label(slow)'
    heph run -e '//... && !//vendor/...'
    heph run -e '(//a/... || //b/...) && tree_output(gen)'

`heph validate`

Validate all targets (link graph + check codegen outputs)

heph validate
heph validate <PACKAGE_MATCHER>

Flag	Value	Default	Description
`<MATCHER>`	`PACKAGE_MATCHER`		Package matcher (e.g. //pkg/...); omit to validate the whole workspace

`heph version`

Prints version

Prints the heph version string and exits.

heph version

`heph tool`

Developer tools

Maintenance and housekeeping subcommands that operate on the workspace or the local cache rather than on individual targets.

heph tool [COMMAND]

`heph tool gc`

Garbage collect the local cache

Sweeps the local cache (.heph3/cache) and removes artifacts no longer reachable from any current target, reclaiming disk space. Resolves every cached target's spec, so providers may run.

Example: heph tool gc

heph tool gc [OPTIONS]

Flag	Value	Default	Description
`--scratch-max-size`	`SIZE`		Cap the total size of persistent scratch caches, e.g. `50GiB`. Least recently used caches are dropped whole until the store fits
`--scratch-max-age-days`	`DAYS`		Drop scratch caches untouched for longer than this many days

`heph tool clean`

Remove the selected targets' entries from the local cache

Deletes every locally cached revision of the selected target(s) — all of them, whatever their cache.history budget and whether or not the target still exists. gc is the sweep that reclaims space without being told what; this is the one you point at something.

Targets are selected exactly as for run: an address, a label followed by a package matcher, or -e '<expr>' (see --help). The selection is required — there is no whole-cache default, since this command deletes. A selection that needs no resolution — an address, or all <package matcher> — is answered from the cache alone: no BUILD files are read, so an entry whose target has since been deleted is still cleanable. label(...) resolves the graph.

Examples:

heph tool clean //cmd/server:bin — one target (that exact variant)

heph tool clean all //cmd/... — every cached target under a subtree

heph tool clean test //cmd/... — every target labelled test

heph tool clean all //... — clear the entire local cache

heph tool clean <TARGET_ADDRESS>
heph tool clean <LABEL> <PACKAGE_MATCHER>
heph tool clean -e <EXPR>

Flag	Value	Description
`<ARG1>`	`TARGET_ADDRESS/LABEL`	Target address (e.g., //pkg:name) OR Label
`<ARG2>`	`PACKAGE_MATCHER`	Package matcher (only if first argument is a Label)
`-e`, `--expr`	`EXPR`	Select targets with a query expression, e.g. -e '//pkg/... && !//vendor/...'. Supports &&, \|\|, !, parentheses, and the label()/tree_output() functions. Mutually exclusive with the positional TARGET arguments
`--scratch`		Also delete persistent scratch caches. With an ADDRESS, only that declaration's cache; alone, every one in the workspace

Selecting targets:
  heph run //pkg:name                 a single target address
  heph run <label> //pkg/...          all targets with <label> under //pkg
  heph run -e '<expr>'                a query expression (see below)

  A label is [A-Za-z0-9_-]+ — the positional form takes one bare label, never
  an expression. For &&, ||, ! or grouping, use -e.

Query language (-e / --expr):
  Patterns:
    //pkg                package //pkg
    //pkg/...            every package under //pkg
    //pkg:name           one target address
    ./sub, ../x, .       relative to the current package
  Functions:
    label(x)             targets carrying label x   (e.g. label(go-lint))
    tree_output(pkg)     targets whose codegen tree writes into pkg
    addr(//pkg:name)     an explicit target address
    package(//pkg)       an explicit package
    package_prefix(//pkg) every package under //pkg
  Operators (precedence ! > && > ||, group with parentheses):
    a && b               both          a || b   either          !a   negate
  Evaluation follows grouping then left-to-right, bailing as early as possible.

  Examples:
    heph run -e '//some/... && label(foo)'
    heph run -e '//app/... && !label(slow)'
    heph run -e '//... && !//vendor/...'
    heph run -e '(//a/... || //b/...) && tree_output(gen)'

`heph tool gen-gitignore`

Manage the heph-generated section of the root .gitignore

Computes the ignore patterns for codegen-copy outputs and writes them into a managed block in the workspace root .gitignore, leaving the rest of the file untouched. Idempotent: a no-op when already up to date.

Example: heph tool gen-gitignore

heph tool gen-gitignore
heph tool gen-gitignore <PACKAGE_MATCHER>

Flag	Value	Default	Description
`<MATCHER>`	`PACKAGE_MATCHER`		Package matcher (e.g. //pkg/...); omit to regenerate the whole section. When given, only the lines emitted by targets under that matcher are rebuilt — a smaller graph walk, so a faster run

`heph tool scratch`

Inspect and reclaim persistent scratch caches

A scratch cache is a directory a target declares and carries between runs to go faster — a compiler cache, a dependency cache. Nothing else bounds their growth, so this is where you look when disk is short, and heph tool gc is what sweeps them on a schedule.

Removing one is always safe: a target's outputs are identical whether its scratch is warm, cold or absent, so it costs time and nothing else.

Example: heph tool scratch ls

heph tool scratch <COMMAND>

`heph tool scratch ls`

List persistent scratch cache directories

One row per declared cache, largest first, with the lineages (branches) present and the total size on disk. Reads no BUILD files, so a cache whose declaring target is gone still shows up — and can still be removed.

Example: heph tool scratch ls

heph tool scratch ls

`heph tool scratch head`

Explain which lineage a cache would be restored from

Prints the resolution walk: every candidate lineage in the order it is consulted, what each holds, and which one wins. This is the answer to "why did my branch build start cold?" — a question the local directory alone cannot answer, because the interesting part is what was not found.

Example: heph tool scratch head //build:gocache

heph tool scratch head <ADDR>

Flag	Value	Default	Description
`<ADDR>`	`ADDR`		Address of the `scratch` target

`heph tool scratch path`

Print the on-disk path of a scratch cache

For pointing another tool at it, or du-ing it by hand.

Example: heph tool scratch path //build:gocache

heph tool scratch path <ADDR>

Flag	Value	Default	Description
`<ADDR>`	`ADDR`		Address of the `scratch` target, e.g. `//build:gocache`

`heph tool scratch push`

Publish scratch caches to the remote

The command CI runs as its last step. Publishing is never a side effect of building: it is expensive, it mutates shared state, and whether a given job's cache state deserves to become the branch's published head is a CI-policy question — one answered far better by an if: condition in a workflow than by a heuristic inside heph.

Writes into the current branch's lineage and never into a fallback, even the one the cache was seeded from. That isolation is what makes this safe to enable on untrusted PR CI at all.

Example: heph tool scratch push --all --producer "$GITHUB_RUN_ID"

heph tool scratch push [OPTIONS] [ADDR]

Flag	Value	Default	Description
`<ADDR>`	`ADDR`		Address of the `scratch` target to publish
`--all`			Publish every cache declared `remote = True`
`--force`			Publish even when the contents are identical to what is already there
`--producer`	`PRODUCER`	``	Free-form producer id recorded with the snapshot, e.g. a CI run id

`heph tool scratch pull`

Fetch scratch caches from the remote without building

Builds do this on their own when a cache is cold, so this is for warming a machine ahead of time, or recovering after a local cache went bad.

Example: heph tool scratch pull --all

heph tool scratch pull [OPTIONS] [ADDR]

Flag	Value	Default	Description
`<ADDR>`	`ADDR`		Address of the `scratch` target to fetch
`--all`			Fetch every cache declared `remote = True`

`heph tool scratch rm`

Delete scratch cache directories

The remedy when a cache has gone bad: the next build starts cold and repopulates it. Deleting a scratch is always safe — a target's outputs are identical whether its scratch is warm, cold or absent, so this costs time and nothing else.

Examples:

heph tool scratch rm //build:gocache — one cache

heph tool scratch rm --all — every cache

heph tool scratch rm [OPTIONS] [ADDR]

Flag	Value	Default	Description
`<ADDR>`	`ADDR`		Address of the `scratch` target to delete
`--all`			Delete every scratch cache in this workspace

`heph tool cache`

Remote cache maintenance

Subcommands for the shared remote cache(s) configured in .hephconfig2.

Example: heph tool cache measure-latency

heph tool cache <COMMAND>

`heph tool cache measure-latency`

Measure and persist remote cache latency ordering

Probes each configured remote cache once and prints its round-trip latency, fastest first. The order is persisted (keyed by the cache definitions) so subsequent builds read caches fastest-first without re-probing; this command forces a fresh measurement.

Example: heph tool cache measure-latency

heph tool cache measure-latency

`heph tool completions`

Print a shell completion-registration script

Emits the script that enables dynamic tab-completion of subcommands, flags, and target addresses for the given shell. Source it from your shell rc, e.g. source <(heph tool completions zsh).

Example: heph tool completions bash

heph tool completions <SHELL>

Flag	Value	Default	Description
`<SHELL>`	`SHELL`		Shell to emit the completion-registration script for

`heph tool build-fmt`

Format BUILD files

Reformats the Starlark BUILD files of every package, or only those matching a package matcher. Rewrites in place by default; --check reports unformatted files and exits non-zero without writing. Pass - to format stdin to stdout.

Example: heph tool build-fmt //pkg/...

heph tool build-fmt
heph tool build-fmt <PACKAGE_MATCHER>
heph tool build-fmt -

Flag	Value	Default	Description
`<MATCHER>`	`PACKAGE_MATCHER`		Package matcher (e.g. //pkg/...); omit to format every package's BUILD file. Pass `-` to read source from stdin and write the formatted result to stdout
`--check`			Check mode: exit non-zero if any file is not formatted; do not write

`heph tool resolve-plugins`

Download + verify every configured plugin is loadable

Resolves each plugins: entry: built-ins are instantiated and each path:/url: plugin's cdylib is fetched (to ~/.heph/plugins) and load-checked over the stable ABI. Fails if any plugin can't be loaded.

Example: heph tool resolve-plugins --force

heph tool resolve-plugins [OPTIONS]

Flag	Value	Default	Description
`--force`			Re-download every plugin even if already cached (clears `~/.heph/plugins/<os>-<arch>/` first)

heph run​

heph inspect​

heph inspect packages​

heph inspect labels​

heph inspect hashin​

heph inspect hashout​

heph inspect outputs​

heph inspect spec​

heph inspect def​

heph inspect deps​

heph inspect revdeps​

heph inspect path​

heph inspect states​

heph inspect functions​

heph query​

heph validate​

heph version​

heph tool​

heph tool gc​

heph tool clean​

heph tool gen-gitignore​

heph tool scratch​

heph tool scratch ls​

heph tool scratch head​

heph tool scratch path​

heph tool scratch push​

heph tool scratch pull​

heph tool scratch rm​

heph tool cache​

heph tool cache measure-latency​

heph tool completions​

heph tool build-fmt​

heph tool resolve-plugins​

`heph run`

`heph inspect`

`heph inspect packages`

`heph inspect labels`

`heph inspect hashin`

`heph inspect hashout`

`heph inspect outputs`

`heph inspect spec`

`heph inspect def`

`heph inspect deps`

`heph inspect revdeps`

`heph inspect path`

`heph inspect states`

`heph inspect functions`

`heph query`

`heph validate`

`heph version`

`heph tool`

`heph tool gc`

`heph tool clean`

`heph tool gen-gitignore`

`heph tool scratch`

`heph tool scratch ls`

`heph tool scratch head`

`heph tool scratch path`

`heph tool scratch push`

`heph tool scratch pull`

`heph tool scratch rm`

`heph tool cache`

`heph tool cache measure-latency`

`heph tool completions`

`heph tool build-fmt`

`heph tool resolve-plugins`