CI Usage

The rules for scripts

1. Pass --json. Every client command prints raw JSON with it; doctor --json prints only the summary object.
2. Branch on exit codes, not text. 0 success, 2 policy refusal, 3 authentication, 4 conflict, 5 not found, 6 timeout, 7 protocol mismatch — the full table is on Troubleshooting.
3. Provide credentials through the environment. VAGARIS_API_URL, VAGARIS_API_KEY and VAGARIS_COMPANY_ID (legacy PAPERCLIP_*) replace --api-base, --api-key and --company-id. An explicit API key also disables the interactive login recovery, so nothing tries to open a browser.
4. Nothing prompts. When stdin or stdout is not a terminal the CLI does not prompt: doctor --repair needs --yes, vagaris uninstall needs --force, agent local-cli --install-skills needs --yes, and run will not onboard — run vagaris onboard --yes first.
5. Telemetry is off in CI automatically; set VAGARIS_TELEMETRY_DISABLED=1 if your runner is not detected as CI.

A GitHub Actions job

This mirrors the smoke matrix the project runs against each published version:

jobs:
  vagaris-smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g @vagarylabs/vagaris
      - run: vagaris --version
      - run: vagaris --help
      - run: vagaris doctor --json || true
      - run: vagaris version --json

doctor --json on a bare runner fails its first check (no config), which is why the step tolerates it; add vagaris onboard --yes before it to exercise a real instance.

Driving a company from a pipeline

export VAGARIS_API_URL=https://vagaris.example.com
export VAGARIS_API_KEY="$AGENT_API_KEY"
export VAGARIS_COMPANY_ID=<company-id>

vagaris issue create --title "Nightly dependency review" --json
vagaris heartbeat run --agent-id <agent-id> --timeout-ms 900000 --json
vagaris approval list --status pending --json

heartbeat run --timeout-ms bounds the wait; the default 0 waits until the run reaches a terminal status.

Pipe-friendly patterns:

vagaris issue list --status todo --json | jq -r '.[].identifier'
vagaris runctl history --json | jq '.[0]'

Governed work in CI

A CI runner can host a run like a developer laptop. Enrol the runner once (Node Enrolment), keep its ~/.vagris/node-identity.json in the runner's persistent home, and claim with --node-id:

vagaris dev --agent-id <agent-id> --run-id <run-id> --node-id <node-id> --json

The report is JSON; spawn.exitCode and closureGate are the fields to gate on. Use --no-spawn in a pre-flight step to confirm the claim would be allowed before spending runner time.

Backups from a schedule

vagaris db:backup --dir /backups --retention-days 30 --json

Version pinning

vagaris update --to <version> and vagaris rollback --to <version> pin an exact version; vagaris version --json tells you whether the runner is behind. A PROTOCOL_MISMATCH (exit 7) from any command means the server moved ahead — update the CLI in the runner image.