Skip to main content

​
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

VariableDescriptionDefaultRequired
SVANTIC_CLIENT_IDClient ID for mesh authentication(none)Yes (chat modes)
SVANTIC_CLIENT_SECRETClient secret for mesh authentication(none)Yes (chat modes)
SVANTIC_URLSvantic platform URL. The edge routes everything (session init, registration, agent dispatch) to the right internal service.https://api.svantic.comNo
SVANTIC_TOKENJWT token for admin commands(none)Yes (admin)
GOOGLE_API_KEYGoogle 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

FlagDescriptionEnv var override
--svantic-url <url>Svantic platform URLSVANTIC_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 authSVANTIC_CLIENT_ID
--client-secret <sec>Client secret for mesh authSVANTIC_CLIENT_SECRET
--headlessRun in headless mode (no interactive UI)(none)
--message <text>Message to send in headless mode(none)
--verboseShow full tool call/result JSON(none)
--help, -hShow help and exit(none)

​
Configuration File

The CLI reads configuration from ~/.svantic/config.json: 
{
  "svantic_url": "https://api.svantic.com",
  "token": "eyJhbG..."
}
KeyDescription
svantic_urlSvantic platform URL (used by admin commands)
tokenJWT 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: 
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: 
# 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.