---
title: Configuration
description: All SDK configuration options, environment variables, and CLI commands.
---

# Configuration

## SDK Configuration

Everything goes through `st.init()`.

### Minimal

```python
st.init(api_key="ak_...", agent_id="my-agent")
```

### All Options

```python
st.init(
    api_key="ak_...",                  # required -- your Staso API key
    agent_id="my-agent",               # required -- name for this agent
    base_url="https://api.staso.ai",   # Staso backend URL
    environment="staging",             # tag traces by environment
    workspace_slug="my-workspace",     # workspace identifier
    batch_size=100,                    # spans buffered before sending
    flush_interval=5.0,                # max seconds between sends
    max_queue_size=10_000,             # max buffered spans
    enabled=True,                      # False to disable without removing code
    debug=False,                       # SDK debug logs on `staso` logger
    capture_messages=True,             # capture LLM message content in integrations
)
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `api_key` | `str` | *required* | Your Staso API key |
| `agent_id` | `str` | *required* | Agent name shown on dashboard |
| `base_url` | `str` | `"https://api.staso.ai"` | Backend URL |
| `environment` | `str` | `"default"` | Environment tag (`"staging"`, `"production"`) |
| `workspace_slug` | `str` | `"default"` | Workspace identifier |
| `batch_size` | `int` | `100` | Flush after this many spans |
| `flush_interval` | `float` | `5.0` | Flush after this many seconds |
| `max_queue_size` | `int` | `10_000` | Drops new spans when full |
| `enabled` | `bool` | `True` | Kill switch -- decorators stay, no data sent |
| `debug` | `bool` | `False` | Debug logging on `staso` logger |
| `capture_messages` | `bool` | `True` | Include LLM message content in integration spans. Set to `False` for sensitive data. |


### Environment Variables

The SDK reads these automatically. Arguments passed to `st.init()` take priority.

| Variable | Maps to |
|----------|---------|
| `STASO_API_KEY` | `api_key` |
| `STASO_AGENT_ID` | `agent_id` |
| `STASO_BASE_URL` | `base_url` |
| `STASO_ENVIRONMENT` | `environment` |
| `STASO_WORKSPACE_SLUG` | `workspace_slug` |
| `STASO_DEBUG` | `debug` (`"1"` or `"true"` to enable) |

```python
# Everything from env vars
st.init()

# Override specific values
st.init(environment="staging")
```

### Disabling

Keep all decorators in your code, send nothing:

```python
st.init(api_key="ak_...", agent_id="my-agent", enabled=False)
```

### Shutdown

Always call before exit:

```python
st.shutdown()
```

An `atexit` hook runs as a fallback, but explicit is better.

## CLI Commands

### Interactive Setup

Run `staso setup` with no flags:

```bash
staso setup
```

The wizard guides you through selecting an agent, entering your API key, and configuring optional settings. Arrow-key navigation, input validation, sensible defaults.

### All Commands

| Command | Description |
|---------|-------------|
| `staso setup` | Interactive setup wizard (when no `--api-key` provided) |
| `staso setup --target <agent> --api-key ak_...` | Scripted setup with flags |
| `staso status [--target <agent>]` | Show current hook configuration |
| `staso sync [--target <agent>]` | Sync hooks after upgrading (add missing events, fix Python path) |
| `staso update` | Upgrade staso package via pip and sync hooks automatically |
| `staso uninstall [--target <agent>]` | Remove all Staso hooks and clean up state files |
| `staso version` | Show version and check for updates |

Agents: `claude-code`, `codex`

### Setup Flags

| Flag | Default | Description |
|------|---------|-------------|
| `--target` | `claude-code` | Which agent to configure |
| `--api-key KEY` | *required* | Staso API key (`ak_...`). Falls back to `STASO_API_KEY` env var |
| `--base-url URL` | `https://api.staso.ai` | Backend URL |
| `--workspace SLUG` | `default` | Workspace identifier |
| `--environment ENV` | `default` | Environment tag |
| `--agent-id ID` | | Agent ID shown on dashboard |
| `--scope` | `global` | `global` (all sessions) or `project` (current directory only) |
| `--auto-sync` | | Auto-sync hook config on each session start |

### Sync Flags

| Flag | Description |
|------|-------------|
| `--target <agent>` | Sync a specific agent (default: all configured) |
| `--enable-auto-sync` | Enable auto-sync on each session start |
| `--disable-auto-sync` | Disable auto-sync |
