agnes-the-ai-analyst/docs/HEADLESS_USAGE.md

Headless / CI usage

For unattended clients (CI, cron, Claude Code), authenticate with a Personal Access Token (PAT) rather than an interactive session.

Create a PAT

Via UI: sign in, open /tokens, create a token. Copy the raw value — it is shown exactly once.

Via CLI (requires an interactive session):

agnes auth token create --name "github-actions" --ttl 365d --raw

The --raw flag prints only the token, suitable for piping into a secret store.

Use the PAT

Set the AGNES_TOKEN env var:

export AGNES_TOKEN=<your-token>
agnes query "SELECT 1"

GitHub Actions example

- name: Sync data
  env:
    AGNES_TOKEN: ${{ secrets.AGNES_TOKEN }}
    AGNES_SERVER: https://agnes.example.com
  run: |
    pip install data-analyst
    da sync --all    

Revoke

agnes auth token list
agnes auth token revoke <id|prefix|name>

Or from /tokens → Revoke.