The command line

The binary takes these flags and no subcommands. Everything else is in the configuration file, because a schedule is not something to retype.

ghchronicle -config /etc/ghchronicle/config.yaml

Every flag

Flag	Default	What it does
`-config`	`config.yaml`	Path to the configuration file
`-once`	off	Run one sweep and exit instead of scheduling; a family that is not due by its cadence is still skipped
`-list`	off	Print the repositories that would be collected, and which are set aside, then exit
`-version`	off	Print the version, the commit and the build date, then exit
`-groups`	off	Print the groups with the families in each, then exit
`-backfill`	off	Reach as far back as each surface allows, waiting for the rate limit to reset rather than stopping
`-backfill-since`	none	Bound the backfill: a date (`2024-01-01`), a duration (`720h`), days (`90d`) or years (`2y`)
`-card`	none	Run one sweep and write a summary SVG to this path; that sweep runs every family, whatever the cadences say
`-card-only`	off	With `-card`, write the SVG and nothing else: no sink is needed, none is written to, and the state file is left as it was
`-card-theme`	`auto`	`dark`, `light`, `auto`, or `both`: the light card at `-card` and the dark one beside it with `_dark` before the extension, from one sweep
`-card-motion`	`once`	`once`, `loop` or `off`; `loop` changes only `terminal` and `ticker`
`-card-layout`	`summary`	Which of the thirteen layouts to draw
`-card-fields`	none	Comma-separated fields the card shows, from the fields; empty means the layout’s own default
`-card-width`	the layout’s	Card width in pixels. Each layout draws between two ends of its own, which its section and `-card-layouts` both state; `badge-row` ignores it, its width following its pills
`-card-speed`	`0.5`	How fast an animated layout plays, as a decimal from 0 to 1. `0` is the slowest animation and `1` the fastest; `0.5` is the pace every card has always been drawn at. `0` is not a still card, `-card-motion off` is
`-card-layouts`	off	Print the layouts with the fields and the widths each draws, then exit

The four that print and exit

-version, -groups, -card-layouts and -list answer and stop. The first three need no token and no configuration; -list reads the configuration and asks GitHub which repositories the targets resolve to, which is the cheap way to check a change before spending quota on a sweep.

ghchronicle -version
ghchronicle -groups
ghchronicle -card-layouts
ghchronicle -config config.yaml -list

The three ways to run a sweep

ghchronicle -config config.yaml           # the loop: each family on its cadence
ghchronicle -config config.yaml -once     # one sweep, in the foreground, then exit
ghchronicle -config config.yaml -backfill # the history walk, once

The loop is what a service runs. -once is what a scheduled job runs, and it is also the quickest way to see what a configuration change does. A backfill is a different intention and says so: it walks every surface to the end and waits for a spent budget to refill rather than giving up.

ghchronicle -config config.yaml -backfill -backfill-since 2y

The card, in one line

ghchronicle -config config.yaml -card profile.svg -card-only \
  -card-layout github-stats -card-theme dark

-card-only is the one combination worth remembering: it makes a run that writes no points, so it needs no sink configured and a configuration that would otherwise be refused at start-up is accepted. The card has the layouts and the fields.

-card-width is the one flag that changes what a card says rather than only how it looks, and on one layout only. activity-heatmap spends the room on data: sixteen weeks of the contribution calendar at its near end, twenty-three at the width it declares, and the whole year the collector keeps at its far end, which sits exactly where the year lands so the card is never asked to fill space it has nothing for. Every other layout spreads the same content over whatever width it is given, so widening one of those buys proportions and not information, and its far end is only a guard against a typo. A width outside a layout’s two ends is refused before the sweep runs, naming both, and -card-layouts prints them for every layout.

ghchronicle -config config.yaml -card calendar.svg -card-only \
  -card-layout activity-heatmap -card-width 700

The speed, and what its slow end is not

-card-speed is one number for the whole card. Every animated layout scales together, the continuous motions with the rest: the ticker’s band takes longer to come round and the terminal’s cursor blinks more slowly at the same setting. It is one knob and not one per layout because the motion the card has was paced against itself, one layout’s cycle chosen beside another’s, and a reader who finds the band slow finds the typing slow with it.

0.5 is the middle of the range and is exactly the card this renderer has always drawn, to the byte, so leaving the flag out and asking for 0.5 are the same command, and each end reaches the same distance from it: 0 draws the animation twice as long as the default, 1 half as long as the default.

ghchronicle -config config.yaml -card slow.svg -card-only \
  -card-layout ticker -card-motion loop -card-speed 0.25

Where the rest lives

Everything that is not in that table is a configuration key, not a flag: the file is the map of them.