The first intervals.icu CLI with a local training database — offline search, SQL, and fitness/form analytics no other tool has.
Sync your activities, wellness, calendar, workouts and gear into local SQLite, then search, run SQL, and compute fitness/form trends offline. Wraps the full intervals.icu REST API for live reads and writes, and adds analytics every existing MCP server and wrapper leaves on the table.
Quick Start
# Check auth and API reachability first.
intervals-icu-pp-cli doctor --dry-run
# Populate the local store so offline commands work.
intervals-icu-pp-cli sync --since 365d
# Find activities by name/tag offline.
intervals-icu-pp-cli search "threshold"
# See your fitness/fatigue/form trend.
intervals-icu-pp-cli form --days 90
Unique Features
These capabilities aren't available in any other tool for this API.
Local state that compounds
-
sync — Sync your full activity, wellness, event, workout and gear history into a local SQLite database for offline search and SQL.
Reach for this first so search/sql/form work offline without hammering the API on every query.
intervals-icu-pp-cli sync --since 365d
-
form — Compute CTL (fitness), ATL (fatigue) and TSB/form from your synced activity load and show the trend.
Use to answer 'am I fresh enough to race / overreaching?' without opening the web UI.
intervals-icu-pp-cli form --days 90 --json
-
since — Show planned workouts, completed activities, and what was missed within a recent time window.
Use for a quick 'what happened / what's coming' digest after time away.
intervals-icu-pp-cli since 7d --json
Offline analysis
-
curve compare — Compare best power/pace/HR curves between two date ranges from the local store.
Use to quantify season-over-season fitness change for a given duration.
intervals-icu-pp-cli curve compare --metric power --this 90d --vs 365d --json
-
wellness trends — Correlate HRV / resting HR / sleep against training load over a window from the local store.
Use to spot whether HRV/resting-HR are tracking accumulated fatigue.
intervals-icu-pp-cli wellness trends --days 60 --json
-
gear status — Roll up distance/time per gear component against reminders to flag what needs service or replacement.
Use to catch chain/tyre/shoe replacement thresholds before they are overdue.
intervals-icu-pp-cli gear status --json
Recipes
Season-over-season power
intervals-icu-pp-cli curve compare --metric power --this 90d --vs 365d --json --select this.peaks,vs.peaks
Compare recent best power against a year ago, selecting just the peak arrays.
Fresh enough to race?
intervals-icu-pp-cli form --days 42 --json
Show six weeks of fitness/fatigue/form to judge taper readiness.
Catch up after a break
intervals-icu-pp-cli since 14d
Digest of planned, completed and missed sessions over two weeks.
Usage
Run intervals-icu-pp-cli --help for the full command reference and flag list.
Commands
activity
Manage activity
intervals-icu-pp-cli activity delete - Delete an activityintervals-icu-pp-cli activity get - An empty stub object is returned for Strava activitiesintervals-icu-pp-cli activity update - Strava activities cannot be updated
athlete
Manage athlete
intervals-icu-pp-cli athlete get - Get the athlete with sportSettings and custom_itemsintervals-icu-pp-cli athlete update - Update an athlete
athlete-plans
Manage athlete plans
intervals-icu-pp-cli athlete-plans - Change training plans for a list of athletes
chats
Manage chats
intervals-icu-pp-cli chats send-message - Returns the new message id. If a new chat was created then it is also returned.intervals-icu-pp-cli chats show - Get a chat by id
disconnect-app
Manage disconnect app
intervals-icu-pp-cli disconnect-app - Disconnect the athlete from the app matching the bearer token
download-workout-ext
Manage download workout ext
intervals-icu-pp-cli download-workout-ext <ext> - The athlete to use is extracted from the bearer token and used to resolve power targets etc.. Note that the create workout endpoint can convert workouts and might be more convenient.
pace-distances
Manage pace distances
intervals-icu-pp-cli pace-distances - List pace curve distances
shared-event
Manage shared event
intervals-icu-pp-cli shared-event <id> - Get a shared event (e.g. race)
Output Formats
# Human-readable table (default in terminal, JSON when piped)
intervals-icu-pp-cli activity get mock-value
# JSON for scripting and agents
intervals-icu-pp-cli activity get mock-value --json
# Filter to specific fields
intervals-icu-pp-cli activity get mock-value --json --select id,name,status
# Dry run — show the request without sending
intervals-icu-pp-cli activity get mock-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
intervals-icu-pp-cli activity get mock-value --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
intervals-icu-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/intervals-icu-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
INTERVALS_ICU_API_KEY | per_call | Yes | |
agentcookie (optional)
If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, intervals-icu-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.
Troubleshooting
Authentication errors (exit code 4)
- Run
intervals-icu-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $INTERVALS_ICU_API_KEY
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- 401 Unauthorized — Set INTERVALS_ICU_API_KEY to your key from intervals.icu Settings - Developer; username is the literal API_KEY.
- search/sql return nothing — Run sync first; those commands read the local store, not the live API.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press