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

# CLI Reference

> Complete command reference for the Svantic CLI, covering interactive chat, headless mode, forge generation, and platform administration.

# CLI Reference

Complete reference for every `svantic` command, organized by category.

***

## Quick Start

Install the Svantic CLI globally:

```bash theme={null}
npm install -g @svantic/cli
```

Check the installed version:

```bash theme={null}
svantic --version
```

Display help for any command:

```bash theme={null}
svantic --help
svantic <command> --help
```

***

## Command Summary

### Chat

| Command                         | Description                                      |
| ------------------------------- | ------------------------------------------------ |
| [`svantic`](#svantic-default)   | Start an interactive chat session with AI agents |
| [`svantic chat`](#svantic-chat) | Explicit chat command (same as default)          |

### Forge

| Command                                       | Description                                                        |
| --------------------------------------------- | ------------------------------------------------------------------ |
| [`svantic forge tool`](#svantic-forge-tool)   | Generate tool specs from OpenAPI, source code, or natural language |
| [`svantic forge agent`](#svantic-forge-agent) | Scaffold a complete agent service from tool specs                  |

### Admin

| Command                                           | Description                           |
| ------------------------------------------------- | ------------------------------------- |
| [`svantic status`](#svantic-status)               | Show platform health and connectivity |
| [`svantic tenants list`](#svantic-tenants-list)   | List all tenants                      |
| [`svantic tenants get`](#svantic-tenants-get)     | Get details for a specific tenant     |
| [`svantic agents list`](#svantic-agents-list)     | List registered agents                |
| [`svantic sessions list`](#svantic-sessions-list) | List recent sessions                  |
| [`svantic config show`](#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):

```bash theme={null}
svantic
svantic --model gemini-2.5-pro
svantic --verbose
```

**Headless mode** (for scripting):

```bash theme={null}
svantic --headless "summarize the latest deployment logs"
svantic --headless --message "run smoke tests on staging"
```

**Session reuse**:

```bash theme={null}
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.

```bash theme={null}
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**:

```bash theme={null}
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`):

```bash theme={null}
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**:

```bash theme={null}
svantic forge agent --name zendesk-agent --spec zendesk.yaml
svantic forge agent --name zendesk-agent --spec zendesk.yaml --standalone
```

**Multiple specs (compose)**:

```bash theme={null}
svantic forge agent --name support-agent --tools zendesk.yaml,hubspot.yaml --standalone
```

**With options**:

```bash theme={null}
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

```bash theme={null}
svantic status
```

***

### svantic tenants list

List all tenants on the platform.

```
svantic tenants list
```

Displays a table with:

* Tenant ID
* Name
* Status
* Created date

```bash theme={null}
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 |

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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`:

```json theme={null}
{
  "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:

```bash theme={null}
export SVANTIC_CLIENT_ID="your-client-id"
export SVANTIC_CLIENT_SECRET="your-client-secret"
svantic
```

Or via flags:

```bash theme={null}
svantic --client-id my_id --client-secret my_secret
```

### Admin commands

Admin commands require a JWT token:

```bash theme={null}
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)

```bash theme={null}
# 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)

```yaml theme={null}
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

```bash theme={null}
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

```bash theme={null}
# 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

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