xeroctl CLI
Official command-line interface for the Xerotier API. Manage models, endpoints, keys, batches, and more from your terminal.
Overview
xeroctl provides full access to the Xerotier API. It is designed around a unified resource pattern:
Pattern
xeroctl <resource> # List all items
xeroctl <resource> <id> # Show item details
xeroctl <resource> <id> --<action> # Perform an action
The router API exposed by Xerotier is fully OpenAI-compatible. xeroctl wraps that API along with management endpoints (keys, agents, SLOs) that go through the frontend service.
Installation
Pre-built Binaries
bash
# macOS (Apple Silicon)
curl -L https://github.com/cloudnull/xerotier-public/releases/latest/download/xeroctl-darwin-arm64 -o xeroctl
chmod +x xeroctl
sudo mv xeroctl /usr/local/bin/
# macOS (Intel)
curl -L https://github.com/cloudnull/xerotier-public/releases/latest/download/xeroctl-darwin-amd64 -o xeroctl
chmod +x xeroctl
sudo mv xeroctl /usr/local/bin/
# Linux (x86_64)
curl -L https://github.com/cloudnull/xerotier-public/releases/latest/download/xeroctl-linux-amd64 -o xeroctl
chmod +x xeroctl
sudo mv xeroctl /usr/local/bin/
Build from Source
Requires Swift 6.2 or later:
bash
git clone https://github.com/cloudnull/xerotier-public.git
cd xerotier-public
swift build --product xeroctl -c release
# Binary at .build/release/xeroctl
Verify Installation
bash
xeroctl --version
xeroctl --help
Configuration
Config File
Configuration is stored in a TOML-subset INI file. The path is resolved in this order:
$XDG_CONFIG_HOME/xeroctl/config.toml~/.config/xeroctl/config.toml
Run xeroctl config init to create the file interactively, or xeroctl config path to print the resolved path.
File Format
~/.config/xeroctl/config.toml
[default]
base_url = https://api.xerotier.ai/proj_ABC123/v1
api_key = sk-xxx
default_endpoint = my-endpoint
frontend_url = https://
output = table
[profile.staging]
base_url = https://staging-api.example.com/proj_yyy/v1
api_key = sk-yyy
Profile Fields
| Key | Description |
|---|---|
base_url |
API base URL including project ID. Format: https://api.xerotier.ai/{project_id}/v1 |
api_key |
API key with appropriate scopes |
default_endpoint |
Default endpoint slug used by commands that accept --endpoint |
frontend_url |
Frontend URL for management operations (keys, agents) |
output |
Default output format: table, json, or wide |
Environment Variables
Environment variables override values from the config file. CLI flags override environment variables.
| Variable | Description |
|---|---|
XEROTIER_BASE_URL |
API base URL including project ID |
XEROTIER_API_KEY |
API key with appropriate scopes |
XEROTIER_FRONTEND_URL |
Frontend URL for management operations |
Resolution Order
For each setting, xeroctl resolves in this priority order:
- CLI flag (e.g.
--base-url,--api-key) - Environment variable (e.g.
XEROTIER_BASE_URL) - Active profile in config file
Shell Configuration
# Add to ~/.bashrc or ~/.zshrc
export XEROTIER_BASE_URL="https://api.xerotier.ai/proj_ABC123/v1"
export XEROTIER_API_KEY="xero_proj_ABC123_your_api_key"
Config Commands
The config subcommand manages the config file and profiles.
| Command | Description |
|---|---|
xeroctl config init |
Interactive setup wizard. Prompts for base URL, API key, and default endpoint, then writes the config file. |
xeroctl config set <key> <value> |
Set a config value in the active profile. Valid keys: base_url, api_key, default_endpoint, frontend_url, output. |
xeroctl config get <key> |
Print a single config value from the active profile. The API key is masked (shows last 4 characters only). |
xeroctl config list |
Show all values for the active profile. |
xeroctl config use-profile <name> |
Switch the active profile. |
xeroctl config profiles |
List all profiles with their base URLs. The active profile is marked. |
xeroctl config path |
Print the resolved config file path. |
Quick Setup
bash
# Interactive wizard
xeroctl config init
# Or set values directly
xeroctl config set base_url https://api.xerotier.ai/proj_ABC123/v1
xeroctl config set api_key sk-xxx
xeroctl config set default_endpoint my-endpoint
# Verify
xeroctl config list
Multiple Profiles
bash
# Set values in a named profile
xeroctl config set base_url https://staging-api.example.com/proj_yyy/v1 --profile staging
xeroctl config set api_key sk-yyy --profile staging
# Switch active profile
xeroctl config use-profile staging
# List all profiles
xeroctl config profiles
Global Options
These options are available on all commands:
| Option | Description |
|---|---|
--base-url <url> |
API base URL including project ID. Overrides XEROTIER_BASE_URL and config file. |
--api-key <key> |
API key with appropriate scopes. Overrides XEROTIER_API_KEY and config file. |
--frontend-url <url> |
Frontend URL for management operations. Overrides XEROTIER_FRONTEND_URL and config file. |
--profile <name> |
Use a named configuration profile instead of the active profile. |
--dry-run |
Preview destructive operations without executing them. |
-v, --verbose |
Print HTTP method, URL, status code, and timing to stderr for every API call. |
--timeout <seconds> |
Request timeout in seconds (default: 300). |
-o, --output <format> |
Output format: table, json, or wide (default: table). |
-q, --quiet |
Suppress non-essential output. Only errors are printed on failure. |
--watch |
Re-render output at regular intervals (use with --watch-interval). |
--no-pager |
Disable the automatic pager for long output. |
--no-color |
Disable ANSI color output. |
--no-headers |
Suppress table column headers. |
--no-footer |
Suppress row count footer. |
--columns <list> |
Comma-separated list of columns to display. |
--sort-by <col> |
Sort by column name. Prefix with - for descending (e.g. --sort-by -created). |
--filter <col=val> |
Filter rows by column value. Repeatable; multiple filters are AND-ed. |
Output Formats
All list and detail commands support three output formats, controlled by -o / --output.
| Format | Description |
|---|---|
table |
Default. Human-readable bordered table with aligned columns. Long output is piped through a pager. |
wide |
Like table but shows all available columns, including those hidden in the default view. |
json |
Machine-readable JSON array of objects. Each object key is the lowercased column header. Useful for piping to jq. |
bash
# JSON output piped to jq
xeroctl models -o json | jq '.[].id'
# Wide table with all columns
xeroctl endpoints -o wide
# Watch mode: refresh every 5 seconds
xeroctl endpoints --watch --watch-interval 5
Command Reference
Each command listed below has its own documentation page with full details, options, and examples.
| Command | Description | Docs |
|---|---|---|
chat |
Test chat completions against an endpoint (interactive or single-shot) | xeroctl/chat |
responses |
Manage stored responses from the OpenAI Responses API | xeroctl/responses |
models |
List, inspect, update, delete, share, and revalidate models | xeroctl/models |
embeddings |
Create text embeddings via the embeddings endpoint | xeroctl/embeddings |
rerank |
Rerank documents by relevance to a query | xeroctl/rerank |
score |
Score text similarity between pairs | xeroctl/rerank |
batches |
Submit, list, and manage batch inference jobs | xeroctl/batches |
files |
Upload and manage batch input/output files | xeroctl/files |
conversations |
Manage conversations and their items | xeroctl/conversations |
webhooks |
Manage webhook subscriptions | xeroctl/webhooks |
keys |
Create, list, and revoke API keys | xeroctl/keys |
agents |
Manage agents and join keys | xeroctl/agents |
slos |
Define and manage Service Level Objectives | xeroctl/slos |
upload |
Upload a model directory or archive to Xerotier | xeroctl/uploads |
uploads |
List and manage existing upload sessions | xeroctl/uploads |
completions |
Manage stored chat completions (requires --endpoint) |
xeroctl/chat |
endpoints |
List, inspect, and health-check inference endpoints | xeroctl/models |
config |
Manage configuration profiles and settings | This page |
status |
Check API connectivity | This page |
version |
Show version, commit, build date, and platform | This page |
doctor |
Diagnose configuration and connectivity issues | This page |
guide |
In-depth help guides (auth, config-file, output, endpoints) | This page |
completion |
Generate shell completion scripts for bash, zsh, or fish | This page |
Utility Commands
These commands are small enough to document here rather than on separate pages.
status
Checks that the API base URL is reachable and returns a successful response. Useful for verifying connectivity after configuration changes.
bash
xeroctl status
version
Prints the xeroctl version, Git commit hash, build date, Swift runtime version, and platform.
bash
xeroctl version
doctor
Runs a series of diagnostic checks: config file presence, active profile, base URL format, API key validity, and round-trip latency to the API. Prints a pass/fail result for each check.
bash
xeroctl doctor
guide
Displays in-depth help guides in the terminal. Available topics: auth, config-file, output, endpoints.
bash
# List available guides
xeroctl guide
# Read a specific guide
xeroctl guide auth
xeroctl guide config-file
xeroctl guide output
xeroctl guide endpoints
completion
Generates shell completion scripts for tab-completion of commands, subcommands, and flags.
bash
# Bash
xeroctl completion bash > /etc/bash_completion.d/xeroctl
# Or for the current user:
xeroctl completion bash > ~/.local/share/bash-completion/completions/xeroctl
# Zsh
xeroctl completion zsh > /usr/local/share/zsh/site-functions/_xeroctl
# Then restart your shell or run: compinit
# Fish
xeroctl completion fish > ~/.config/fish/completions/xeroctl.fish
