xeroctl CLI - Xerotier

Overview

Two command shapes coexist:

Pattern A: resource groups with action flags

                    xeroctl <resource>                   # List all items
xeroctl <resource> <id>              # Show item details
xeroctl <resource> <id> --<action>   # Perform an action
                

Pattern A is used by these groups, each of which accepts the action as a flag on a hidden default subcommand:

models
uploads
completions
responses
webhooks
keys
batches
files
slos
agents
agents join-keys

Pattern B: verb subcommands

xeroctl <group> <verb> [id] [flags] # e.g. xeroctl endpoints update my-ep

Pattern B is used by these groups:

endpoints
conversations
chats
workspaces
maintenance
project
exec
templates
approvals
exports
usage
mcp
bootstrap
discovery
preferences
learnings
config

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/
                

Verify Installation

bash

                    xeroctl --version
xeroctl --help
                

First Commands

Three invocations cover the path from an unconfigured binary to a working chat completion. Each one is also documented in full further down the page.

bash

                    # 1. Write a config file. Interactive wizard prompts for the project-scoped
#    base URL and API key, then writes ~/.config/xeroctl/config.toml.
xeroctl config init

# 2. Confirm the API base URL is reachable.
xeroctl status

# 3. Send one prompt to an endpoint and print the reply.
xeroctl chat --endpoint <slug> --message 'hello'
                

If status fails, run xeroctl doctor for a diagnostic dump of the resolved config path, active deployment, base URL, and a connectivity probe.

Configuration

xeroctl reads a single configuration file at ~/.config/xeroctl/config.toml (honoring $XDG_CONFIG_HOME). The file holds one or more named deployments. A top-level current line selects which deployment commands use by default. Everything xeroctl needs is derived from two values you can copy directly from the dashboard: the project-scoped base_url and an api_key. There are no project UUIDs, endpoints, or hidden ids in the file.

The full config command group is documented on its own page, xeroctl/config. This section is the quick reference.

File Format

The file is plain TOML you can read and edit by hand. Each [deployment.<name>] section is one deployment, where <name> is an arbitrary human label.

~/.config/xeroctl/config.toml

                    current = "prod"

[deployment.prod]
base_url = "https://api.xerotier.ai/proj_ABC123/v1"
api_key  = "xero_proj_ABC123_your_api_key"
# optional:
# output       = "table"   # or "json"
# frontend_url = "https://"

[deployment.staging]
base_url         = "https://staging-api.example.com/proj_yyy/v1"
api_key_keychain = "xeroctl-staging"
                

Each deployment requires base_url plus exactly one of an inline api_key or a keychain-backed api_key_keychain. Xerotier-issued API keys follow the xero_<project_external_id>_* shape. Legacy OpenAI-style sk-* keys are not issued by Xerotier; use the xero_* form for all deployments and env vars.

Deployment Fields

Fields live under each [deployment.<name>] section.

Field	Required	Description
`base_url`	Yes	The project-scoped inference URL from the dashboard, of the form `https://<host>/<project>/v1` (e.g. `https://api.xerotier.ai/proj_ABC123/v1`). Used verbatim for inference; management commands derive the host and project segment from it.
`api_key`	One of these	Inline API key. Stored as TOML text in the file (set 0600 mode on the file). Wins over `api_key_keychain` if both are present.
`api_key_keychain`	One of these	Reference to a keychain entry that holds the API key. Resolved through the OS keychain, falling back to `~/.xerotier/secrets/` at 0600 when no keychain is available.
`output`	No	Default output format. One of `table` or `json`.
`frontend_url`	No	Optional dashboard URL associated with the deployment.

Derived values: Project id, host, and endpoint are all derived from base_url at runtime. You never write a project UUID or endpoint into the file.

Deployment Selection

When a command needs a deployment, the active one is chosen by the first rule that matches:

--context <name> flag on the invocation.
XEROTIER_CONTEXT environment variable.
current in the config file.
If exactly one [deployment.*] section exists, that one.
Otherwise an error listing the available deployment names.

Individual values can also be overridden ad hoc without touching the file. For any single value the first match wins: an explicit flag (--base-url, --api-key), then the matching environment variable (XEROTIER_BASE_URL, XEROTIER_API_KEY), then the resolved deployment's field. When the flags or environment variables fully satisfy a command, no deployment is consulted and the file may be absent.

Environment Variables

The following environment variables influence configuration discovery and value resolution:

Variable	Description
`XDG_CONFIG_HOME`	Overrides the base config directory. The config file is read from `$XDG_CONFIG_HOME/xeroctl/config.toml`, falling back to `~/.config/xeroctl/config.toml`.
`XEROTIER_CONTEXT`	Selects the active deployment, taking precedence over `current` in the file. Overridden by an explicit `--context <name>` flag.
`XEROTIER_BASE_URL`	Supplies the base URL ad hoc, taking precedence over the resolved deployment's field. Overridden by an explicit `--base-url` flag.
`XEROTIER_API_KEY`	Supplies the API key ad hoc (`xero_*` shape), taking precedence over the resolved deployment's field. Overridden by an explicit `--api-key` flag.
`NO_COLOR`	Disable ANSI color output. Same effect as `--no-color`.
`PAGER`	Override the program used to paginate long output. Defaults to `less`.

Shell Configuration

                    # Add to ~/.bashrc or ~/.zshrc to override ad hoc
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 single deployment file. Full detail, including keychain backing, lives on the xeroctl/config page.

Command	Description
`xeroctl config init`	Interactive setup. Prompts for the project-scoped base URL and API key, writes the deployment, and points `current` at it.
`xeroctl config add <name> --base-url <url> --api-key <key> [--use-keychain]`	Register a new named deployment non-interactively. `--use-keychain` stores the key in the OS keychain and writes `api_key_keychain` instead of inlining it.
`xeroctl config list`	List all configured deployment names and mark the active one (`current`).
`xeroctl config use <name>`	Set `current` to the named deployment.
`xeroctl config current`	Print the active deployment and its resolved values, with the API key redacted to its last four characters.
`xeroctl config set <name> <field> <value>`	Set a single field on a named deployment. Valid fields: `base_url`, `api_key`, `api_key_keychain`, `output`, `frontend_url`.
`xeroctl config get <name> <field>`	Print a single field from a named deployment. The API key is returned masked.
`xeroctl config remove <name>`	Delete a deployment from the file. A keychain-backed deployment's keychain entry is removed too.
`xeroctl config path`	Print the resolved config file path.

Quick Setup

bash

                    # Interactive wizard
xeroctl config init

# Or register a deployment directly
xeroctl config add production \
  --base-url https://api.xerotier.ai/proj_ABC123/v1 \
  --api-key xero_proj_ABC123_your_api_key

# Verify
xeroctl config list
xeroctl config current
                

Multiple Deployments

bash

                    # Register a second deployment, keychain-backed
xeroctl config add staging \
  --base-url https://staging-api.example.com/proj_yyy/v1 \
  --api-key xero_proj_yyy_your_staging_api_key \
  --use-keychain

# This writes a [deployment.staging] section to the file.

# Switch the active deployment
xeroctl config use staging

# Or run one command against it without switching
xeroctl agents --context staging
                

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.
`--context <name>`	Use a named deployment instead of the active one. Overrides `current` in the config file and the `XEROTIER_CONTEXT` environment variable.
`--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`.

Shaping the Output

The --columns, --sort-by, --filter, --no-headers, and --no-footer options (see Global Options) apply to all three formats:

--columns <a,b,c> selects which columns are emitted. In table and wide, only the selected columns are rendered; in json, each emitted object contains only the selected keys (keys are the lowercased column header).
--sort-by <col> sorts rows by the named column. Prefix with - for descending. Applies before --columns projection and is honored by json output (array order matches the sorted rows).
--filter col=val drops rows that do not match. Repeat for AND semantics. Applies to all three formats; in json, filtered rows are omitted from the array.
--no-headers suppresses the column header row in table and wide; no effect on json (object keys remain).
--no-footer suppresses the row-count footer in table and wide; no effect on json.
--watch with --watch-interval <sec> re-renders the same shaped output at fixed intervals.

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

# Scriptable: JSON output with column projection, filter, and quiet mode
xeroctl endpoints -o json --columns id,status,model --filter status=ready --sort-by -created --quiet \
    | jq '.[] | {id, model}'
                

Command Reference

Each command links to its own page with full options, flags, and examples. Tables are grouped by the two command shapes from the Overview.

Pattern A: resource groups

Command	Description	Docs
`chat`	Test chat completions against an endpoint, interactive or single-shot	xeroctl/chat
`completions`	Manage stored chat completions (requires `--endpoint`)	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
`webhooks`	Manage webhook subscriptions	xeroctl/webhooks
`keys`	Create, list, and revoke API keys	xeroctl/keys
`agents`	Manage agents and join keys (uses active-context resolution)	xeroctl/agents
`slos`	Define and manage Service Level Objectives	xeroctl/slos
`uploads`	List and manage existing upload sessions	xeroctl/uploads

Pattern B: verb subcommands

Command	Description	Docs
`conversations`	Manage conversations and their items	xeroctl/conversations
`endpoints`	List, inspect, and health-check inference endpoints	xeroctl/models
`chats`	Manage chats, branches, messages, memories, and context	xeroctl/platform
`workspaces`	Manage workspaces, search, memories, and files	xeroctl/platform
`project`	Manage project members, roles, and invitations	xeroctl/platform
`team`	Manage team members, invitations, and role delegations	xeroctl/platform
`settings`	Read, update, or delete project-level settings	xeroctl/platform
`preferences`	Manage per-context preferences (model defaults, output, behavior)	xeroctl/platform
`config`	Manage named deployments and stored credentials in the config file	xeroctl/config
`exec`	Execute server-side tools and prompts directly from the CLI	xeroctl/exec
`templates`	List and render prompt templates	xeroctl/templates
`approvals`	List, approve, and reject pending human-in-the-loop approval requests	xeroctl/approvals
`learnings`	Inspect and curate distilled learnings captured by the agent	xeroctl/learnings
`upload`	Upload a model directory or archive to Xerotier	xeroctl/uploads
`maintenance`	Schedule, update, cancel, complete, and purge maintenance windows	xeroctl/platform
`usage`	Query usage events, request logs, per-endpoint rollups, and uptime	xeroctl/platform
`exports`	Create, monitor, download, and cancel data exports	xeroctl/platform
`health`	View project and service health dashboards	xeroctl/platform
`discovery`	Manage XEM agent discovery candidates	xeroctl/platform
`bootstrap`	Bootstrap a XEM agent on the local host (uses `XEROTIER_AGENT_JOIN_KEY` when set)	xeroctl/platform
`mcp`	Render and install MCP / inference setup bundles for supported clients	docs/mcp

Utilities

Command	Description	Docs
`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, and platform.

bash

xeroctl version

doctor

Prints the resolved config path, active deployment, and base URL, then runs a connectivity test by listing models against the configured endpoint. Surfaces the returned model count on success and the raised error on failure.

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
# Ensure your ~/.zshrc has the following before completions are loaded:
#   autoload -Uz compinit && compinit
# Then restart your shell, or run: compinit

# Fish
xeroctl completion fish > ~/.config/fish/completions/xeroctl.fish
                