Skip to main content

​
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

CodeMeaning
0Stream completed successfully
1Error (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.