Skip to content
Browse documentation
Reference / ATH documentation

Command reference

Every ATH command, named the same way in the terminal, the sidebar and these guides.

The terms

  • Database: athlete.ath.sqlite, the one live local record used by ATH v1.
  • Package: a complete portable JSON snapshot made by ath export. It does not stay synchronized with the database.
  • Record: one logical item with a stable ID and numbered revisions.
  • Benchmark: a repeatable effort, such as fran. A result is an actual attempt at that benchmark.
  • Session: a workout recorded by a device. Link a result to its session to connect the score with those measurements.
  • Prediction: an estimate saved before an attempt. Grading compares an existing prediction with an existing result.
  • Skill: instructions for your agent. Gateway: the model provider used by terminal predictions.

Commands

Using the examples

Run commands from your ath-yourname folder. Values such as fran are benchmark IDs; ath stats shows what exists in your record. Replace example dates, source IDs and paths with your own.

--json selects structured output; it does not generally mean read-only. For ath predict specifically, it returns evidence without a model call or write. Use --dry-run only on commands that list it.

Your agent can use the same commands through the installed skill. In chat, say what you need in plain language, such as log fran 4:41 rx. Terminal syntax and chat prompts are different ways to request the same work.

$ath --help

Version

Reviewed against the public v1.1.0 source at commit 070754a on 8 November 2026. Use the help in your installed version if an option differs. ath share is present but publishing is not implemented.

v1.1.0 is the latest release on npm. These docs were reviewed against it on 8 November 2026.

$ath --version

Recent changes

v1.1.0, published 24 October 2026: ath migrate upgrades 1.0.0 databases in place after a verified backup, and ath models --default no longer overwrites the database. Until you migrate, 1.1.0 only reads a 1.0.0 database, and ath check flags its old schema. Migrating also clears false ath check errors from 1.0.0 provider imports.

The release notes list every change and the upgrade steps.

v1.1.0 is the latest release on npm. These docs were reviewed against it on 8 November 2026.

v1.0.0 moved the live record to SQLite, added stable record IDs and revisions, complete package export and restore, named calculations, record inspection and correction, import conflict handling, normal deletion and privacy erasure. v1 refuses prerelease 0.x ATH JSON documents and no converter ships.

Up nextRelease notes →