Command reference
Every ATH command, named the same way in the terminal, the sidebar and these guides.
The terms
- Record: athlete.ath.json and its neighbouring series/ sample files.
- 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 it with the result; backtesting repeats that process against history.
- Skill: instructions for your agent. Gateway: the model provider used by terminal predictions.
Commands
- ath init — Create a record and install the agent skill.
- ath skill — Check or refresh the instructions your agent uses.
- ath --update — Update ATH and refresh an existing agent skill in this folder.
- ath key — Manage a gateway key for predictions from the terminal.
- ath models — List available models or choose a default for predictions.
- ath import — Load device exports into your record.
- ath log — Save a workout result, a measurement or a note.
- ath link — Attach a logged result to a device-recorded session.
- ath stats — See what is in your record.
- ath series — Read daily summaries or individual measurement samples.
- ath check — Validate the record and its sample files.
- ath predict — Predict a benchmark with a model, or prepare evidence for your agent.
- ath grade — Record the outcome and compare it with a prediction.
- ath backtest — Replay past results to evaluate one or more models.
- ath share — Locate the latest backtest report. Sharing is not implemented yet.
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 --helpVersion
Reviewed against the public v0.4.3 source at commit cd89f72 on 27 September 2026. Use the help in your installed version if an option differs. ath share is present but publishing is not implemented.
Checked 27 September 2026: v0.4.3 is available on npm.
$ath --versionRecent changes
v0.4.3 restores the MIT license across the repository, npm package and bundled skill. The CLI behavior and file structure are unchanged.
v0.4.2 introduced ath --update for global npm, pnpm and bun installations, with existing skill refresh in the current folder. Existing v0.4.0 ath files remain valid; no migration is needed.