Headless & CI

The CLI is built to run non-interactively, which makes it suitable for CI pipelines, cron jobs, and internal bots in addition to interactive shell use. Headless runs use User API keys (or short-lived credential leases where configured) and emit scriptable output so downstream steps can gate merges, post comments, or open follow-up tasks.

How CI handoff works

Typical flow:

CI job → 4rged agent run → run ID → poll until complete → artifact / PR URL → pass/fail job

Authentication in CI

1. Create a User API key

   An org admin creates a key from Dashboard → Integrations → User API Keys. If keys are disabled, enable Allow personal API keys in Settings or use a dedicated service account when your org supports them.

2. Store as a CI secret

   Add X4RGE_API_KEY to your provider's encrypted secret store (GitHub Actions secrets, GitLab CI variables, etc.). Never echo the key in logs.

3. Verify in a bootstrap step

   4rged whoami --output json

   Confirms org context before starting expensive agent runs.

GitHub Actions example

Pin the CLI version, authenticate with X4RGE_API_KEY, run against a project, and fail the job on agent error:

name: 4RGE agent review
 
on:
  pull_request:
    types: [opened, synchronize]
 
jobs:
  agent-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    env:
      X4RGE_API_KEY: ${{ secrets.X4RGE_API_KEY }}
      X4RGE_CLI_VERSION: "1.2.0"  # pin — match your org's approved version
    steps:
      - uses: actions/checkout@v4
 
      - name: Install 4RGE CLI
        run: curl -fsSL https://4rged.ai/cli/install | sh -s -- --version "$X4RGE_CLI_VERSION"
 
      - name: Verify auth
        run: 4rged whoami --output json
 
      - name: Run agent
        id: agent
        run: |
          4rged agent run \
            --project acme-web \
            --prompt "Review this PR for security regressions in auth middleware" \
            --output json > agent-result.json
          echo "run_id=$(jq -r '.run_id' agent-result.json)" >> "$GITHUB_OUTPUT"
 
      - name: Wait for completion
        run: 4rged agent wait --run "${{ steps.agent.outputs.run_id }}" --timeout 30m
 
      - name: Upload summary
        uses: actions/upload-artifact@v4
        with:
          name: x4rge-agent-summary
          path: agent-result.json

Adapt --cloud and --task flags when linking output to project tasks.

GitLab CI example

x4rge-doc-sync:
  image: ubuntu:22.04
  variables:
    X4RGE_CLI_VERSION: "1.2.0"
  script:
    - apt-get update && apt-get install -y curl jq git
    - curl -fsSL https://4rged.ai/cli/install | sh -s -- --version "$X4RGE_CLI_VERSION"
    - 4rged whoami
    - |
      4rged agent run \
        --cloud \
        --project platform-docs \
        --prompt "Update API reference from OpenAPI spec at ./openapi.yaml" \
        --output json | tee run.json
    - 4rged agent wait --run "$(jq -r '.run_id' run.json)" --timeout 45m
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"

Governance still applies

Runs started from the CLI respect the same controls as desktop and cloud:

Check Dashboard → Usage for policy denials if CI jobs fail with opaque policy errors — denial events include remediation hints (allowed model group, missing repo link, etc.).

Environment variables for headless runs

The install script reads X4RGE_CLI_VERSION to select the tarball from the release base URL. Set it in your CI job env block before the install step so pipelines do not pick up an unexpected latest build.

Pinned installs in CI

Both the bash and PowerShell installers honor X4RGE_CLI_VERSION. In GitHub Actions, export the variable in env and pass it to the install step. After install, run 4rged whoami --output json as a gate before any agent work — this confirms org context and catches expired or revoked keys before a long --cloud run starts.

Operational checklist for admins

1. Approve CLI surface defaults

   In model control, set a cost-predictable default model for CLI (often the same as desktop).

2. Set org budget enforcement

   Use warn for internal experimentation; soft stop or hard stop for production CI that could burn on-demand capacity. See Usage & billing.

3. Link repos to projects

   Ensure CI repositories are linked on the project so hosted and CLI runs pass repo policy.

4. Rotate keys quarterly

   Revoke unused API keys from Integrations; re-issue CI secrets after rotation.