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()/driver()/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
    driver(name)         targets run by that driver, whole name, case-sensitive
                         (e.g. driver(auth.credential))
    addr(//pkg:name)     an explicit target address
    package(//pkg)       an explicit package
    package_prefix(//pkg) every package under //pkg
  Any argument may be bare or quoted, with the same meaning: label(ci) is
  label("ci"). A quoted argument takes escapes: \\ \" \n \r \t \u{..}
  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.

  label(), driver() and tree_output() are decided from what providers list
  where they can, without resolving each target they rule out. `query` then
  resolves each match and prints only targets that exist; `query --candidates`
  skips that, which is faster but may print a listed target that does not. Set
  HEPH_NO_LISTED_FACTS to 1 to resolve every candidate instead; `heph validate`
  checks the listings.

  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 plugin 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 plugin-exposed functions (heph.<plugin>.<fn>)

Prints every function registered by a plugin for use in BUILD files, in heph.<plugin>.<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()/driver()/tree_output() functions. Mutually exclusive with the positional TARGET arguments
`--candidates`		Print the candidates as providers list them, without resolving each one. Faster, but the output may include targets that do not exist

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
    driver(name)         targets run by that driver, whole name, case-sensitive
                         (e.g. driver(auth.credential))
    addr(//pkg:name)     an explicit target address
    package(//pkg)       an explicit package
    package_prefix(//pkg) every package under //pkg
  Any argument may be bare or quoted, with the same meaning: label(ci) is
  label("ci"). A quoted argument takes escapes: \\ \" \n \r \t \u{..}
  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.

  label(), driver() and tree_output() are decided from what providers list
  where they can, without resolving each target they rule out. `query` then
  resolves each match and prints only targets that exist; `query --candidates`
  skips that, which is faster but may print a listed target that does not. Set
  HEPH_NO_LISTED_FACTS to 1 to resolve every candidate instead; `heph validate`
  checks the listings.

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

A credential is a target (driver = "auth.credential") declaring what identity a build needs and how it may be obtained. This is the preflight over them: which apply in this environment, from which source, and until when.

A build never signs anyone in — it fails with the exact command to run, and heph auth login is where a human runs it.

Examples:

heph auth status — one row per declared credential

heph auth explain //auth:aws — why a chain picked what it picked

heph auth login — run whichever sign-ins have gone stale

heph auth <COMMAND>

`heph auth status`

One row per declared credential: is it available here, from where, and until when

The preflight. Exits non-zero unless every row is ok, so a caller can branch without parsing and then parse to learn what to run.

Probes each chain; it does not acquire anything, so it runs no vendor CLI and signs nobody in.

Examples:

heph auth status

heph auth status //auth/... --json

heph auth status [OPTIONS] [PACKAGE_MATCHER]

Flag	Value	Default	Description
`<MATCHER>`	`PACKAGE_MATCHER`		Package matcher limiting which credentials are listed. Defaults to the whole workspace
`--json`			Machine-readable output: `addr`, `state`, `source`, `expires_at`, `login`

`heph auth explain`

The whole chain walk: every source, why each was skipped, which won

What to run when status says something is unavailable and the reason is not obvious. Prints the same structure the "no source applies" build failure does, so the diagnostic and the failure can never drift apart.

Example: heph auth explain //auth:aws

heph auth explain [OPTIONS] <TARGET_ADDRESS>

Flag	Value	Default	Description
`<ADDR>`	`TARGET_ADDRESS`		The credential to explain
`--json`

`heph auth login`

Run the sign-in commands of every source that is stale

Stale is a source the probe skipped, or the chosen source when acquiring from it fails — the probe only checks that its tool is there, so an expired session behind an installed tool shows up here. --force signs in to the chosen source regardless.

Never requires a terminal: it runs the vendor's own command with this process's stdio attached, so a browser flow works interactively and an agent sees the URL and code on its own output.

Examples:

heph auth login — everything that has gone stale

heph auth login //auth:aws — one credential

heph auth login //auth:aws --force — sign in again anyway

heph auth login [OPTIONS] [TARGET_ADDRESS]

Flag	Value	Default	Description
`<ADDR>`	`TARGET_ADDRESS`		Credential to sign in to. Defaults to every one that has gone stale
`-f`, `--force`			Sign in again even where the current session still works, and forget what heph has cached for the credential — to switch accounts, or when a session is broken in a way heph cannot see

`heph auth logout`

Forget every acquired credential, in this process and on disk

Clears <home>/auth. The vendor CLIs' own sessions are untouched — heph does not own those, and signing you out of aws because you asked heph to forget a cache entry would be a surprise.

heph auth logout

`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 under the heph home (.heph by default, homeDir in config) 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()/driver()/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
    driver(name)         targets run by that driver, whole name, case-sensitive
                         (e.g. driver(auth.credential))
    addr(//pkg:name)     an explicit target address
    package(//pkg)       an explicit package
    package_prefix(//pkg) every package under //pkg
  Any argument may be bare or quoted, with the same meaning: label(ci) is
  label("ci"). A quoted argument takes escapes: \\ \" \n \r \t \u{..}
  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.

  label(), driver() and tree_output() are decided from what providers list
  where they can, without resolving each target they rule out. `query` then
  resolves each match and prints only targets that exist; `query --candidates`
  skips that, which is faster but may print a listed target that does not. Set
  HEPH_NO_LISTED_FACTS to 1 to resolve every candidate instead; `heph validate`
  checks the listings.

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

Inspect the POSIX utilities compiled into this binary

The binary carries its own cp, install, sha256sum and friends so a recipe behaves the same on Linux and macOS, and puts them on every target's PATH. These subcommands say what is in the set and what a name resolves to.

Example: heph tool coreutils list

heph tool coreutils <COMMAND>

`heph tool coreutils list`

List the utilities compiled into this binary

Prints every applet, the toolbox version that reaches a target's cache key, and where the implementations come from.

Example: heph tool coreutils list

heph tool coreutils list [OPTIONS]

Flag	Value	Default	Description
`--json`			Emit JSON instead of a table

`heph tool coreutils which`

Explain what a name resolves to

Says whether heph ships this utility and what the host would supply instead — the two candidates a target's PATH chooses between.

Example: heph tool coreutils which cp

heph tool coreutils which <NAME>

Flag	Value	Default	Description
`<NAME>`	`NAME`		Utility name, e.g. `cp`

`heph tool coreutils run`

Run one builtin utility directly

The same code a target gets, without a sandbox — for checking what a flag does. Its exit code becomes heph's.

Example: heph tool coreutils run cp -r src dst

heph tool coreutils run <NAME> [ARGS]...

Flag	Value	Default	Description
`<NAME>`	`NAME`		Utility name, e.g. `cp`
`<ARGS>`	`ARGS`		Arguments passed to it verbatim

`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 tool plugins`

List the loaded plugins and their components, by full name

Prints every registered plugin (builtins and the plugins: entries) with where it came from, then each provider, driver, function and exec runner it contributes, under the name a BUILD file uses: a driver as driver = "<plugin>.<local>", a function as heph.<plugin>.<fn>.

Example: heph tool plugins --json

heph tool plugins [OPTIONS]

Flag	Value	Default	Description
`--json`			Emit JSON instead of the text listing

`heph tool telemetry`

Inspect anonymous usage telemetry

What heph reports, and how to turn it off, is in docs/TELEMETRY.md.

Example: heph tool telemetry status

heph tool telemetry <COMMAND>

`heph tool telemetry status`

Show whether telemetry is on, why, and what is waiting to be sent

Reports whether this machine and workspace send anonymous usage telemetry, which switch turned it off (HEPH_DISABLE_TELEMETRY, or telemetry.enabled: false in the config), where the spool of unsent events lives, how many are pending and how old the oldest is, how the last flush went, and when the next one is due. The report itself sends nothing; after it is printed, this command is handled like any other — recorded when telemetry is on, and when it is off, a spool left from before the opt-out is sent once and deleted. --json emits the same as a stable object (see docs/TELEMETRY.md for its keys).

Example: heph tool telemetry status --json

heph tool telemetry status [OPTIONS]

Flag	Value	Default	Description
`--json`			Emit JSON instead of the text report

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 auth​

heph auth status​

heph auth explain​

heph auth login​

heph auth logout​

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 coreutils​

heph tool coreutils list​

heph tool coreutils which​

heph tool coreutils run​

heph tool completions​

heph tool build-fmt​

heph tool resolve-plugins​

heph tool plugins​

heph tool telemetry​

heph tool telemetry status​

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

`heph auth status`

`heph auth explain`

`heph auth login`

`heph auth logout`

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

`heph tool coreutils list`

`heph tool coreutils which`

`heph tool coreutils run`

`heph tool completions`

`heph tool build-fmt`

`heph tool resolve-plugins`

`heph tool plugins`

`heph tool telemetry`

`heph tool telemetry status`