> ## Documentation Index
> Fetch the complete documentation index at: https://docs.svantic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Headless Mode

> Guide to using the Svantic CLI in headless mode for scripting and CI/CD pipelines.

# 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
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

```bash theme={null}
#!/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

```yaml theme={null}
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

```yaml theme={null}
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:

```bash theme={null}
# 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](./environment-and-config) for details.