Introducing tnr: TheNextRace From Your Terminal
by The Next Race
Most of TheNextRace is built around a clean web UI. That's the right default — coaches plan out blocks visually, athletes drag workouts onto calendars, everything is laid out where you can see it.
But some of you have asked for something else. A way to pull the same data from a script. A way to fire off a quick race entry without opening a browser. A way to wire your TheNextRace account into the rest of your tooling.
Today we're publishing tnr — a small command-line tool that does exactly that.
Install
npm install -g @thenextrace/tnr
tnr login
tnr login walks you through pasting an API token (you generate one at Settings → API Tokens). After that, tnr is on your $PATH.
What's in it
tnr whoami show the current user
tnr race list [--upcoming] list your races
tnr race create --title ... --date ... --plan <id>
tnr plan list list training plans
tnr plan create --title ... create an empty plan
tnr plan delete <id> [-y] delete a plan (cascades to its races)
tnr workout list [--sport run] list library workouts
tnr workout create --title ... --sport run --type intervals
tnr profile show show your profile + physiology
tnr profile set --ftp 285 --threshold-pace 4:05 --max-hr 188
tnr mcp run as an MCP server (for AI agents)
Every command supports --json for clean machine-readable output to stdout. Status messages go to stderr. Exit codes follow standard conventions. That makes it pleasant to pipe into jq, glue into shell scripts, or call from your ~/.zshrc.
A few examples
See what's coming up:
tnr race list --upcoming
Pipe upcoming race titles into something else:
tnr --json race list --upcoming | jq -r '.[].title'
Add a race in one line, ready to script from your race-registration emails:
tnr race create \
--title "Berlin Marathon" \
--date 2026-09-27 \
--plan 142 \
--type marathon \
--priority A \
--location Berlin
The --type flag accepts canonical values like run_marathon, tri_full_distance, or friendly aliases like marathon, ironman, 70.3, 5k, half_marathon. Either form works.
Update your zones after a fresh threshold test:
tnr profile set --ftp 285 --threshold-pace 4:05 --max-hr 188 --weight 72
What this is also: an MCP server
The tnr mcp command turns the same binary into a Model Context Protocol server, which is what lets Claude Desktop, Cursor, Claude Code, and similar AI tools call your TheNextRace account directly. Same auth, same surface, just a different transport.
If you're an athlete who happens to live in a terminal, you'll probably enjoy that side of it too. We wrote about that flow in a separate post.
A note on tokens
API tokens are scoped to your account and treated like passwords. You can see, name, and revoke any of them from Settings → API Tokens. If a token gets exposed (accidentally committed, screenshot, shared), revoke it and create a new one — there's no limit.
We also store only the SHA-256 hash of every token, never the plaintext, so the value shown at creation is the only time anyone — including us — can see it.
What's next
A few CLI commands are deliberately not in v0.1: editing races, deleting individual races, calendar export (.ics), and pulling activity data. We left those out to keep the first release tight. They'll land in v0.2 once we see what people actually use.
If there's a command you want, the GitHub repo accepts issues — or just email us. The package is at @thenextrace/tnr on npm; the source is private for now but the CLI itself is open and inspectable via npm pack or unpkg.com.
Race well from the terminal.