# Quickstart

Install ghchronicle, point it at a database and run a first sweep of a GitHub account, and what that first sweep does that later ones do not.

Source: https://docs.jmrp.io/ghchronicle/start/quickstart/

Six steps and a configuration file. The only decision worth thinking about
before you start is which store keeps the history, and you can defer that by
printing the points to the terminal first.

## The short way

If you have a terminal, let it ask:

```sh
ghchronicle -setup
```

It asks for a token, checks with GitHub who the token is, asks which account to
collect and where to put the numbers, checks that the place answers, offers the
dashboard and offers to set it up to run by itself. What it writes is a
`config.yaml` that loads and, when you asked for a service, a unit, an agent or
a scheduled task for whichever system this is.

Credentials never go in the configuration. They go in a file beside it that
only you can read, and the configuration refers to them by name.

The installer above offers to run it as its last step, so on a new machine the
two together are the whole of getting started.

The rest of this page is what it writes, for a reader who would rather write it
themselves or wants to know what they just agreed to.

## Zero to a first sweep

1. **Install the binary.**

    - **Script**

      ```sh
      curl -fsSL https://raw.githubusercontent.com/jmrplens/ghchronicle/main/install.sh | bash
      ```

      On Windows, in PowerShell:

      ```powershell
      irm https://raw.githubusercontent.com/jmrplens/ghchronicle/main/install.ps1 | iex
      ```

    - **Release**

      Take the archive for your platform from the [releases
      page](https://github.com/jmrplens/ghchronicle/releases) and put
      `ghchronicle` on your `PATH`.

    - **Container**

      ```sh
      docker pull ghcr.io/jmrplens/ghchronicle
      ```

    - **Go**

      ```sh
      go install github.com/jmrplens/ghchronicle/v2/cmd/ghchronicle@latest
      ```

2. **Create a token** at `https://github.com/settings/tokens` and export it.

    ```sh
    export GITHUB_TOKEN=github_pat_...
    ```

    A classic token with `repo`, `read:packages`, `read:user`, `read:org`,
    `security_events`, `read:public_key` and `read:gpg_key` sees everything this
    collects. The
    [token page](https://docs.jmrp.io/ghchronicle/start/token/) explains which scope buys which
    family, and why the automatic `GITHUB_TOKEN` of an Action is not enough.

3. **Write the configuration.** Two decisions, and this is the whole file:

    ```yaml
    # config.yaml
    github:
      token: ${GITHUB_TOKEN}
    targets:
      user: your-login
    sinks:
      stdout: true # swap for influxdb once you have somewhere to put it
    ```

    A `${VAR}` in a credential, an address or a file path is read from the
    environment at start-up, so the file itself holds no secrets and can be
    committed. Everything else has a default.

    The documented version, which comments every option there is, lives in the
    repository rather than in the install, so take it from there when you want
    to read the rest:

    ```sh
    curl -O https://raw.githubusercontent.com/jmrplens/ghchronicle/main/config.example.yaml
    ```

4. **See what would be collected**, before spending any quota on it.

    ```sh
    ghchronicle -config config.yaml -list
    ```

    That prints the repositories in scope. Forks and archived repositories are
    excluded by default. If something you expected is missing, this is the
    command that tells you.

5. **Run one sweep.**

    ```sh
    ghchronicle -config config.yaml -once
    ```

    With `sinks.stdout: true` the points go to the terminal as line protocol
    instead of to a database, which is the cheapest way to see the shape of what
    you are about to store.

6. **Leave it running.**

    ```sh
    ghchronicle -config config.yaml
    ```

    Each family then runs on its own cadence: workflow runs every fifteen
    minutes, the contribution calendar every hour, the account's SSH and GPG
    keys once a day.

## What the first sweep does that later ones do not

Four things happen once, and they are why the first run is the expensive one.

- The daily star history of every repository, whatever the token may see, is
  read back to the repository's first week, and the whole stargazer list of
  every repository whose list the token may read (since July 2026, only a
  repository's
  [admins and collaborators](https://docs.github.com/en/rest/activity/starring#new-access-restrictions))
  is walked, page by page, so each of those stars carries the moment it was
  given and who gave it. After that, the history is one request per repository
  for its newest thirty weeks, usually a free 304, and the newest hundred stars
  of each readable list ride in one GraphQL query per ten repositories.
- A month of workflow runs, so a fresh install does not chart a CI history that
  begins fifteen minutes ago. After that, twice the cadence, and never less
  than two hours.
- The co-authored pull requests of the account's whole life, which
  `achievements` walks for the Pair Extraordinaire count: 35 queries and
  23.7 MB over 2,315 merged pull requests, measured on 2026-09-27. After that a
  pass walks the days since, one page, and the whole history again once a
  week.
- Every year's contribution calendar, if `every.families.history` is set, back
  to the day the account was created. After that, only the year in progress,
  rewritten at its cadence.

Nothing is cached yet either, so every answer of the first sweep is paid in
full, where a later one asks with the ETag the last answer came with and is
mostly answered a free 304; see [the cache beside the state
file](https://docs.jmrp.io/ghchronicle/configuration/#the-cache-beside-it).

Expect a few thousand points from a first sweep of twenty repositories, and a
few hundred from each one after.

None of that is the history. The first sweep is a wider increment, and a
dashboard at ninety days or two years then begins on the day you installed the
collector: measured after a day of sweeps, about a fifth of the pull requests
the repositories report, commits from the last thirty days only, and jobs for
a tenth of the workflow runs. Run `ghchronicle -config config.yaml -backfill`
once, before the service or right after it;
[the backfill page](https://docs.jmrp.io/ghchronicle/how/backfill/) says what it reaches and what
it costs.

> **Keep the state file**
>
> `state_file` is what remembers where each family got to, and
> [nine things live in it](https://docs.jmrp.io/ghchronicle/configuration/#state_file). Delete it
> and the next sweep re-collects everything, which costs quota and nothing else
> for seven of the nine. The other two are the commit each dependency diff
> starts from, whose changes in the gap are not collected again, and what the
> file records of each store, a refill a migration still owes among it, which
> nothing then reads back.

## Where to go next

- [Ways to install](https://docs.jmrp.io/ghchronicle/install/) is what turns the command above into
  something that keeps running: systemd, Docker or a scheduled Action.
- [Dating a point](https://docs.jmrp.io/ghchronicle/how/dating/) is the design idea everything else
  follows from.
- [Choosing a store](https://docs.jmrp.io/ghchronicle/sinks/) decides which questions you will be
  able to ask later.
- [Cost of a sweep](https://docs.jmrp.io/ghchronicle/api/cost/) is the measured price in API calls.