--- name: pp-intervals-icu description: "The first intervals.icu CLI with a local training database — offline search, SQL Trigger phrases: `sync my intervals.icu data`, `what's my form`, `compare my power this season`, `show my wellness trends`, `what training did I miss`, `use intervals.icu`, `run intervals.icu`." author: "Milos Mladenovic" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - intervals-icu-pp-cli install: - kind: go bins: [intervals-icu-pp-cli] module: github.com/mvanhorn/printing-press-library/library/other/intervals-icu/cmd/intervals-icu-pp-cli --- # Intervals.icu — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `intervals-icu-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first: 1. Install via the Printing Press installer: ```bash npx -y @mvanhorn/printing-press-library install intervals-icu --cli-only ``` 2. Verify: `intervals-icu-pp-cli --version` 3. Ensure `$GOPATH/bin` (or `$HOME/go/bin`) is on `$PATH`. If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer): ```bash go install github.com/mvanhorn/printing-press-library/library/other/intervals-icu/cmd/intervals-icu-pp-cli@latest ``` If `--version` reports "command not found" after install, the install step did not put the binary on `$PATH`. Do not proceed with skill commands until verification succeeds. 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. ## When to Use This CLI Use when an agent or user needs to query intervals.icu training data programmatically: pulling activities, wellness, calendar and workouts, computing fitness/form, or comparing performance curves across seasons. Best when repeated queries make a local synced store worthwhile. ## Anti-triggers Do not use this CLI for: - Do not use for real-time device streaming during a ride - Do not use to edit another athlete's data without coach permissions - Do not use as a replacement for the web UI's interactive charts ## Unique Capabilities 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._ ```bash 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._ ```bash 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._ ```bash 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._ ```bash 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._ ```bash 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._ ```bash intervals-icu-pp-cli gear status --json ``` ## Command Reference **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 ` — The athlete to use is extracted from the bearer token and used to resolve power targets etc.. **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 ` — Get a shared event (e.g. race) ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash intervals-icu-pp-cli which "" ``` `which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query. ## Recipes ### Season-over-season power ```bash 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? ```bash intervals-icu-pp-cli form --days 42 --json ``` Show six weeks of fitness/fatigue/form to judge taper readiness. ### Catch up after a break ```bash intervals-icu-pp-cli since 14d ``` Digest of planned, completed and missed sessions over two weeks. ## Auth Setup Run `intervals-icu-pp-cli auth setup` to print the URL and steps for getting a key (add `--launch` to open the URL). Then set: ```bash export INTERVALS_ICU_API_KEY="" ``` Or persist it in `~/.config/intervals-icu-pp-cli/config.toml`. Run `intervals-icu-pp-cli doctor` to verify setup. ## Agent Mode Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color --yes`. - **Pipeable** — JSON on stdout, errors on stderr - **Filterable** — `--select` keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs: ```bash intervals-icu-pp-cli activity get mock-value --agent --select id,name,status ``` - **Previewable** — `--dry-run` shows the request without sending - **Offline-friendly** — sync/search commands can use the local SQLite store when available - **Non-interactive** — never prompts, every input is a flag - **Explicit retries** — use `--idempotent` only when an already-existing create should count as success, and `--ignore-missing` only when a missing delete target should count as success ### Response envelope Commands that read from the local store or the API wrap output in a provenance envelope: ```json { "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."}, "results": } ``` Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal AND no machine-format flag (`--json`, `--csv`, `--compact`, `--quiet`, `--plain`, `--select`) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout. ## Agent Feedback When you (or the agent) notice something off about this CLI, record it: ``` intervals-icu-pp-cli feedback "the --since flag is inclusive but docs say exclusive" intervals-icu-pp-cli feedback --stdin < notes.txt intervals-icu-pp-cli feedback list --json --limit 10 ``` Entries are stored locally at `~/.local/share/intervals-icu-pp-cli/feedback.jsonl`. They are never POSTed unless `INTERVALS_ICU_FEEDBACK_ENDPOINT` is set AND either `--send` is passed or `INTERVALS_ICU_FEEDBACK_AUTO_SEND=true`. Default behavior is local-only. Write what *surprised* you, not a bug report. Short, specific, one line: that is the part that compounds. ## Output Delivery Every command accepts `--deliver `. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported: | Sink | Effect | |------|--------| | `stdout` | Default; write to stdout only | | `file:` | Atomically write output to `` (tmp + rename) | | `webhook:` | POST the output body to the URL (`application/json` or `application/x-ndjson` when `--compact`) | Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr. ## Named Profiles A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern. ``` intervals-icu-pp-cli profile save briefing --json intervals-icu-pp-cli --profile briefing activity get mock-value intervals-icu-pp-cli profile list --json intervals-icu-pp-cli profile show briefing intervals-icu-pp-cli profile delete briefing --yes ``` Explicit flags always win over profile values; profile values win over defaults. `agent-context` lists all available profiles under `available_profiles` so introspecting agents discover them at runtime. ## Exit Codes | Code | Meaning | |------|---------| | 0 | Success | | 2 | Usage error (wrong arguments) | | 3 | Resource not found | | 4 | Authentication required | | 5 | API error (upstream issue) | | 7 | Rate limited (wait and retry) | | 10 | Config error | ## Argument Parsing Parse `$ARGUMENTS`: 1. **Empty, `help`, or `--help`** → show `intervals-icu-pp-cli --help` output 2. **Starts with `install`** → ends with `mcp` → MCP installation; otherwise → see Prerequisites above 3. **Anything else** → Direct Use (execute as CLI command with `--agent`) ## MCP Server Installation 1. Install the MCP server: ```bash go install github.com/mvanhorn/printing-press-library/library/other/intervals-icu/cmd/intervals-icu-pp-mcp@latest ``` 2. Register with Claude Code: ```bash claude mcp add intervals-icu-pp-mcp -- intervals-icu-pp-mcp ``` 3. Verify: `claude mcp list` ## Direct Use 1. Check if installed: `which intervals-icu-pp-cli` If not found, offer to install (see Prerequisites at the top of this skill). 2. Match the user query to the best command from the Unique Capabilities and Command Reference above. 3. Execute with the `--agent` flag: ```bash intervals-icu-pp-cli [subcommand] [args] --agent ``` 4. If ambiguous, drill into subcommand help: `intervals-icu-pp-cli --help`.