---
name: athletic-standard
description: Set up Athletic Standard (ATH) and use its CLI and documentation to import device exports, log workouts, read training history, and work with predictions in an ath file. Use when someone asks to install ATH, configure its agent skill, or work with their .ath.json data.
license: MIT
---

# Athletic Standard

ATH is an open format and CLI for an athlete's training history. The athlete chooses their devices, agent, model and storage location. ATH itself requires no account or subscription. An ath folder contains `athlete.ath.json` and, when present, a neighbouring `series/` directory for dense measurements. Keep them together.

This is the web entry point for setup and documentation. The docs describe ATH v0.4.3, licensed under MIT. After setup, read the skill bundled with the installed CLI for its version-specific workflow and references. If the installed version differs, check `ath --help` and the relevant command's help before using its options.

Publication checked 27 September 2026: v0.4.3 is available in the repository and on npm under the MIT license. Check the live registry with `npm view athleticstandard version` and the installed CLI with `ath --version` before relying on a new feature.

## Set up ATH

1. Read [Getting started](https://ath.fit/docs/index.md) and [ath init](https://ath.fit/docs/init.md). If you have terminal and filesystem access, carry out the requested setup. Otherwise, guide the user through the commands and explain which steps still need to be run; do not claim to have installed anything.
2. Check `node --version`, `npm --version` and, if available, `ath --version`. ATH requires Node.js 20 or newer. If Node is missing, use the current LTS from [nodejs.org](https://nodejs.org/). If ATH is missing, install it:

   ```sh
   npm install -g athleticstandard
   ath --version
   ```

   If global installation is unavailable, use `npx athleticstandard` in place of `ath`. Keep an existing installation unless the user requested an upgrade or the required command is unavailable.

3. Use the athlete's existing ath folder when they have one. Otherwise, choose a folder named `ath-yourname`, such as `ath-mike` or `ath-jill`, in the location they want. Ask for a name or location only if it is still needed. The directory below is an example to replace with their choice:

   ```sh
   mkdir ath-mike
   cd ath-mike
   ath init --yes
   ```

   `--yes` skips the optional profile questions. Do not invent a name, birth year or sex. Do not replace an existing ath file. The user can keep the folder on their machine or in their own cloud storage; ATH does not provide cloud hosting or automatic synchronization. Commands need access to a writable folder.

4. `ath init` installs the bundled skill in `.agents/skills` and existing supported agent folders. Inspect its installed locations and read its `SKILL.md`, then the references needed for the user's task:

   ```sh
   ath skill --json
   ```

   For an existing ath folder with a missing or outdated skill, use `ath skill install`, then check again. See [ath skill](https://ath.fit/docs/skill.md). Do not substitute this short web guide for the full bundled skill.

5. Verify setup from that folder:

   ```sh
   ath check --json
   ath stats --json
   ```

   Tell the user where their ath folder is and whether validation and skill installation succeeded. An empty training history is expected before the first import or log. Import only a file they supplied or selected; do not add demo workouts to their history.

## Update an existing installation

When the user requests an upgrade, check the installed version and read [ath --update](https://ath.fit/docs/update.md).

- With v0.4.2 or newer, run `ath --update` from the athlete's folder. It updates a global npm, pnpm or bun installation with the same manager, then refreshes the skill if a copy already exists here. It does not create a skill where none is installed or modify training data.
- Before v0.4.2, rerun the original install command to get the latest published version, then run `ath skill install` from the athlete's folder. Do not assume the new flag is available until `ath --version` confirms it.
- A fetched npx/dlx/bunx copy does not become a global install. A project-local dependency or source checkout is not updated by this flag. Follow the update guide for those cases.
- Check `ath --version` and `ath skill` afterward. Read the refreshed skill before continuing. Use `ath skill install` alone when only the skill needs to be installed or refreshed. Existing v0.4.0 ath files remain valid; no migration is required for v0.4.3.

## Find the right documentation

Use [llms.txt](https://ath.fit/llms.txt) to find a guide. Every documentation page has a Markdown version, including [Getting started](https://ath.fit/docs/index.md) and the [command reference](https://ath.fit/docs/commands.md). Fetch the relevant page before constructing an unfamiliar command. [llms-full.txt](https://ath.fit/llms-full.txt) contains the complete docs when a single document is more convenient.

| Task | Documentation |
| --- | --- |
| Update ATH or refresh its agent skill | [ath --update](https://ath.fit/docs/update.md), [ath skill](https://ath.fit/docs/skill.md) |
| Understand the file, reconnect old logs, or switch devices | [Your athletic record](https://ath.fit/docs/record.md) |
| Import supported Apple Health, WHOOP or Oura exports | [ath import](https://ath.fit/docs/import.md) |
| Save a workout, score, measurement or note | [ath log](https://ath.fit/docs/log.md) |
| Connect a logged result to a device session | [ath link](https://ath.fit/docs/link.md) |
| Inspect coverage, sources and measurements | [ath stats](https://ath.fit/docs/stats.md), [ath series](https://ath.fit/docs/series.md) |
| Reason with an agent and prepare prediction evidence | [Working with agents](https://ath.fit/docs/agents.md), [ath predict](https://ath.fit/docs/predict.md) |
| Compare an actual result with a saved prediction | [ath grade](https://ath.fit/docs/grade.md) |
| Configure terminal models or evaluate past predictions | [ath key](https://ath.fit/docs/key.md), [ath models](https://ath.fit/docs/models.md), [ath backtest](https://ath.fit/docs/backtest.md) |
| Validate a file and its sample references | [ath check](https://ath.fit/docs/check.md) |

## Work with the athlete's data

- Read `ath stats --json` before reasoning about training. Use actual dates, benchmark IDs and source IDs from the file. Keep source attribution and gaps visible.
- Device measurements, manually entered measurements, athlete notes and vendor scores are distinct. Do not pool different devices' baselines or describe an athlete's report as a sensor reading. A missing recording is not proof of a rest day, and a training plan is not proof of a completed workout.
- For images, PDFs and messages, the agent extracts the workout details; `ath log` itself does not read images. Resolve unclear scores, dates, units and session matches before saving. Follow the bundled skill's write-review workflow.
- In an agent chat, use `ath predict <benchmark> --json` for evidence and reason with the agent already in use. That mode needs no gateway key and does not save a prediction. Follow the bundled prediction reference to save an estimate before the result is known. Bare `ath predict` and `ath backtest` use gateway models; they are separate terminal workflows, not a prerequisite for setup.
- `--json` selects structured output, not a general read-only mode. Use `--dry-run` only on commands whose documentation lists it. `ath share` does not publish anything in v0.4.3.

Source: [ATH repository](https://github.com/mwhitham/ath), [v0.4.3 bundled skill](https://github.com/mwhitham/ath/blob/cd89f72eceae3961ef1a05694226515c9e4321d2/skill/SKILL.md).