Gravitus CLI

The only CLI that syncs your Gravitus strength data into your training dashboard.

Gravitus has no API and no data export. gravitus-pp-cli handles the session auth, paginates your full workout history, and writes LiftingSession records directly into your dashboard's SQLite database — incremental, reliable, and scriptable.

Learn more at Gravitus.

Created by @azaaron (mvanhorn). Contributors: @tmchow (Trevin Chow).

Authentication

Gravitus uses Django session auth. Run gravitus-pp-cli auth login-password with your email and password — the CLI handles the CSRF token exchange and stores your session cookie in the config file. Re-run auth login whenever the session expires (typically every few weeks).

Quick Start

# authenticate — handles the CSRF dance automatically
gravitus-pp-cli auth login

# pull all workouts into dev.db as LiftingSession records
gravitus-pp-cli gravitus-sync --dashboard-db ./prisma/dev.db

# only fetch new workouts since last sync
gravitus-pp-cli gravitus-sync --incremental --dashboard-db ./prisma/dev.db

# view all personal records as structured JSON
gravitus-pp-cli exercises prs --agent

# find lifts with no progress in 6 weeks
gravitus-pp-cli exercises plateau --weeks 6

Unique Features

These capabilities aren't available in any other tool for this API.

Dashboard pipeline

• sync — Sync all Gravitus workouts into your training dashboard's SQLite database — writes LiftingSession records in the exact Prisma schema format with auth, pagination, and incremental support.

  Use to populate the training dashboard's lifting data — the only reliable way to authenticate and paginate all workout history into dev.db.

  gravitus-pp-cli gravitus-sync --dashboard-db ./prisma/dev.db
  

• export — Export your complete Gravitus training history to CSV or JSON — the first and only way to get your data out of Gravitus.

  Use when a coach, analyst, or AI agent needs the full training history outside the app.

  gravitus-pp-cli export --format csv --output training_history.csv
  

Analytics

• exercises plateau — Identifies exercises where estimated 1RM hasn't improved in N weeks — alert-style output for the dashboard coaching panel.

  Use before a program change — gives evidence-based list of which lifts need intervention.

  gravitus-pp-cli exercises plateau --weeks 6 --agent
  

• stats volume — Weekly total lifting volume (lbs) aggregated from all synced sessions — the same metric the dashboard LiftingSection displays.

  Use to feed the dashboard's volume trend chart or check load progression over a training block.

  gravitus-pp-cli stats volume --weeks 12 --agent
  

• exercises prs — All-time PRs across every exercise, extracted from PR markers on workout pages.

  Use to display the personal records panel in the dashboard or track PR cadence.

  gravitus-pp-cli exercises prs --agent
  

Usage

Run gravitus-pp-cli --help for the full command reference and flag list.

Commands

accounts

Authentication — login and session management

• gravitus-pp-cli accounts - Fetch login page to retrieve CSRF token

exercises

Exercise history, personal records, and volume trends

• gravitus-pp-cli exercises <exercise_slug> - Fetch exercise history with PR timeline and volume data

users

User profile and paginated workout history

• gravitus-pp-cli users <user_id> - Fetch user profile and paginated workout history list

workouts

Workout sessions with exercises, sets, reps, weight, and PRs

• gravitus-pp-cli workouts <workout_id> - Fetch full workout detail — exercises, sets, reps, weight, personal records

Output Formats

# Human-readable table (default in terminal, JSON when piped)
gravitus-pp-cli exercises mock-value

# JSON for scripting and agents
gravitus-pp-cli exercises mock-value --json

# Filter to specific fields
gravitus-pp-cli exercises mock-value --json --select id,name,status

# Dry run — show the request without sending
gravitus-pp-cli exercises mock-value --dry-run

# Agent mode — JSON + compact + no prompts in one flag
gravitus-pp-cli exercises 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
• Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
• 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

gravitus-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/gravitus-pp-cli/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Environment variables:

Name	Kind	Required	Description
GRAVITUS_SESSION_ID	per_call	Yes	Set to your API credential.

Troubleshooting

Authentication errors (exit code 4)

• Run gravitus-pp-cli doctor to check credentials
• Verify the environment variable is set: echo $GRAVITUS_SESSION_ID Not found errors (exit code 3)
• Check the resource ID is correct
• Run the list command to see available items

API-specific

• sync returns 0 workouts — run gravitus-pp-cli doctor — session likely expired, re-run auth login
• dashboard-db write fails — verify the path with gravitus-pp-cli doctor --dashboard-db <path> and ensure the file is not locked by the Next.js dev server
• auth login fails with CSRF error — run gravitus-pp-cli auth logout then auth login again to force a fresh CSRF token fetch

HTTP Transport

This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints. It does not require a resident browser process for normal API calls.

---

Sources & Inspiration

This CLI was built by studying these projects and resources:

• hevycli — Go
• hevy-mcp — TypeScript
• LiftShift — JavaScript

Generated by CLI Printing Press