Skip to content

docs: trim prime to one screen #27

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
DTTerastar merged 1 commit into from
May 9, 2026
Merged

docs: trim prime to one screen #27

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 28 additions & 83 deletions cmd/prime.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,113 +10,58 @@ const primeText = `crono-export — primer for LLM agents
=====================================

WHAT IT IS
A CLI that reads your personal Cronometer data (per-food log, daily totals,
weight/biometrics, exercises, notes) and prints it on stdout.
CLI for personal Cronometer data: per-food log, daily nutrition totals,
biometrics (weight/fat/BP/...), exercises, and notes.

OUTPUT FORMATS
Default: narrow, fitdown-style markdown — date-grouped headings, one
bullet per non-zero field, easy to skim and easy for an LLM to consume
inline. Zero-valued nutrients are suppressed in markdown.

--format json Pretty-printed JSON ARRAY of full rows. Use this when
you want the complete row, when piping to jq, or when
round-tripping into other tools. Nothing is suppressed.

Errors go to stderr. You do NOT need '2>&1'. Exit code is 0 on
success and non-zero on auth or network failure. An empty result is
success — markdown prints "_(no records in window)_", JSON prints '[]'.
I/O
stdout: data in --format markdown (default) or json.
stderr: errors. Exit 0 on success including empty results.

AUTH
Set both env vars before invoking. No config file or token cache; the CLI
logs in on every run.
Env-var only — the CLI logs in on every run, no token cache.
CRONOMETER_USERNAME your Cronometer email
CRONOMETER_PASSWORD your Cronometer password

'crono-export auth status' is a fast local check that exits 0 when both
vars are set, 1 with a clear "missing X" message otherwise.
crono-export auth status Exit 0 if both vars set, 1 with "missing X".

DATE FLAGS (every export subcommand accepts these)
--since VALUE inclusive lower bound
--until VALUE inclusive upper bound; defaults to today
DATE FLAGS (every subcommand)
--since VALUE / --until VALUE
VALUE: today | yesterday | YYYY-MM-DD | Nd/Nw/Nm/Ny
(no flag) last 7 days, ending today

Default when neither given: last 7 days ending today.
See https://github.com/quantcli/common/blob/main/CONTRACT.md#3-date-flags
for the cross-CLI specification.

SUBCOMMANDS
servings per-food log; one row per food eaten, full nutrient breakdown
nutrition daily totals across all foods (string-valued JSON — see GOTCHAS)
biometrics weight, body fat, blood pressure, custom metrics
exercises logged cardio / strength / custom activities
notes user-entered notes per day

servings — per-food log: one row per food eaten, full nutrient breakdown.
Markdown: ## per date, ### per food (group · name · quantity), bullets
for non-zero nutrients.
JSON: typed numbers. Keys (subset):
RecordedTime, Group, FoodName, QuantityValue, QuantityUnits,
EnergyKcal, ProteinG, CarbsG, FiberG, FatG, SodiumMg, CalciumMg,
IronMg, B12Mg, VitaminDUI, Omega3G, ... (60+ nutrients).

nutrition — daily totals: one row per day across all foods logged that day.
Markdown: ## per date, bullets for non-zero columns.
JSON: string-keyed (raw CSV columns, ALL VALUES ARE STRINGS — cast in jq).
Keys (subset):
"Date", "Energy (kcal)", "Protein (g)", "Carbs (g)", "Fat (g)",
"Fiber (g)", "Sodium (mg)", "Iron (mg)", "Calcium (mg)",
"B12 (Cobalamin) (µg)", "Cholesterol (mg)", "Completed", ...

biometrics — weight, body fat, blood pressure, custom metrics.
Markdown: ## per date, bullet per metric: "- Metric: amount unit".
JSON keys: RecordedTime, Metric, Unit, Amount.

exercises — logged cardio / strength / custom activities.
Markdown: ## per date, one bullet per session.
JSON keys: RecordedTime, Exercise, Minutes, CaloriesBurned, Group.

notes — user-entered notes per day. Markdown: ## per date with note
body. JSON: string-keyed (raw CSV).
Inspect any subcommand's row schema with: <subcommand> --since today --format json

EXAMPLES

# Today's macros, scannable
crono-export nutrition --since today

# Today's macros, parsed (numbers via tonumber)
crono-export nutrition --since today --format json | jq '.[] | {
date: .Date,
kcal: (."Energy (kcal)" | tonumber),
protein: (."Protein (g)" | tonumber)
}'

# 7-day protein total (servings is typed — no tonumber needed)
crono-export servings --since 7d --format json | jq '[.[] | .ProteinG] | add'

# All foods from today's breakfast
crono-export servings --since today --format json | jq '[.[] | select(.Group == "Breakfast") | .FoodName]'

# All servings on a specific day
crono-export servings --since 7d --format json | jq '[.[] | select(.RecordedTime | startswith("2026-04-25"))]'

# Latest weight reading in a 30-day window
crono-export biometrics --since 30d --format json | jq 'map(select(.Metric == "Weight")) | sort_by(.RecordedTime) | last'
crono-export biometrics --since 30d --format json |
jq 'map(select(.Metric == "Weight")) | sort_by(.RecordedTime) | last'

GOTCHAS
- "Today" is your LOCAL calendar day, not UTC.
- 'today' is your LOCAL calendar day, not UTC.
- 'nutrition' and 'notes' JSON values are STRINGS (raw CSV) — cast with
'jq tonumber' when doing math. 'servings', 'biometrics', 'exercises'
JSON values are already typed numbers.
- Markdown drops zero-valued nutrients to stay readable. If you need
every column (including zeros), use --format json.
- Cronometer logs by calendar day; nothing here is real-time. Two
'--since today' calls moments apart return the same data.
- 'servings' JSON rows contain a 'Day' field that is always null — use
'RecordedTime' (an ISO-8601 timestamp) for any date-based filtering.
'jq tonumber' when doing math. 'servings', 'biometrics', 'exercises'
are typed numbers.
- Markdown drops zero-valued nutrients; use --format json for every column.
- 'servings' rows have a 'Day' field that is always null — use 'RecordedTime'.
`

var primeCmd = &cobra.Command{
Use: "prime",
Short: "Print an LLM-targeted primer (output formats, subcommands, jq recipes)",
Short: "Print an LLM-targeted primer (one screen)",
Long: `Print a one-screen primer aimed at LLM agents calling this CLI as a tool.
Covers the output formats (markdown by default, --format json for structured),
auth env vars, the subcommands and what their rows look like, the shared
date flags, and a few jq recipes for common questions.`,
Covers I/O, auth, the shared date flags, the subcommand menu, and a few jq
recipes. Per the quantcli contract, prime is short — anything that wants
to grow into a man page belongs in --help on the relevant subcommand or
in https://github.com/quantcli/common/blob/main/CONTRACT.md.`,
RunE: func(cmd *cobra.Command, _ []string) error {
_, err := fmt.Fprint(cmd.OutOrStdout(), primeText)
return err
Expand Down
Loading