CLI reference¶

evaltrack --help lists the commands and evaltrack <command> --help documents every flag. This page covers what the help output cannot: what a command's output means, and what the exit codes promise.

evaltrack push¶

Re-pushing under an existing run id replaces the stored run, so re-pushing the same file is safe. The ref is separate. A re-push does not update the --commit, --pr or --title on a ref that already points at the run. See Moving a ref is idempotent.

evaltrack promote¶

promote writes baseline to the remote. If the target is the local repository, the command exits 2. See Repositories › Promote and Cleaning up runs.

evaltrack runs¶

Lists recorded runs, newest first, one per line: the run id, the recording time in UTC, the short commit, the test counts, and the branch label when the run recorded one. A commit carries -dirty when the working tree had uncommitted changes at eval time.

$ evaltrack runs --local
01KZ5HPEFPMGTMCXB288BVGECV  2026-08-04T04:49:46Z  9b8c7d6e-dirty  2/14 failed  (feature/better-prompt)
01KZ5HPEFMEBFBF39RT2SAJSJV  2026-08-04T04:49:46Z  3f9c1a2b        12 tests, none failed  (main)

evaltrack refs¶

Lists refs and the runs they point at. baseline comes first, then the PR refs, then the rest. A line holds the ref name, the run it targets, when it last moved (UTC), and the PR number and title when the move recorded them.

$ evaltrack refs --remote
baseline  01KZ5HPEFMEBFBF39RT2SAJSJV  2026-08-04T04:49:47Z
pr/482    01KZ5HPEFPMGTMCXB288BVGECV  2026-08-04T04:49:47Z  #482 Rework the summarizer prompt

Both listings are for reading. The fields and their order can change in any release. Don't script against them.

evaltrack export¶

Prints a recorded run as JSON. Use it to inspect a run or archive one outside the repository. The same data is available in Python. See Reading runs from Python.

Exit codes: 0 when the run was exported. 1 when the named repository does not hold the run, and the error names that repository. 2 when no repository is named. Only report shares 1, so a script can act on the missing run alone.

evaltrack report¶

Writes a recorded run as one HTML file that opens from disk, with no server and no network.

evaltrack report --ref pr/482 --output evaltrack-report.html

To report a run that is not in a repository, name its run file with --run-file. For example, CI can report the file that pytest --evaltrack-run-file wrote. The page then does not list any refs.

The page also shows the run's history over the remote's baseline, and Compare to mainline against the run that baseline points at. Both come from the remote, whichever repository holds the run. Without a remote, the page shows the run alone and says why.

The page holds the inputs and outputs that the run recorded. Share it with the same care as the run. A value over 16 KB is left out, so a report of a large run stays small. Pass --full to embed every value whole.

Exit codes: 0 when the report was written. 1 when the repository does not hold the run or the ref. Nothing is written then. 2 when no repository is named, or when the run file is missing or does not parse.

evaltrack ui¶

The remote is not contacted at startup, so the dashboard comes up at once even when the remote is out of reach, for example without network or with an expired login. Its runs and refs then fail as you browse them, and the dashboard shows the storage error while your local runs stay usable.

The server always listens on your own machine, and no flag changes that. The dashboard trust model has why. The command hands the terminal to the server, so a server that cannot start exits with the server's own code rather than the codes below.

Exit codes¶

The four codes mean the same thing for every command. Where a command has more to say about one, it carries an Exit codes note.

Only export and report exit 1 today, for a run or ref the repository does not hold. Please report a 70 with the traceback.

Related: CI/CD · Repositories and storage