CLI reference

Every command, option, environment variable and exit code. stoop --help prints the short form.

A leather falconry hood, glove, jesses and a brass bell on a wooden perch.

Commands

CommandWhat it does
stoop run [options] -- <command> [args...]Skip the command if a proof matches; otherwise run it traced and record a proof if it passes. The default, so stoop -- make test works too.
stoop explain [options] -- <command> [args...]Say what would happen and why, without running anything. Prints what differed in each proof it checked.
stoop sh <script> [args...]Shell mode for CI. Runs the script with bash --noprofile --norc -eo pipefail, keyed by the script's contents and arguments, GITHUB_WORKFLOW, GITHUB_JOB and the working directory. Made for shell: stoop sh {0}.
stoop ls [--store DIR]List keys, working directories, recorded platforms, proof count, inputs in the newest proof, and when it was created (Unix seconds). Older proofs without platform information are shown as unknown.
stoop forget <key> [--store DIR]Drop every proof for a key.
stoop pull [--sync git[:remote]]Fetch every published proof from the remote once. Use it at the start of a job.
stoop prune [--sync git[:remote]] [--max-age DUR]Delete published proofs older than --max-age (default 7d). Needs write access.
stoop --help, stoop --versionHelp text and version.

Options

Options go before --. Everything after it is the command.

--key NAME
Name the proof yourself. The default is the program name plus a hash of the arguments and the working directory, like cargo-46fcb2881638d3cc. A named proof must still match the working directory and repository identity.
--root DIR
The repository root. Defaults to the nearest directory containing a .git directory or file; a nested repository uses the inner root. Without .git, the working directory is the root. Paths inside the root are stored relative to it, and only reads inside it can be recorded as absent.
--store DIR
Where proofs live. Defaults to <root>/.stoop, or $STOOP_STORE. An external store scopes automatic keys by Git origin, or by the physical root path if there is no origin. See keys.
--env NAME
Count this variable too. The environment already counts, minus runner bookkeeping (GITHUB_, RUNNER_, ACTIONS_, INPUT_, STOOP_); use this to put one of those back. Repeatable.
--ignore-env NAME
Exempt a variable that changes without mattering, such as a per-run token. Repeatable.
--probe CMD
External state to verify. CMD runs with sh -c before the command; its output is hashed into the proof and must match again for a skip. A probe that fails, or prints something different after the command finishes, means nothing is recorded. Declaring a probe accepts network use for that step. Repeatable.
--allow-network
Record runs that used the network anyway. You are vouching that the network can't change the result.
--max-age DUR
A proof stops counting after DUR: 90s, 30m, 12h, 7d, or a bare number of seconds. Default 7d; 0 means never expire.
--ignore PATTERN
Paths whose reads don't count. Same syntax as .stoopignore. Repeatable.
--no-record
Check and skip as usual, but never write a proof. For jobs you don't trust.
--sync git[:REMOTE]
On a miss, fetch this key's proofs from refs/stoop/<key> on the git remote (default origin) and check again. See git sync.
--sync-write
Publish proofs to that remote after a recorded run. Off by default; use it on the default branch only.
--quiet
Print nothing about the decision. The command's own output is untouched.

Environment

VariableEffect
STOOP_FULL=1Never skip; still record. For the nightly full run.
STOOP_OFF=1Don't trace or skip; run commands directly.
STOOP_STORE=DIRDefault for --store.
STOOP_SYNC=git[:REMOTE]Default for --sync.
STOOP_SYNC_WRITE=1Same as --sync-write.
STOOP_ENV_SALTA secret that keys the environment hashes stored in proofs. Set it from a repository secret wherever proofs are published. See How git sync works.

These are switches. A variable that is empty, or set to 0, false, no or off, is off; anything else is on. That makes the common CI idiom STOOP_SYNC_WRITE: ${{ github.ref == 'refs/heads/main' && '1' || '' }} safe: the empty string on a pull request does not turn publishing on. An empty STOOP_SYNC or STOOP_STORE counts as unset.

Exit codes

CommandExit code
run, sh0 on a skip; otherwise the command's own code (128 + signal if it was killed). 127 if it couldn't be started.
explain0 if the command would be skipped, 1 if it would run.
forget0 if proofs were dropped, 1 if there were none for the key.
prune0 on success, 1 if the remote refused.
Any2 for a usage error, such as an unknown option.

What the messages mean

stoop: skip KEY: N inputs unchanged since T ago (Xms)
A proof matched. The command did not run.
stoop: run KEY: REASON
No proof matched. REASON is what differed from the newest one: no proof yet, src/main.rs changed, env changed, proof expired, STOOP_FULL is set.
stoop: recorded N inputs for KEY
The run passed and a proof was written.
stoop: not recorded: REASON
The run passed but couldn't be vouched for. See when it runs anyway.