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:

{
  "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:

CLI reads client_id and client_secret from flags or environment variables.
Calls MeshAuth.get_token() on the Mesh API, passing credentials.
Mesh returns a JWT with tenant context.
CLI calls POST /sessions/init on the gateway with the JWT.
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:

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:

Re-authenticates to get a fresh JWT.
Creates a new session via the gateway.
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:

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

​Environment and Configuration

​Precedence

​Environment Variables

​CLI Flags

​Configuration File

​Authentication

​Chat Commands

​Admin Commands

​Token Refresh

​Forge Mode

​Setting Up a .env File

​Troubleshooting

​”Mesh credentials required”

​”Auth error: HTTP 401”

​”Connection error”

​”Session expired”

​”Could not reach gateway”