incremnt

Command-line tool and MCP server for querying your incremnt strength training data.

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 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 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, program proposals, and program shares.
• Typed coach read tools for agent-native context retrieval, including get_increment_score, get_recent_sessions, get_exercise_history, get_next_session, get_readiness_snapshot, get_body_weight_snapshot, get_goal_status, and get_records.

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