Intervals.icu CLI

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 activity
• intervals-icu-pp-cli activity get - An empty stub object is returned for Strava activities
• intervals-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_items
• intervals-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:

• hhopke/intervals-icu-mcp — Python
• eddmann/intervals-icu-mcp — Python
• mvilanova/intervals-mcp-server — Python
• q050cr/intervals-icu — Python
• rday/py-intervalsicu — Python
• freekode/tp2intervals — Kotlin

Generated by CLI Printing Press