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 yesterdayA 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
| Code | Meaning |
|---|---|
0 | It worked. |
1 | It failed, or SnowAnalytics refused it. The reason is printed on stderr. |
2 | The command was wrong: a missing argument, an unknown option, or no site chosen. |
3 | Not 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 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"
fiThe 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.