Headless Mode

Headless mode sends a single message to the Svantic mesh, streams the response to stdout, and exits. No interactive UI is rendered. This mode is designed for shell scripts, CI/CD pipelines, and programmatic invocation.

Running a Headless Command

Pass --headless with a message:

svantic --headless "summarize the latest deployment logs"
svantic --headless --message "run the test suite on staging"

The terminal authenticates, initializes a session, sends the message via A2A streaming, and prints the response text to stdout. Diagnostics go to stderr.

Exit Codes

Code	Meaning
0	Stream completed successfully
1	Error (auth failure, network error, stream error, or API error)

Check the exit code in scripts:

svantic --headless "deploy to staging"
if [ $? -ne 0 ]; then
  echo "Deployment failed" >&2
  exit 1
fi

Output Streams

Response text goes to stdout, diagnostics go to stderr:

# Capture only the response
svantic --headless "list open tickets" > tickets.txt

# Pipe to another command
svantic --headless "generate a CSV of all users" | csvlook

# Capture both streams
svantic --headless "analyze logs" > result.txt 2> debug.txt

Verbose Mode

Add --verbose to see tool calls, results, and thinking on stderr:

svantic --headless --verbose "check server health"

Verbose output on stderr:

[thinking] Checking health endpoints...
[tool] orchestrator -> health_check({"service": "api"})
[result] orchestrator -> health_check: {"status": "healthy", "uptime": 84200}

Response text on stdout:

The API server is healthy with 23.4 hours of uptime.

Shell Script Example

#!/bin/bash
set -euo pipefail

export SVANTIC_CLIENT_ID="$CI_CLIENT_ID"
export SVANTIC_CLIENT_SECRET="$CI_CLIENT_SECRET"

RESULT=$(svantic --headless "run smoke tests on staging and report pass/fail")

if echo "$RESULT" | grep -q "PASS"; then
  echo "Smoke tests passed"
  exit 0
else
  echo "Smoke tests failed:"
  echo "$RESULT"
  exit 1
fi

CI/CD Integration

GitHub Actions

name: AI-Assisted Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Svantic CLI
        run: npm install -g @svantic/cli

      - name: Run pre-deploy checks
        env:
          SVANTIC_CLIENT_ID: ${{ secrets.SVANTIC_CLIENT_ID }}
          SVANTIC_CLIENT_SECRET: ${{ secrets.SVANTIC_CLIENT_SECRET }}
          SVANTIC_URL: ${{ secrets.SVANTIC_URL }}
        run: |
          svantic --headless "run pre-deploy validation for commit ${{ github.sha }}"

      - name: Deploy to staging
        env:
          SVANTIC_CLIENT_ID: ${{ secrets.SVANTIC_CLIENT_ID }}
          SVANTIC_CLIENT_SECRET: ${{ secrets.SVANTIC_CLIENT_SECRET }}
        run: |
          svantic --headless "deploy ${{ github.sha }} to staging and run smoke tests"

GitLab CI

deploy:
  stage: deploy
  image: node:20
  script:
    - npm install -g @svantic/cli
    - svantic --headless "deploy $CI_COMMIT_SHA to staging"
  variables:
    SVANTIC_CLIENT_ID: $SVANTIC_CLIENT_ID
    SVANTIC_CLIENT_SECRET: $SVANTIC_CLIENT_SECRET

Combining with Flags

Override the model or Svantic URL per invocation:

# Use a specific model
svantic --headless --model gemini-2.5-pro "analyze this error log"

# Point to a self-hosted Svantic edge
svantic --headless --svantic-url https://svantic.example.com "check mesh health"

# Reuse an existing session for multi-step workflows
SESSION=$(svantic --headless "start a new analysis" 2>/dev/null | grep -oP 'sess-\w+')
svantic --headless --session "$SESSION" "now correlate with yesterday's data"

Authentication Errors

If credentials are missing or invalid, the terminal exits with code 1:

Auth error: HTTP 401: Invalid client credentials

Ensure SVANTIC_CLIENT_ID and SVANTIC_CLIENT_SECRET are set. See Environment and Config for details.

​Headless Mode

​Running a Headless Command

​Exit Codes

​Output Streams

​Verbose Mode

​Shell Script Example

​CI/CD Integration

​GitHub Actions

​GitLab CI

​Combining with Flags

​Authentication Errors