incremnt

Official command-line tool and MCP server for querying your INCREMNT strength training data. INCREMNT is a strength training app for iPhone and Apple Watch.

Requires the incremnt iOS app — all workout data originates there.

Setup

npm install -g incremnt
incremnt login
incremnt mcp install   # registers with Claude Desktop, Claude Code, and Codex CLI

This installs two binaries:

• incremnt (CLI)
• incremnt-mcp (MCP server over stdio)

incremnt mcp install auto-registers the MCP server with Claude Desktop, Claude Code, and Codex CLI. Restart your assistant app after installing.

CLI

Hosted sync (recommended)

After connecting with Apple in the iOS app (Settings > Cloud Sync), your workouts sync automatically. To access them from the CLI:

incremnt login
incremnt sessions list --limit 5
incremnt records
incremnt programs current
incremnt exercises history --name "Bench Press"
incremnt browse

Headless agents

Agent tokens are named bearer tokens for cron jobs, MCP servers, and other non-browser clients. They default to read-only access and expire after 90 days.

Create and use a read-only token:

incremnt login
incremnt agents create --name "morning report"
export INCREMNT_AGENT_TOKEN=incr_agent_...
export INCREMNT_BASE_URL=https://incremnt-sync.onrender.com
incremnt sessions list --limit 5

Create a write-capable token only for workflows that need existing write commands such as Ask/proposals or observation lifecycle actions:

incremnt agents create --name "coach writer" --access write --expires-days 30

Persist an agent token into the normal CLI session file:

incremnt agents create --name "local mcp" --store
incremnt login --agent-token incr_agent_...

Manage tokens from a human session:

incremnt agents list
incremnt agents revoke --id agt_...

Token safety:

• Agent token plaintext is shown once on create.
• Store secrets in your shell, process manager, or MCP host secret mechanism, not in source control.
• INCREMNT_AGENT_TOKEN takes precedence over the stored session and is never persisted by status or read commands.
• Agent tokens cannot create, list, or revoke other agent tokens.

Local snapshot

If you prefer to work offline, import a snapshot into the local session:

incremnt login --snapshot ~/Downloads/export.onemore.json
incremnt sessions list --limit 5

Or import a session file:

incremnt login --session-file ~/Downloads/session.json

Commands

| Command | Description | |---------|-------------| | sessions list | Recent sessions with duration and exercise count | | sessions show --id <id> | Details for a single session | | sessions compare --session-id <id> | Compare planned vs actual | | sessions explain --session-id <id> | Explain session context | | programs current | Active program state | | programs list | All programs | | programs show --id <id> | Full program detail | | exercises history --name <name> | Set-by-set history for an exercise | | records | Personal records (best e1RM per exercise) | | health history | Daily health rows, units, per-metric coverage and fetch timestamps | | health summary / health ai | Health metrics and AI summary | | training load | ATL/CTL/TSB and workload context | | ask history / ask show --id <id> | Coach conversation history | | increment-score current | Latest Increment Score summary with components, drivers, trend, and data-quality flags | | increment-score history | Historical Increment Score snapshots | | increment-score upload --file <file> | Upload Increment Score snapshots | | coach observations list | Current persisted coach observations | | coach observations seen --id <id> | Mark a coach observation as seen | | coach observations dismiss --id <id> | Dismiss an observation and suppress matching follow-ups | | programs create --file <file> | Create an inactive saved program from generated-plan JSON, including day-local supersets; duration is shaped by concrete work, not a sessionLengthTarget field | | programs propose --file <file> | Submit a program proposal | | programs proposals | List proposals | | programs proposal dismiss --id <id> | Dismiss a proposal | | programs share create --program-id <id> | Create a public share token for a program | | programs share list --program-id <id> | List share artifacts for a program | | programs share fetch --token <token> | Fetch a publicly shared program | | programs share revoke --share-id <id> | Revoke a previously issued share | | browse | Interactive Ink browser for sessions, programs, records, goals, cycles, and health | | tui | Alias for browse | | mcp install | Register incremnt-mcp with Claude Desktop, Claude Code, and Codex CLI | | login | Authenticate with the hosted sync service (opens browser) | | login --no-browser | Headless login flow for SSH/Termius/remote shells | | login --agent-token <token> | Store direct agent-token auth for CLI/MCP | | agents create --name <name> | Create a read-only named agent token | | agents create --name <name> --access <read\|write> | Create a named agent token with explicit access | | agents list | List agent token metadata and token hints | | agents revoke --id <id> | Revoke an agent token | | logout | Clear stored session | | status | Show current mode, auth state, and config paths | | contract | Machine-readable command surface for scripts |

Flags

| Flag | Description | |------|-------------| | --json | Force JSON output for command responses | | --limit <n> | Limit number of results (sessions list, ask history) | | --days <n> | Day window (health summary) | | --program-id <id> | Filter cycle summaries to a program | | --base-url <url> | Override remote sync service URL for login/bootstrap | | --snapshot <file> | Bootstrap login from a local snapshot | | --session-file <file> | Import an existing session file | | --token <token> / --email <email> | Non-interactive bootstrap login options | | --agent-token <token> | Store direct agent-token auth with login |

Browse mode key bindings

incremnt browse (or incremnt tui) launches an interactive TUI.

• Tab / Shift+Tab: cycle pane focus (sections → items → detail)
• 1 / 2 / 3: jump focus directly to sections / items / detail
• h/l or ←/→: move pane focus
• j/k or ↑/↓: navigate rows in focused list pane
• /: enter search mode for current list pane
• Esc: exit search or move focus back
• Ctrl-U: clear search query (in search mode)
• Ctrl-L: clear query and exit search mode
• Enter: open/select in focused pane
• PgUp/PgDn, g/G, Home/End: list navigation shortcuts
• r: refresh detail for selected item
• q or Ctrl-C: quit

Exercise matching

exercises history --name "Bench Press" uses canonical synonym matching, so it finds Barbell Bench Press without pulling in incline, machine, or dumbbell variants.

MCP Server

The package includes an MCP server for AI assistants like Claude and Codex.

Run incremnt mcp install to auto-register the server with Claude Desktop, Claude Code, and Codex CLI (see Setup above).

To register manually instead, add to your Claude Code project config (.mcp.json):

{
  "mcpServers": {
    "incremnt": {
      "type": "stdio",
      "command": "incremnt-mcp"
    }
  }
}

The MCP server uses the same auth resolver as the CLI. It prefers INCREMNT_AGENT_TOKEN, then the stored session from incremnt login or incremnt login --agent-token.

For a headless MCP host:

export INCREMNT_BASE_URL=https://incremnt-sync.onrender.com
export INCREMNT_AGENT_TOKEN=incr_agent_...
incremnt-mcp

Read-only agent tokens can call read tools. Write tools return structured JSON with code: "INSUFFICIENT_SCOPE" unless the active token has write access. Missing, expired, or incompatible auth also returns structured JSON errors so agents can reauth or downgrade cleanly.

MCP tool surface

The MCP server exposes two tool families:

• Command-shaped tools from the public CLI contract, including sessions, programs, cycles, goals, health, training load, ask history/show, increment-score-current, increment-score-history, increment-score-upload, coach-observations-current, inactive generated program creation, program proposals, and program shares.
• Typed coach read tools for agent-native context retrieval. The registry in src/queries/coach-read-tools.js is the source of truth and includes session detail/comparison/explanation, programme list/detail/progress/history, exercise history/progress, records, readiness, body weight, training load, Increment Score, volume trends, training profile, and Coach observations.

The public hosted ChatGPT MCP is a read-only subset governed by src/hosted-mcp-parity.js. That registry must account for every CLI read capability as either covered by one or more typed tools or explicitly excluded with a product/safety reason; its parity test fails when the CLI gains an unclassified read.

get_increment_score returns the same privacy-safe score summary as increment-score current: score, snapshot timestamp, formula version, data tier, component scores, positive/negative drivers, day-over-day delta, recent trend, and data-quality flags. It does not expose raw HealthKit values.

You can inspect the exact machine-readable contract at any time:

incremnt contract

License

MIT

Daily health evidence

incremnt health history --metrics body_weight,steps,sleep_duration,active_energy --since 2026-08-01 --until 2026-09-06 --json

Omit --metrics for all supported metrics or dates for the last 30 days. History is bounded to 365 days. Missing dates are not filled with zero. Each metric reports observed/requested days, latest measurement date and age at the window end, and fetch time when available. Missing samples do not prove denied HealthKit access; today can be incomplete, and weight/VO2 max need not be recorded daily. Active energy is neither food intake nor total daily expenditure.

Nutrition uses dietary_energy (kcal), dietary_protein, dietary_fat, and dietary_carbohydrates (grams). These are recorded Apple Health totals: food logs can be incomplete or contain duplicate entries from multiple food apps. A logged day is not proof of complete intake.

An updated iOS app must obtain HealthKit read access and sync before these fields are available. Enable Nutrition (Calories & Macros) in Coach data sources to share them with hosted MCP; this setting defaults off and takes effect after sync. Dev MCP exposes the shared health-history schema; the published public tool registry remains gated. Local CLI/MCP can query the same fields in an owned snapshot.

The CLI uses the same authenticated get_health_history read endpoint as local MCP and Ask Coach. A running older MCP installation must be updated/restarted to discover new tools. Hosted ChatGPT discovery remains separately gated by INCREMNT_MCP_HEALTH_HISTORY_ENABLED=true after connector review; updating this code does not enable the published connector.