CLI Configuration

The ZERG CLI stores configuration in ~/.zerg/config.json with support for multiple profiles, environment variable overrides, and OS keyring integration for secure token storage.

Config File Location

The configuration file is stored at:

~/.zerg/config.json

The ~/.zerg/ directory is created automatically on first use. The config file is created with mode 0600 (owner read/write only).

Config Structure

{
  "api_url": "https://api.nonsense.ws",
  "token": null,
  "default_model": null,
  "output_format": "text",
  "profiles": {
    "default": {
      "api_url": "https://api.nonsense.ws",
      "token": "prod-api-token"
    },
    "staging": {
      "api_url": "https://staging.nonsense.ws",
      "token": "staging-token"
    },
    "local": {
      "api_url": "http://localhost:11434",
      "token": null
    }
  },
  "active_profile": "default"
}

Top-Level Fields

Field	Type	Default	Description
api_url	string	https://api.nonsense.ws	Default server URL
token	string	null	Default auth token
default_model	string	null	Model to use when not specified
output_format	string	text	Output format: text or json
profiles	object	{}	Named configuration profiles
active_profile	string	null	Currently active profile name

Profiles

Profiles allow switching between different ZERG servers without re-entering credentials.

Creating Profiles

zerg config set profiles.production.url https://api.nonsense.ws
zerg config set profiles.production.token prod-token-here

zerg config set profiles.staging.url https://staging.nonsense.ws
zerg config set profiles.staging.token staging-token-here

Switching Profiles

zerg config set active_profile staging
zerg status
zerg config set active_profile production

Using a Profile Per Command

zerg status --profile staging
zerg models --profile production

Resolution Order

The CLI resolves settings in this order (highest priority first):

1. CLI flags (--api-url, --token, --profile)
2. Active profile values
3. Top-level config values
4. Environment variables
5. Built-in defaults

URL Resolution

--api-url flag > profile.api_url > config.api_url > ZERG_API_URL > ZERG_HOST:ZERG_PORT > default

Token Resolution

--token flag > profile.token > config.token > ZERG_TOKEN

Environment Variables

Variable	Description	Example
ZERG_API_URL	Server base URL	https://api.nonsense.ws
ZERG_TOKEN	Authentication token	Bearer token value
ZERG_HOST	Server hostname (with ZERG_PORT)	192.168.1.100
ZERG_PORT	Server port (default: 21434)	8001

export ZERG_API_URL=https://api.nonsense.ws
export ZERG_TOKEN=your-token-here
zerg status

Config Commands

Get a Value

zerg config get api_url
zerg config get profiles.production.token

Set a Value

zerg config set api_url https://api.nonsense.ws
zerg config set profiles.staging.url https://staging.nonsense.ws
zerg config set active_profile default

List All Values

zerg config list

Keyring Integration

On Linux, the CLI can store tokens in the system keyring via secret-tool (libsecret) instead of the config file. This prevents tokens from being stored in plaintext.

Storing a Token in Keyring

zerg keyring-set --key zerg-token --value "your-secret-token"

Retrieving a Token from Keyring

zerg keyring-get --key zerg-token

Deleting a Token from Keyring

zerg keyring-delete --key zerg-token

Testing Keyring Access

zerg keyring-test

Keyring Requirements

Platform	Backend	Package
Linux	libsecret	libsecret-1-dev, secret-tool
macOS	Keychain	Built-in
Windows	Credential Manager	Built-in

Permission Checks

The CLI warns if the config file has overly permissive file modes:

Warning: config file ~/.zerg/config.json has loose permissions (others can read)

The config file is created with mode 0600. If permissions are modified externally, the CLI will warn on startup.