# The command line The flags, what each one does, and which of them print something and exit. Source: https://jmrplens.github.io/ghchronicle/reference/cli/ The binary takes these flags and no subcommands. Everything else is in the configuration file, because a schedule is not something to retype. ```sh 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](/ghchronicle/card/layouts/) to draw | | `-card-fields` | none | Comma-separated fields the card shows, from [the fields](/ghchronicle/card/#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](/ghchronicle/card/layouts/) 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. ```sh ghchronicle -version ghchronicle -groups ghchronicle -card-layouts ghchronicle -config config.yaml -list ``` ## The three ways to run a sweep ```sh 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](/ghchronicle/how/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. ```sh ghchronicle -config config.yaml -backfill -backfill-since 2y ``` ## The card, in one line ```sh 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](/ghchronicle/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`](/ghchronicle/card/layouts/#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. ```sh 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. > **0 is the slowest animation, not none** > > A range that starts at zero reads like a switch, and this one is not. At `0` > the card still animates, as slowly as this renderer will draw it. What draws > a card with no animation at all is `-card-motion off`. ```sh 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](/ghchronicle/configuration/) is the map of them.