Configuration

The CLI uses a layered configuration system with multiple sources. Higher priority sources override lower ones.

Configuration Priority

Environment variables (highest) - VSB_API_KEY, VSB_BASE_URL, VSB_STRATEGY
Config file (lowest) - ~/.config/vsb/config.yaml

Interactive Setup

Run the configuration wizard to set up credentials interactively:

vsb config

This prompts for your API key and gateway URL, then saves them to the config file.

Manual Configuration

Set Individual Values

# Set API key
vsb config set api-key "your-api-key"

# Set gateway URL
vsb config set base-url "https://your-gateway.vsx.email"

# Set delivery strategy (sse or polling)
vsb config set strategy sse

Running vsb config set strategy without a value opens an interactive selector.

View Current Configuration

vsb config show

The API key is masked in the output for security. When connected to a server, this also displays server capabilities including spam analysis status and allowed domains.

Example output:

api-key: vsb_*****
base-url: https://your-gateway.vsx.email
strategy: sse

Server capabilities:
  spam-analysis: enabled
  domains: example.com, test.com

JSON output includes a server object with capability details:

vsb config show -o json

{
  "apiKey": "vsb_*****",
  "baseUrl": "https://your-gateway.vsx.email",
  "strategy": "sse",
  "server": {
    "spamAnalysisEnabled": true,
    "allowedDomains": ["example.com", "test.com"]
  }
}

Config File

The config file is stored at ~/.config/vsb/config.yaml:

api_key: your-api-key
base_url: https://your-gateway.vsx.email
default_output: pretty
strategy: sse

Config File Options

Key	Description	Default
`api_key`	Your VaultSandbox API key	-
`base_url`	Gateway server URL	-
`default_output`	Output format (`pretty` or `json`)	`pretty`
`strategy`	Delivery strategy (`sse` or `polling`)	`sse`

Note: default_output can only be set by editing the config file directly. The vsb config set command supports api-key, base-url, and strategy.

Environment Variables

Variable	Description
`VSB_API_KEY`	Your VaultSandbox API key
`VSB_BASE_URL`	Gateway URL
`VSB_STRATEGY`	Delivery strategy (`sse` or `polling`)
`VSB_CONFIG_DIR`	Override config directory
`VSB_OUTPUT`	Default output format

Example:

export VSB_API_KEY="your-api-key"
export VSB_BASE_URL="https://your-gateway.vsx.email"
export VSB_STRATEGY="sse"
vsb inbox create

Delivery Strategy

The delivery strategy controls how the CLI receives email updates from the gateway.

Strategy	Description
`sse`	Server-Sent Events for real-time push notifications (default)
`polling`	Periodic API calls with exponential backoff

When to use each:

SSE (default): Best for most use cases. Provides real-time, low-latency email delivery.
Polling: Use when SSE is blocked by firewall/proxy, or in CI environments where long-lived connections are problematic.

Global Flags

These flags work with any command:

Flag	Description
`--config`	Specify config file path
`-o, --output`	Output format: `pretty` or `json`

Example:

vsb inbox list --output json

Data Storage

The CLI stores data in ~/.config/vsb/:

File	Description
`config.yaml`	Configuration settings
`keystore.json`	Inbox private keys (base64-encoded)

Next Steps

TUI Dashboard - Launch the interactive dashboard
Inbox Commands - Create and manage inboxes