Skip to main content

Inspecting builds

When a build does something surprising — a target rebuilds when you expected a cache hit, or a dependency isn't where you think — the heph inspect subcommands show you the engine's view. See the CLI reference for full flag detail.

"Why did this rebuild?"​

A target rebuilds when its input hash changes. Compare the hash across runs to find what moved:

terminal
heph inspect hashin //app:server

The input hash (hashin) folds in every declared input. If it changed, an input changed. Pair it with the output hash to confirm what the target produced:

terminal
heph inspect hashout //app:server

"What does this depend on?"​

Print a target's dependency edges, or explore them interactively:

terminal
heph inspect deps //app:server
heph inspect deps //app:server -i      # interactive explorer

"What did the provider produce?"​

A provider turns BUILD files (or generated sources) into target specs, which a driver then resolves into a definition. Inspect each stage:

terminal
heph inspect spec //app:server     # the raw spec the provider emitted
heph inspect def //app:server      # the resolved definition (inputs, outputs, sandbox)

spec is what the provider produced before any driver interpreted it; def is the fully resolved form the engine executes.

Listing what exists​

terminal
heph inspect packages              # all packages
heph inspect packages cmd/...      # packages under a matcher
heph inspect functions             # provider-exposed BUILD functions

functions lists every provider function available in BUILD files, with its typed signature — for example fs.glob(pattern: string) -> list[string]. Useful when a provider adds its own callable beyond the core builtins, or to check argument names and types before writing a call.

Reproducing the environment​

To go past inspection and actually poke at a failing target, open its sandbox:

terminal
heph run //app:server --shell