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
`--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)

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("//tag:release"))
    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 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 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 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 //...

heph query test //cmd/...

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)

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("//tag:release"))
    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

`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 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 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 hashin​

heph inspect hashout​

heph inspect spec​

heph inspect def​

heph inspect deps​

heph inspect functions​

heph query​

heph validate​

heph version​

heph tool​

heph tool gc​

heph tool gen-gitignore​

heph tool cache​

heph tool cache measure-latency​

heph tool completions​

heph tool resolve-plugins​

`heph run`

`heph inspect`

`heph inspect packages`

`heph inspect hashin`

`heph inspect hashout`

`heph inspect spec`

`heph inspect def`

`heph inspect deps`

`heph inspect functions`

`heph query`

`heph validate`

`heph version`

`heph tool`

`heph tool gc`

`heph tool gen-gitignore`

`heph tool cache`

`heph tool cache measure-latency`

`heph tool completions`

`heph tool resolve-plugins`