Watchletic CLI

The official Node 20+ command-line client for the Watchletic Data API. It reads and changes remotely meaningful Watchletic cloud data for Watchletic Club members, exports activities, and gives AI agents a bounded deterministic context without exposing provider credentials.

The canonical repository is watchletic/cli, and the npm package is @watchletic/cli.

Installation

npm install --global @watchletic/cli
watchletic auth login

Local development

npm install
npm run generate
npm test
npm run build
node dist/index.js --help

The generator reads ../watchletic-api/openapi/watchletic-v1.yaml. Generated types are committed, so package installation will not depend on a sibling repository.

npm pack and package publication use the committed generated types and do not require the sibling API repository. Run npm run generate explicitly when updating the contract during local development.

Use WATCHLETIC_API_URL to point at a local server and WATCHLETIC_ACCESS_TOKEN for an ephemeral access-token override. The environment token is never written to disk.

Agent context

watchletic context returns compact, deterministic JSON for training analysis and structured-workout planning. It includes recent activity metadata, readiness values and seven-day trends, summarized 90-day analytics, current fitness/fatigue/form, training-load configuration, and upcoming structured-workout summaries.

Full analytics curves, raw samples, live-tracking recipients, and complete structured-workout steps are intentionally excluded. Use the returned activity and structured-workout IDs with the focused activities get, activities raw, analytics get, or structured-workouts get commands when a specific question needs more detail.

Safety

Every mutation prints its exact before/after value and asks for confirmation. Non-interactive mutations require --yes. Structured-workout batches are always validated and their schedule diff is displayed before commit.

Exit codes

• 0 success
• 2 usage or validation failure
• 3 authentication failure
• 4 Watchletic Club membership required for data access
• 5 conflict or stale revision
• 6 raw data or requested export unavailable
• 7 partial bulk export
• 8 network or server failure
• 130 cancelled by the user