From d083beeee7bea710eb1f62ef6da13ead201a82d1 Mon Sep 17 00:00:00 2001 From: LeadGoEngineer Date: Mon, 25 May 2026 14:48:53 -0400 Subject: [PATCH] docs: add worked example for liftoff-export MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Moves the liftoff-export worked example out of quantcli/common (where it was misfiled in PR #24) and into this repo where it belongs — next to the binary it documents. Co-references in GETTING_STARTED.md will be updated in a follow-up PR against quantcli/common. Co-Authored-By: Paperclip --- docs/example.md | 181 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 181 insertions(+) create mode 100644 docs/example.md diff --git a/docs/example.md b/docs/example.md new file mode 100644 index 0000000..906bf44 --- /dev/null +++ b/docs/example.md @@ -0,0 +1,181 @@ +# Worked example: liftoff-export + +**Audience:** Liftoff (gymbros.com) users who want workout history or bodyweight trends in a terminal or piped to an LLM agent. + +**Prerequisites:** `liftoff-export` installed (see [GETTING_STARTED.md](https://github.com/quantcli/common/blob/main/GETTING_STARTED.md)), a Liftoff account, `liftoff-export auth login` completed. + +--- + +## 1. Authenticate + +Liftoff uses a stored OAuth token. Run the login flow once: + +```sh +liftoff-export auth login +``` + +This opens a browser tab. Complete the OAuth flow and the token is stored locally (`~/.config/liftoff-export/auth.json`). + +Check readiness: + +```sh +liftoff-export auth status +``` + +**Expected when logged in:** + +``` +logged in +``` + +Exit 0. **Expected when not logged in:** + +``` +Error: not logged in — run: liftoff-export auth login +``` + +Exit 1. + +--- + +## 2. Orient with `prime` + +```sh +liftoff-export prime +``` + +**Output** (reproduced at HEAD, 2026-05-19): + +``` +liftoff-export — primer for LLM agents +====================================== + +WHAT IT IS + CLI for personal Liftoff (gymbros.com) data: gym workouts with sets/ + reps/weights and recorded bodyweights. + +I/O + stdout: data in --format markdown (default; fitdown set notation) or json. + stderr: errors. Exit 0 on success including empty results. + +DATE FLAGS (every subcommand) + --since VALUE / --until VALUE + VALUE: today | yesterday | YYYY-MM-DD | Nd/Nw/Nm/Ny + See https://github.com/quantcli/common/blob/main/CONTRACT.md#3-date-flags + +SUBCOMMANDS + workouts list Every workout in the window + workouts show DATE Workouts on one specific day + workouts stats Per-exercise PR/recent + monthly bar charts + Filters: --exercise NAME, --detail + bodyweights list Recorded bodyweights, one per line + bodyweights stats Current/high/low + monthly trend + plateau + + Inspect any subcommand's row schema with: --since 1d --format json + +EXAMPLES + liftoff-export workouts show today + liftoff-export workouts stats --since 30d --format json | + jq '.[] | select(.type == "WR") | {name, vol: ([.sessions[].volume] | add)}' + liftoff-export bodyweights list --since 90d --format json | + jq '[.[]] | (.[-1].weight - .[0].weight)' + +GOTCHAS + - Workout dates are LOCAL — 11pm workouts bucket on the day you logged them. + - API hosts rotate; set LIFTOFF_API_BASE=https://vX-Y-Z.api.getgymbros.com + if data calls fail with "server is deprecated". + - Bodyweight is read off Post.bodyweight (the value you entered for that + workout). No workout that day means no bodyweight that day. + - 'workouts stats' bins exercises by name. Renaming an exercise in + Liftoff splits it into two summaries. +``` + +--- + +## 3. List recent workouts + +```sh +liftoff-export workouts list --since 7d +``` + +**Expected output** (markdown, one row per workout): + +``` +| Date | Title | Exercises | Duration | +|------------|------------------|-----------|----------| +| 2026-05-14 | Push A | 5 | 58m | +| 2026-05-17 | Pull A | 4 | 52m | +``` + +For the full set-level detail, use `--format json`: + +```sh +liftoff-export workouts list --since 7d --format json | jq '.[0]' +``` + +--- + +## 4. Show a specific day's workout + +```sh +liftoff-export workouts show today +``` + +Shows all workouts logged on today's local calendar date, including each exercise's sets, reps, and weights in fitdown-style markdown. + +--- + +## 5. Track bodyweight trend + +```sh +liftoff-export bodyweights list --since 90d +``` + +To compute weight change over the period: + +```sh +liftoff-export bodyweights list --since 90d --format json \ + | jq '[.[]] | (.[-1].weight - .[0].weight)' +``` + +--- + +## 6. Check flag validation (contract §3, §7) + +These run without credentials (hermetic by [CONTRACT.md §7](https://github.com/quantcli/common/blob/main/CONTRACT.md#7-hermeticity)): + +```sh +liftoff-export workouts list --help # exits 0; no network call +``` + +**Expected:** help text including `--since`, `--until`, `--format` flags; exit 0. + +--- + +## 7. Run the contract conformance suite + +```sh +git clone https://github.com/quantcli/liftoff-export-cli +cd liftoff-export-cli +go build -o /tmp/liftoff-export . +LIFTOFF_EXPORT_BIN=/tmp/liftoff-export go test -tags=compat ./... +``` + +**Expected:** + +``` +ok github.com/quantcli/liftoff-export-cli 0.003s +``` + +The `compat` suite covers CONTRACT.md §4 parse-level conformance (the `--format` flag, `UnknownFormatFails`, `FlagValidationIsHermetic`) across all four data-producing subcommands (`workouts list`, `workouts stats`, `bodyweights list`, `bodyweights stats`). Data-path subtests (`--format json` with live data) are skipped because the suite does not provision a Liftoff OAuth token; the parse-level subtests run without credentials. + +--- + +## What to look at next + +- `liftoff-export workouts stats --help` — per-exercise PR summaries and filters +- `liftoff-export prime` — jq recipes and API host rotation gotcha +- [CONTRACT.md §3](https://github.com/quantcli/common/blob/main/CONTRACT.md#3-date-flags) — date flag semantics +- [CONTRACT.md §4](https://github.com/quantcli/common/blob/main/CONTRACT.md#4-output-format) — output format contract +- [crono-export example](https://github.com/quantcli/crono-export-cli/blob/main/docs/example.md) — if you also track nutrition +- [withings-export example](https://github.com/quantcli/withings-export-cli/blob/main/docs/example.md) — if you have Withings devices