goalline How it worksClaude Code hookGitHub ActionBenchmarkCommandsGitHub

goalline / Commands

goalline command reference

Every command and option of goalline 0.14.0, exactly as goalline help prints it.

goalline 0.14.0: goal-line technology for your tests. Signed receipts that a check ran on this
exact code, and checks that catch a coding agent moving the goalposts. (Its old name, receipts, still works.)

  goalline run --gate <name> [options] -- <command>
      Run a gate (tests, lint, build) and save a signed receipt for the exact code it ran on.
      Exits with the command's own exit code.
      --count label=regex   count a pattern in the output; any hit makes the receipt WARNED
                            (e.g. --count 'http429="statusCode":429')
      --idle-mb <n>         free memory needed at the start to call the run idle (default 1600)
      --env-keys A,B        also record these env vars, as hashes
      --no-machine          skip the idle and other-runner checks
      --reuse               skip the gate when this exact code already passed it: prints that pass and
                            exits 0 (--reuse-runs 2 needs two passes, --reuse-idle one on an idle machine)
      --rules <file>        also check whether the files changed since an earlier pass can affect this
                            gate. A trial unless trusted: the gate still runs, and whether skipping would
                            have been right is recorded (goalline trial-report)
      --trust-rules         with --rules: really skip, writing a CARRIED receipt for this code
      --input name=<probe>  something the gate depends on that the code doesn't hold, read right
                            before and after the run and kept on the receipt as a hash. db=pg is
                            the schema pg_dump reports for $DATABASE_URL (pg:VAR for another
                            variable); any other probe is a command whose output says what
                            matters. Repeatable. In --rules, "inputs" names the gates that need each
      --clock-ttl <time>    when the project's code reads the real clock (Date.now(), new Date()) in a
                            Jest, Vitest or node --test run, its receipt counts until the next midnight;
                            this sets another time instead (12h, 7d, or 0: never). Fake timers count
                            while their time came from the real clock, not once set to a fixed time
      --no-clock            don't watch the clock

  goalline verify [--require a,b,browser:2] [--idle browser] [--input db=pg] [--json]
      Show which gates have valid receipts for the code in this checkout, without re-running them.
      Exits 1 if a --require'd gate is not proven. A receipt made with --input counts only while
      the same probe still reads the same.

  goalline goalpost [--base origin/main] [--head HEAD] [--cwd apps/web] -- npx jest {files}
      Run the OLD versions of the test files this change edited or deleted against the NEW code.
      An old test that now fails means behaviour changed and the tests were edited to match.
      Jest, Vitest (-- npx vitest run {files}) and pytest (-- python -m pytest {files}) are
      judged test by test; any other runner file by file, by its exit code.
      An old file that only fails to compile against the new types (ts-jest) is run again with the
      type check off, so its tests are judged on behaviour (--no-retry-untyped: leave it BROKE).
      An old test that only crashes inside the new code (its fixtures or mocks lack something the
      new code needs) is CRASHED: not judged, rather than MOVED.
      A flagged test the change explains in .goalpost-acks.json (goalline guard --ack) shows its
      reason and doesn't count against it; only entries the change added count (--no-acks: none).

  goalline prove-red [--base origin/main] [--head HEAD] [--cwd apps/web] -- npx jest {files}
      Run the NEW tests this change adds against the BASE code. A new test that passes there
      does not test the change.

  goalline guard [--base origin/main] [--cwd apps/web] [--hook] -- npx jest {files}
      A stop check for coding agents: goalpost on the work as it stands (uncommitted files
      included). Exits 2 while an old test expectation no longer holds and is not acknowledged,
      so a Claude Code Stop hook keeps the agent working. --hook reads the hook's JSON on stdin.
      goalline guard --ack "<test file>::<test name>" --why "<reason>"   accept one change
      goalline guard --report                                           the reviewer's ledger
      Acks go in .goalpost-acks.json; commit it and goalpost in CI shows the reasons. An entry
      already on the base explained an earlier change, so it never counts again.
      --max-blocks <n>   stop blocking after n identical blocks (default 3)

  goalline history [--limit 200] [--cwd apps/web] [--out goalline-history] [--from-git] -- npx jest {files}
      What goalpost would have flagged on the repository's last merged PRs: each merge commit
      against its first parent, one at a time while the machine is idle. Writes report.md (the
      PRs that need a look, with the old and new values) and results.jsonl (resumable).
      --from-git reads the PRs from merge commits instead of GitHub. --first-heads also judges
      each PR as first opened. --max-minutes <n> pauses (exit 4); run it again to resume.
      --plan counts what would run; --config <file.json> for several areas.

  goalline prune [--older-than 30d] [--before <time>] [--tree <sha>] [--gate <name>] [--dry-run]
      Delete receipts that can never prove anything (unreadable, the code changed during the run,
      or a pass that read the real clock and expired), plus the ones that match every filter given. A failed or flagged run is never deleted
      just because a later run passed: it is the record that the gate was flaky.

  goalline trial-report             what reuse saved, and how the rules trial is going

  goalline show <file.dsse.json>    print a receipt and check its signature
  goalline key                      print this machine's signing key

Common options: --repo <dir> (default: current directory) · --gate <name> · --deps-from <dir>
(where node_modules come from; default: --repo) · --tests <globs> · --keep (keep the scratch copy)
· --no-fail (exit 0 even when flagged) · --quiet (hide test output)
Tests that need a database (goalpost, prove-red):
  --fresh-db VAR=url-with-{db}   a database name for this run alone, in VAR for setup, tests and teardown
  --setup "<command>"            run in the scratch copy before the tests, e.g. "createdb {db} && npx prisma migrate deploy"
  --teardown "<command>"         always run afterwards, e.g. "dropdb {db}"
goalpost and prove-red exit 2 when they flag something. Receipts live in ~/.receipts (GOALLINE_HOME).

Install: npm install -g github:intikhab49/goalline, or run any command with npx github:intikhab49/goalline <command>.

Related