08CLI

Scripts and CI

A script or a CI job can't approve a sign-in in a browser, so it uses an agent key. The CLI never asks a question when nobody is at a terminal: what it needs comes from options and environment variables.

Make a key

Create it

Open Account → Connected apps and, under Agent keys, choose Create key. Name it after where it will run, such as "GitHub deploys". Leave Make changes for you on if the job marks fixes or adds chart notes; turn it off for a job that only reads.

Store it as a secret

The key starts with snw_agent_ and is shown once. In GitHub, add it as the repository secret SNOWANALYTICS_AGENT_KEY, and the site's ID as the variable SNOWANALYTICS_SITE.

Use it

With SNOWANALYTICS_AGENT_KEY set, every command acts with the key, whatever this computer has saved:

export SNOWANALYTICS_AGENT_KEY=snw_agent_…
export SNOWANALYTICS_SITE=your_site_id
snowanalytics errors --period yesterday

A key acts as your account and reaches every site you can open, so keep it in secrets, never in code. Revoke it in Connected apps and it stops working at once.

Exit codes

CodeMeaning
0It worked.
1It failed, or SnowAnalytics refused it. The reason is printed on stderr.
2The command was wrong: a missing argument, an unknown option, or no site chosen.
3Not signed in, or the key was refused or revoked.

Answers go to stdout and everything else to stderr, so snowanalytics errors | jq always reads clean JSON.

Note each deploy and mark what it fixed

This job runs after your deploy. It writes a note on the chart's day, so a change in the numbers has its reason beside it, and marks the issues the deployed commits fixed. SnowAnalytics then checks production and confirms each fix. See Fix errors with an agent for how the check decides.

A commit says which issue it fixes with a trailer, the last lines of its message:

Retry the payment intent when the cart API times out

Fixes-SnowAnalytics: 7962391455820a08
.github/workflows/deploy.yml
  snowanalytics:
    needs: deploy
    runs-on: ubuntu-latest
    env:
      SNOWANALYTICS_AGENT_KEY: ${{ secrets.SNOWANALYTICS_AGENT_KEY }}
      SNOWANALYTICS_SITE: ${{ vars.SNOWANALYTICS_SITE }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: npm install -g @kapybara/snowanalytics
      - name: Note the deploy on the chart
        run: snowanalytics run notes.create --date "$(date -u +%F)" --body "Deployed ${GITHUB_SHA::7}"
      - name: Mark the issues this deploy fixes
        run: |
          ids=$(git log --format='%(trailers:key=Fixes-SnowAnalytics,valueonly)' \
            "${{ github.event.before }}..${{ github.sha }}" | xargs)
          if [ -n "$ids" ]; then
            snowanalytics fixed $ids --release "$GITHUB_SHA" \
              --link "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/commit/$GITHUB_SHA"
          fi

--release "$GITHUB_SHA" matches the release the SnowAnalytics packages report, which is the commit by default. A site with the script tag and no data-release uses --deployed-at now instead.

Post yesterday's new errors

A morning job that sends what broke yesterday to a Slack channel, through an incoming webhook:

snowanalytics errors --period yesterday --tab new --json \
  | jq -r '.issues[] | "• \(.people) people: \(.message) (\(.page))"' > new-errors.txt

if [ -s new-errors.txt ]; then
  jq -n --rawfile text new-errors.txt '{text: ("New errors yesterday\n" + $text)}' \
    | curl -s -X POST -H 'Content-Type: application/json' -d @- "$SLACK_WEBHOOK_URL"
fi

The fields each command returns are the same as the MCP tools': run a command with --json once to see them.

Let an agent fix errors in CI

The GitHub Actions recipe runs a coding agent on each error ticket. Ask it to end each fix commit with the Fixes-SnowAnalytics trailer, and the deploy job above marks the issue once the fix is live.

On this page