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

# Environment and Configuration

> Complete reference for Svantic CLI environment variables, configuration files, and authentication.

# Environment and Configuration

The Svantic CLI resolves configuration from three sources in order of precedence: CLI flags, environment variables, and built-in defaults.

## Precedence

```
CLI flag  >  environment variable  >  config file  >  built-in default
```

A CLI flag always wins. If not provided, the CLI checks the corresponding environment variable, then the config file. If none are set, the built-in default is used.

## Environment Variables

| Variable                | Description                                                                                                                  | Default                   | Required                  |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------- |
| `SVANTIC_CLIENT_ID`     | Client ID for mesh authentication                                                                                            | (none)                    | Yes (chat modes)          |
| `SVANTIC_CLIENT_SECRET` | Client secret for mesh authentication                                                                                        | (none)                    | Yes (chat modes)          |
| `SVANTIC_URL`           | Svantic platform URL. The edge routes everything (session init, registration, agent dispatch) to the right internal service. | `https://api.svantic.com` | No                        |
| `SVANTIC_TOKEN`         | JWT token for admin commands                                                                                                 | (none)                    | Yes (admin)               |
| `GOOGLE_API_KEY`        | Google API key for AI-powered forge generation                                                                               | (none)                    | Only for `forge --prompt` |

Place variables in a `.env` file in the working directory. The CLI loads it automatically.

## CLI Flags

| Flag                    | Description                              | Env var override        |
| ----------------------- | ---------------------------------------- | ----------------------- |
| `--svantic-url <url>`   | Svantic platform URL                     | `SVANTIC_URL`           |
| `--model <name>`        | LLM model name (e.g., `gemini-2.5-pro`)  | (none)                  |
| `--session <id>`        | Reuse an existing session ID             | (none)                  |
| `--client-id <id>`      | Client ID for mesh auth                  | `SVANTIC_CLIENT_ID`     |
| `--client-secret <sec>` | Client secret for mesh auth              | `SVANTIC_CLIENT_SECRET` |
| `--headless`            | Run in headless mode (no interactive UI) | (none)                  |
| `--message <text>`      | Message to send in headless mode         | (none)                  |
| `--verbose`             | Show full tool call/result JSON          | (none)                  |
| `--help`, `-h`          | Show help and exit                       | (none)                  |

## Configuration File

The CLI reads configuration from `~/.svantic/config.json`:

```json theme={null}
{
  "svantic_url": "https://api.svantic.com",
  "token": "eyJhbG..."
}
```

| Key           | Description                                   |
| ------------- | --------------------------------------------- |
| `svantic_url` | Svantic platform URL (used by admin commands) |
| `token`       | JWT token for admin commands                  |

## Authentication

### Chat Commands

Interactive and headless modes require mesh credentials. The auth flow:

1. CLI reads `client_id` and `client_secret` from flags or environment variables.
2. Calls `MeshAuth.get_token()` on the Mesh API, passing credentials.
3. Mesh returns a JWT with tenant context.
4. CLI calls `POST /sessions/init` on the gateway with the JWT.
5. Gateway returns a `session_id` for subsequent messages.

In interactive mode, the terminal also registers as an A2A agent via `MeshConnector.connect()`.

### Admin Commands

Admin commands (`status`, `tenants`, `agents`, `sessions`, `config`) require a JWT token:

```bash theme={null}
export SVANTIC_TOKEN="your-jwt-token"
svantic tenants list
```

Or store it in `~/.svantic/config.json`.

### Token Refresh

If a session expires while idle, the terminal automatically:

1. Re-authenticates to get a fresh JWT.
2. Creates a new session via the gateway.
3. Retries the message transparently.

## Forge Mode

Forge commands (`svantic forge tool`, `svantic forge agent`) run locally and do not require mesh credentials.

The only relevant environment variable is:

* `GOOGLE_API_KEY` — required when using `--prompt` for AI-powered tool generation.

## Setting Up a `.env` File

Create a `.env` file in your working directory:

```bash theme={null}
# Mesh credentials
SVANTIC_CLIENT_ID=your-client-id
SVANTIC_CLIENT_SECRET=your-client-secret

# Svantic platform URL (optional, shown with default)
SVANTIC_URL=https://api.svantic.com

# Admin token (for admin commands)
SVANTIC_TOKEN=your-jwt-token

# AI generation (optional, only for forge --prompt)
GOOGLE_API_KEY=your-google-api-key
```

## Troubleshooting

### "Mesh credentials required"

```
Error: Mesh credentials required.
Set SVANTIC_CLIENT_ID and SVANTIC_CLIENT_SECRET in .env
(or use --client-id / --client-secret).
```

**Fix:** Set both `SVANTIC_CLIENT_ID` and `SVANTIC_CLIENT_SECRET` in your `.env` file or pass them as flags.

### "Auth error: HTTP 401"

```
Auth error: HTTP 401: Invalid client credentials
```

**Fix:** Verify that `SVANTIC_CLIENT_ID` and `SVANTIC_CLIENT_SECRET` are correct. Check that the credentials have not expired or been revoked.

### "Connection error"

```
Connection error: ECONNREFUSED
```

**Fix:** Ensure the Svantic platform is reachable at the URL specified by `SVANTIC_URL` (default: `https://api.svantic.com`). Check network connectivity.

### "Session expired"

The terminal prints `Session expired (reaped); re-initializing...` and retries automatically. If re-initialization fails, check that your credentials are still valid and the gateway is reachable.

### "Could not reach gateway"

```
Could not reach gateway at https://api.svantic.com
```

**Fix:** Verify `SVANTIC_URL` is correct. Check network connectivity. Ensure the Svantic platform is reachable.