CLI Reference

Complete reference for every svantic command, organized by category.

Quick Start

Install the Svantic CLI globally:

npm install -g @svantic/cli

Check the installed version:

svantic --version

Display help for any command:

svantic --help
svantic <command> --help

Command Summary

Chat

Command	Description
`svantic`	Start an interactive chat session with AI agents
`svantic chat`	Explicit chat command (same as default)

Forge

Command	Description
`svantic forge tool`	Generate tool specs from OpenAPI, source code, or natural language
`svantic forge agent`	Scaffold a complete agent service from tool specs

Admin

Command	Description
`svantic status`	Show platform health and connectivity
`svantic tenants list`	List all tenants
`svantic tenants get`	Get details for a specific tenant
`svantic agents list`	List registered agents
`svantic sessions list`	List recent sessions
`svantic config show`	Display current CLI configuration

Chat Commands

svantic (default)

Start an interactive chat session with AI agents on the Svantic mesh. This is the default action when no command is specified.

svantic [message] [options]

Argument	Description
`message`	Optional message to send (for headless mode)

Option	Description
`--svantic-url <url>`	Svantic platform URL (default: `https://api.svantic.com`, or `SVANTIC_URL`)
`--model <name>`	LLM model name (e.g., `gemini-2.5-flash`, `gemini-2.5-pro`)
`--session <id>`	Reuse an existing session ID
`--client-id <id>`	Client ID for authentication (or `SVANTIC_CLIENT_ID`)
`--client-secret <sec>`	Client secret for authentication (or `SVANTIC_CLIENT_SECRET`)
`--headless`	Send a single message and exit (no interactive UI)
`--message <text>`	Message to send (alternative to positional arg)
`--verbose`	Show full tool call/result JSON

Interactive mode (default):

svantic
svantic --model gemini-2.5-pro
svantic --verbose

Headless mode (for scripting):

svantic --headless "summarize the latest deployment logs"
svantic --headless --message "run smoke tests on staging"

Session reuse:

svantic --session sess-abc123

svantic chat

Explicit chat command. Identical to running svantic with no command.

svantic chat [message] [options]

All options are the same as the default command above.

svantic chat
svantic chat --headless "check server health"
svantic chat --model gemini-2.5-pro --verbose

Forge Commands

AI-powered tool and agent generation. Forge commands run locally and do not require mesh credentials.

svantic forge tool

Generate tool specifications from OpenAPI specs, TypeScript source files, or natural language prompts.

svantic forge tool [options]

Option	Description
`--spec <file>`	OpenAPI v3 spec (YAML/JSON) or existing Tool Spec YAML
`--list <file>`	List all operations in the spec (no generation)
`--prompt <text>`	AI-powered generation from natural language
`--docs <url>`	Documentation URL for context (use with `--prompt`)
`--pick <names>`	Comma-separated path prefixes or function names to include
`--domain <name>`	Override domain name (default: derived from spec title)
`--out <dir>`	Output directory (default: current directory)

From OpenAPI spec:

svantic forge tool --spec openapi.yaml
svantic forge tool --spec openapi.yaml --pick /tickets,/contacts
svantic forge tool --list openapi.yaml

From natural language (requires GOOGLE_API_KEY):

svantic forge tool --prompt "Zendesk: list, create, update tickets"
svantic forge tool --prompt "Stripe: charges, refunds" --docs https://stripe.com/docs/api

svantic forge agent

Scaffold a complete agent service from one or more tool specs.

svantic forge agent [options]

Option	Description
`--name <name>`	Agent service name (required)
`--spec <file>`	Tool Spec YAML or OpenAPI spec file
`--tools <files>`	Comma-separated spec files for multi-domain compose
`--standalone`	Generate full project scaffolding (`package.json`, `Dockerfile`, `tsconfig.json`)
`--description <text>`	Agent description override
`--port <number>`	Port override (default: 9100)
`--out <dir>`	Output directory (default: `./<name>/`)

Single spec:

svantic forge agent --name zendesk-agent --spec zendesk.yaml
svantic forge agent --name zendesk-agent --spec zendesk.yaml --standalone

Multiple specs (compose):

svantic forge agent --name support-agent --tools zendesk.yaml,hubspot.yaml --standalone

With options:

svantic forge agent --name billing-agent --spec stripe.yaml \
  --description "Handles payment processing" \
  --port 9200 --standalone

Admin Commands

Platform administration commands. Require a valid JWT token (SVANTIC_TOKEN) or super-admin credentials.

svantic status

Show platform health and connectivity status.

svantic status

Displays:

Platform edge health status
Mesh connection status
Service version
Uptime

svantic status

svantic tenants list

List all tenants on the platform.

svantic tenants list

Displays a table with:

Tenant ID
Name
Status
Created date

svantic tenants list

svantic tenants get

Get detailed information about a specific tenant.

svantic tenants get <tenant_id>

Argument	Description
`tenant_id`	The tenant ID to retrieve

svantic tenants get acme-corp
svantic tenants get svantic

svantic agents list

List all registered agents.

svantic agents list

Displays a table with:

Agent ID
Agent Type
Name
Status
Tenant ID

svantic agents list

svantic sessions list

List recent sessions.

svantic sessions list

Displays a table with:

Session ID
Tenant ID
Agent Type
Status
Created date
Message count

svantic sessions list

svantic config show

Display the current CLI configuration.

svantic config show

Shows:

Svantic platform URL
Token status (set/not set, masked)
Config file location and status

svantic config show

Exit Codes

Code	Meaning
`0`	Success
`1`	Failure — invalid arguments, command error, authentication failure, or network error

Environment Variables

Variable	Description	Default
`SVANTIC_CLIENT_ID`	Client ID for mesh authentication	(none)
`SVANTIC_CLIENT_SECRET`	Client secret for mesh authentication	(none)
`SVANTIC_URL`	Svantic platform URL	`https://api.svantic.com`
`SVANTIC_TOKEN`	JWT token for admin commands	(none)
`GOOGLE_API_KEY`	Google API key for AI-powered forge generation	(none)

Variables can be set in a .env file in the working directory or in ~/.svantic/config.json.

Configuration File

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

{
  "svantic_url": "https://api.svantic.com",
  "token": "eyJhbG..."
}

Precedence: CLI flag > environment variable > config file > built-in default

Authentication

Chat commands

Chat commands (interactive and headless) require client credentials:

export SVANTIC_CLIENT_ID="your-client-id"
export SVANTIC_CLIENT_SECRET="your-client-secret"
svantic

Or via flags:

svantic --client-id my_id --client-secret my_secret

Admin commands

Admin commands require a JWT token:

export SVANTIC_TOKEN="your-jwt-token"
svantic tenants list

The token can also be stored in ~/.svantic/config.json.

Interactive Mode Features

When running in interactive mode, the terminal provides:

Slash Commands

Command	Description
`/help`	Show all available commands
`/clear`	Clear conversation history
`/verbose`	Toggle verbose mode
`/session`	Show current session ID
`/load`	Load a previous session
`/attach`	Attach file to next message
`/upload`	Upload a file as an artifact
`/mcp`	Manage MCP servers
`/approvals`	List tool approvals
`/routes`	Show active instance routes
`/reset`	Start a new session
`/quit`	Exit the terminal

Tool Approvals

When an agent requests to execute a sensitive tool, you’ll be prompted to:

Approve — allow this single invocation
Approve for session — allow all future calls in this session
Approve permanently — allow across all sessions
Deny — reject the invocation

File Attachments

Attach files using /attach <path> or type @ to open a file picker.

Headless Mode

Headless mode is designed for scripting and CI/CD pipelines.

Output Streams

stdout — response text only
stderr — diagnostics (tool calls, thinking, errors)

# 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

CI/CD Example (GitHub Actions)

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 }}
        run: |
          svantic --headless "run pre-deploy validation for commit ${{ github.sha }}"

Examples

Interactive chat session

export SVANTIC_CLIENT_ID=default
export SVANTIC_CLIENT_SECRET=change-me-in-production
svantic --model gemini-2.5-pro

> List all open support tickets and summarize the top issues.

[tool] orchestrator -> zendesk_list_tickets({"status": "open"})
[result] 23 tickets found

There are 23 open tickets. The top three issues are:
1. Login failures after password reset (8 tickets)
2. Slow dashboard loading (6 tickets)
3. Missing invoice downloads (4 tickets)

Generate and scaffold an agent

# Generate tools from OpenAPI
svantic forge tool --spec ./specs/zendesk-openapi.yaml --pick /tickets

# Scaffold the agent
svantic forge agent --name zendesk-agent --spec zendesk.yaml --standalone

# Run the agent
cd zendesk-agent
npm install
cp .env.example .env
npx tsx server.ts

Check platform health

export SVANTIC_TOKEN="your-admin-jwt"
svantic status
svantic tenants list
svantic agents list

CLI Reference

Documentation Index

​CLI Reference

​Quick Start

​Command Summary

​Chat

​Forge

​Admin

​Chat Commands

​svantic (default)

​svantic chat

​Forge Commands

​svantic forge tool

​svantic forge agent

​Admin Commands

​svantic status

​svantic tenants list

​svantic tenants get

​svantic agents list

​svantic sessions list

​svantic config show

​Exit Codes

​Environment Variables

​Configuration File

​Authentication

​Chat commands

​Admin commands

​Interactive Mode Features

​Slash Commands

​Tool Approvals

​File Attachments

​Headless Mode

​Output Streams

​CI/CD Example (GitHub Actions)

​Examples

​Interactive chat session

​Generate and scaffold an agent

​Check platform health

CLI Reference

Quick Start

Command Summary

Chat

Forge

Admin

Chat Commands

svantic (default)

svantic chat

Forge Commands

svantic forge tool

svantic forge agent

Admin Commands

svantic status

svantic tenants list

svantic tenants get

svantic agents list

svantic sessions list

svantic config show

Exit Codes

Environment Variables

Configuration File

Authentication

Chat commands

Admin commands

Interactive Mode Features

Slash Commands

Tool Approvals

File Attachments

Headless Mode

Output Streams

CI/CD Example (GitHub Actions)

Examples

Interactive chat session

Generate and scaffold an agent

Check platform health