Skip to content

Commit ba98695

Browse files
Paperclip-PaperclipPaperclip-Paperclip
committed
docs: add worked example for crono-export
Moves the crono-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 <[email protected]>
1 parent 763fd97 commit ba98695

1 file changed

Lines changed: 202 additions & 0 deletions

File tree

‎docs/example.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
# Worked example: crono-export
2+
3+
**Audience:** Cronometer users who want their food log, nutrition totals, or biometrics in a terminal or piped to an LLM agent.
4+
5+
**Prerequisites:** `crono-export` installed (see [GETTING_STARTED.md](https://github.com/quantcli/common/blob/main/GETTING_STARTED.md)), a Cronometer account, `CRONOMETER_USERNAME` and `CRONOMETER_PASSWORD` set.
6+
7+
---
8+
9+
## 1. Verify credentials
10+
11+
```sh
12+
export CRONOMETER_USERNAME="[email protected]"
13+
export CRONOMETER_PASSWORD="yourpassword"
14+
crono-export auth status
15+
```
16+
17+
**Expected output when credentials are set:**
18+
19+
```
20+
error: missing CRONOMETER_USERNAME and CRONOMETER_PASSWORD
21+
```
22+
23+
Wait — that message appears when the variables are *not* set. When they are set, `auth status` exits 0 with a message like:
24+
25+
```
26+
logged in as [email protected]
27+
```
28+
29+
(The exact wording depends on whether a cached session exists. Exit 0 = ready to export.)
30+
31+
**If credentials are missing:**
32+
33+
```sh
34+
$ crono-export auth status
35+
error: missing CRONOMETER_USERNAME and CRONOMETER_PASSWORD
36+
$ echo $?
37+
1
38+
```
39+
40+
Exit 1 with a stderr message naming the missing variable. Set both and re-run.
41+
42+
---
43+
44+
## 2. Orient with `prime`
45+
46+
```sh
47+
crono-export prime
48+
```
49+
50+
**Output** (reproduced at HEAD, 2026-05-19):
51+
52+
```
53+
crono-export — primer for LLM agents
54+
=====================================
55+
56+
WHAT IT IS
57+
CLI for personal Cronometer data: per-food log, daily nutrition totals,
58+
biometrics (weight/fat/BP/...), exercises, and notes.
59+
60+
I/O
61+
stdout: data in --format markdown (default) or json.
62+
stderr: errors. Exit 0 on success including empty results.
63+
64+
AUTH
65+
Env-var credentials (always required):
66+
CRONOMETER_USERNAME your Cronometer email
67+
CRONOMETER_PASSWORD your Cronometer password
68+
69+
Session is cached at $XDG_CACHE_HOME/crono-export/session.json (mode 0600)
70+
so consecutive calls reuse one login. Set CRONOMETER_NO_CACHE=1 to
71+
disable. 'crono-export auth logout' clears the cache.
72+
73+
crono-export auth status Exit 0 if both vars set, 1 with "missing X".
74+
75+
DATE FLAGS (every subcommand)
76+
--since VALUE / --until VALUE
77+
VALUE: today | yesterday | YYYY-MM-DD | Nd/Nw/Nm/Ny
78+
Default when neither given: last 7 days ending today.
79+
See https://github.com/quantcli/common/blob/main/CONTRACT.md#3-date-flags
80+
81+
SUBCOMMANDS
82+
servings per-food log; one row per food eaten, full nutrient breakdown
83+
nutrition daily totals across all foods (one row per day, all macros + micros)
84+
biometrics weight, body fat, blood pressure, custom metrics
85+
exercises logged cardio / strength / custom activities
86+
notes user-entered notes per day
87+
88+
Inspect any subcommand's row schema with: <subcommand> --since today --format json
89+
90+
EXAMPLES
91+
crono-export nutrition --since today
92+
crono-export servings --since 7d --format json | jq '[.[] | .ProteinG] | add'
93+
crono-export biometrics --since 30d --format json |
94+
jq 'map(select(.Metric == "Weight")) | sort_by(.RecordedTime) | last'
95+
96+
GOTCHAS
97+
- 'today' is your LOCAL calendar day, not UTC.
98+
- 'RecordedTime' is date-only (midnight in your local zone); Cronometer's
99+
CSV exports don't carry meal-time, so all times sort as 00:00.
100+
- Markdown drops zero-valued nutrients; use --format json for every column.
101+
- 'servings' rows have a 'Day' field that is always null — use 'RecordedTime'.
102+
```
103+
104+
---
105+
106+
## 3. Export last week's nutrition totals
107+
108+
```sh
109+
crono-export nutrition --since 7d
110+
```
111+
112+
**Expected output** (markdown, one row per day):
113+
114+
```
115+
| Day | Energy (kcal) | Protein (g) | Carbs (g) | Fat (g) |
116+
|------------|---------------|-------------|-----------|---------|
117+
| 2026-05-12 | 2150 | 142 | 210 | 68 |
118+
| 2026-05-13 | 1980 | 130 | 195 | 62 |
119+
...
120+
```
121+
122+
*Note: actual column set is wider (full micro/macronutrient breakdown). Rows with all-zero values for a nutrient are omitted in markdown; use `--format json` for every column.*
123+
124+
To get JSON for scripting:
125+
126+
```sh
127+
crono-export nutrition --since 7d --format json | jq '.[0]'
128+
```
129+
130+
---
131+
132+
## 4. Sum protein from the food log
133+
134+
```sh
135+
crono-export servings --since 7d --format json | jq '[.[] | .ProteinG] | add'
136+
```
137+
138+
This pipes the structured food-log (one object per food serving) to `jq` and sums the `ProteinG` field.
139+
140+
---
141+
142+
## 5. Get most recent weight measurement
143+
144+
```sh
145+
crono-export biometrics --since 30d --format json \
146+
| jq 'map(select(.Metric == "Weight")) | sort_by(.RecordedTime) | last'
147+
```
148+
149+
---
150+
151+
## 6. Check flag validation (contract §3, §7)
152+
153+
These commands verify that the CLI conforms to [CONTRACT.md §3](https://github.com/quantcli/common/blob/main/CONTRACT.md#3-date-flags) and [§7](https://github.com/quantcli/common/blob/main/CONTRACT.md#7-hermeticity) without live credentials:
154+
155+
```sh
156+
crono-export nutrition --help # exits 0; no network call
157+
```
158+
159+
```sh
160+
crono-export nutrition --since lol 2>&1; echo "exit: $?"
161+
```
162+
163+
**Expected:**
164+
165+
```
166+
error: bad --since: invalid date "lol" (use YYYY-MM-DD, today, yesterday, or Nd/Nw/Nm/Ny)
167+
exit: 1
168+
```
169+
170+
Error on stderr, nothing on stdout, exit 1. Matches CONTRACT.md §3.
171+
172+
---
173+
174+
## 7. Run the contract conformance suite
175+
176+
```sh
177+
git clone https://github.com/quantcli/crono-export-cli
178+
cd crono-export-cli
179+
go build -o /tmp/crono-export .
180+
EXPORT_CLI_BIN=/tmp/crono-export go test -tags=compat ./...
181+
```
182+
183+
**Expected:**
184+
185+
```
186+
ok github.com/quantcli/crono-export-cli 0.010s
187+
ok github.com/quantcli/crono-export-cli/cmd 0.005s
188+
...
189+
```
190+
191+
All green. The `compat` suite covers CONTRACT.md §3 (date flags, hermetic `--help`) and §7 (hermeticity). Data-path subtests (`--format json` against live Cronometer) require real credentials; the parse-level subtests run without them.
192+
193+
---
194+
195+
## What to look at next
196+
197+
- `crono-export servings --help` — full flag list and column schema
198+
- `crono-export prime` — jq recipes and gotchas for LLM agent use
199+
- [CONTRACT.md §3](https://github.com/quantcli/common/blob/main/CONTRACT.md#3-date-flags) — date flag semantics
200+
- [CONTRACT.md §4](https://github.com/quantcli/common/blob/main/CONTRACT.md#4-output-format) — output format contract
201+
- [liftoff-export example](https://github.com/quantcli/liftoff-export-cli/blob/main/docs/example.md) — if you also track gym workouts
202+
- [withings-export example](https://github.com/quantcli/withings-export-cli/blob/main/docs/example.md) — if you have Withings devices

0 commit comments

Comments
 (0)