CLI and AI agents

The gymgym CLI is built for people and for programs. Everything it can show it can print as JSON, and everything you can build in the app (routines, plans, logged workouts) it can create and edit, either step by step or as whole documents.

Agents can use gymgym two ways, with the same abilities and the same code underneath:

the MCP server at https://gymgym.club/mcp, for any assistant that speaks MCP, in the cloud (Claude, ChatGPT) or on your machine (Claude Code, Codex): nothing to install, you sign in and allow it in the browser. Every tool is listed in the MCP server reference;
CLI commands with --json, for scripts and agents that run shell commands.

Connect an assistant

The app’s /connect page walks people through this with copyable setup for each client, and Settings → Connected apps links to it.

Add https://gymgym.club/mcp to your assistant as a remote MCP server (often called a custom connector). For example, in Claude Code:

claude mcp add --transport http gymgym https://gymgym.club/mcp

In Codex (~/.codex/config.toml):

[mcp_servers.gymgym]
url = "https://gymgym.club/mcp"

The first time the assistant uses it, a gymgym page opens:

Sign in (Google, GitHub, a passkey or a guest account). If several accounts are signed in on this browser, pick the one the assistant should use.
Check what it asks for and choose Allow.

The assistant now acts as that account only. To give it another account, connect it again and pick the other one. Settings → Connected apps lists every app you allowed, with Remove access, which stops it at once. Assistants register themselves with a Client ID Metadata Document or, if they are older, dynamic registration; you don’t need to create anything first.

Several accounts: profiles

In the CLI, a profile is one signed-in account on one server. Sign in a second one next to the first and switch between them:

gymgym login                    # the "default" profile
gymgym login --profile coach    # another account; becomes current
gymgym profile                  # list them; * marks the current one
gymgym profile use default
gymgym today --profile coach    # one command as another profile
GYMGYM_PROFILE=coach gymgym workouts
gymgym logout --profile coach   # sign out of one and forget it

The web app has the same idea (Settings → Account → Add account, then switch from the account list or the sidebar), and so does the MCP server: connect an assistant once per account and pick the account when signing in.

Set up an agent with the CLI

Run gymgym login once on the machine the agent uses and approve the code at /device in your browser. Session tokens are stored per profile in ~/.config/gymgym/config.json (mode 0600), or wherever $GYMGYM_CONFIG points.
Give the agent the commands it may run. A useful read-only set is today, plan, routine list|show, workouts, workout show, weight and exercises; add routine / workout apply and log when it may write.
Point it at the formats: gymgym routine schema and gymgym workout schema print JSON Schemas, --example prints a valid sample, and Routine and workout documents explains every field.

Conventions

--json on every command prints the data as JSON on stdout. Prompts and progress go to stderr.
Exit code 0 on success, 1 on any problem, with one line on stderr starting gymgym:. Document errors name the field, e.g. gymgym: Document problem at exercises[1].sets: expected a whole number 1–20. Nothing is saved when a command fails.
No prompts when given everything: destructive commands need --yes; import needs --yes without a terminal; workout --as-planned logs a routine without asking; documents can be piped with -.
Names or ids: routines by name or a unique start of it, workouts by id (or its last characters, as shown by gymgym workouts), a date, or last; exercises by everyday name or id.
Units: documents carry a unit (kg or lb); weights are read and written in it. Commands and MCP tools use the account’s unit, which gymgym settings --unit lb (or the settings tool) changes. New accounts start in the unit of the browser’s region: pounds for the US, kilograms elsewhere.

Edit a routine

Read, change, write back:

gymgym routine show "Upper A" --json > upper.json
# … change upper.json (add an exercise, change reps to "8-12", set "superset": "A" on two entries) …
gymgym routine apply upper.json

Or one change at a time:

gymgym routine create "Upper A" --progression double
gymgym routine add "Upper A" "bench press" --sets 4 --reps 6-10 --weight 80 --rest 2:30
gymgym routine add "Upper A" pull-up --sets 3 --reps 6-10 --superset A
gymgym routine add "Upper A" "dumbbell lateral raise" --sets 3 --reps 12-15 --superset A
gymgym routine edit "Upper A" 1 --reps 5-8
gymgym routine move "Upper A" 3 1
gymgym plan set mon "Upper A"

A routine document can also plan extra sets per exercise: "warmups": 2 (ramped toward the first work weight, rounded to the plates you own), "drops": 1 and "bursts": 1 (drop sets and rest-pause bursts after the last work set), each 0–5. "deload": true on the routine makes it a planned deload: its sessions open on its own targets and never feed progression.

Log a workout

As a document (an agent that knows what was done):

gymgym workout apply - <<'JSON'
{ "name": "Evening push", "date": "2026-10-03", "minutes": 50,
  "exercises": [ { "exercise": "bench press", "sets": ["80x8", "80x7@8", "80x6"] } ] }
JSON

In set text, w: marks a warm-up, d: a drop set and rp: a rest-pause burst, e.g. ["w:40x10", "80x8", "d:60x8"]. Warm-ups never count for volume, records or progression; drop sets and bursts count for volume only. An exercise can carry a "note" (with "pinned": true it reappears in later workouts with that exercise) and "skipProgression": true; the same flag on the workout excludes the entire session.

Correct it later by applying the edited output of gymgym workout show last --json (it keeps its id). For a single exercise, gymgym log "bench press" 85x3 85x3 is shorter. The output of workout apply and log includes any new personal records.