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.
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:
Generated by CLI Printing Press