xeroctl config - Xerotier

Overview

The config command group manages 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.

Deployment defaults: Every xeroctl subcommand uses the active deployment for its base URL and API key. Run xeroctl config use <name> to switch deployments, or pass --context <name> on a single invocation.

Quick Start

Two commands to land in a working deployment. The active deployment supplies the base URL and (keychain-resolved or inline) API key to every xeroctl subcommand.

bash

                    xeroctl config add production \
  --base-url https://api.xerotier.ai/acme-prod/v1 \
  --api-key "$PROD_API_KEY"

xeroctl config use production
xeroctl status
                

Prefer an interactive walkthrough? Run init instead. The rest of this page is reference.

Config File

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. The top-level current line names the active deployment.

~/.config/xeroctl/config.toml

                    current = "prod"

[deployment.prod]
base_url = "https://api.xerotier.ai/acme-prod/v1"
api_key  = "xero_acme-prod_AbC123..."
# optional:
# output       = "table"   # or "json"
# frontend_url = "https://app.xerotier.ai"

[deployment.staging]
base_url         = "https://staging.example/acme-stg/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. See the field reference below.

Field Reference

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/acme-prod/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: base_url is the only place the project appears. xeroctl derives the project identity from base_url for inference, and for management commands (agents, endpoints, keys) it derives the router endpoint and the project ref from the same /<project>/v1 segment. You never set a project id, UUID, or endpoint separately.

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.

Flag placement: Global options (--context, --base-url, --api-key) are consumed by the leaf subcommand. xeroctl --context staging agents fails to parse; the correct form is xeroctl agents --context staging.

init

Interactive setup. Prompts for the project-scoped base_url and an api_key, defaults the deployment name to the slug parsed from the key, writes the deployment, and points current at it.

bash

xeroctl config init

If a deployment with the same name already exists, init prompts before overwriting.

add

Registers a new named deployment non-interactively. By default the API key is inlined into the file; pass --use-keychain to store it in the OS keychain (or a 0600-mode file when no keychain is available) and write an api_key_keychain reference instead.

bash

                    xeroctl config add production \
  --base-url https://api.xerotier.ai/acme-prod/v1 \
  --api-key xero_acme-prod_your_api_key

xeroctl config add staging \
  --base-url https://staging.example/acme-stg/v1 \
  --api-key "$STAGING_API_KEY" \
  --use-keychain
                

Options

Option	Description
`name` (positional)	Local name for the deployment (e.g. `production`, `staging`)
`--base-url <url>`	Project-scoped inference URL (`https://<host>/<project>/v1`)
`--api-key <key>`	API key with appropriate scopes
`--use-keychain`	Store the key in the keychain and write `api_key_keychain` instead of inlining it
`--frontend-url <url>`	Optional dashboard URL for the deployment
`--output <fmt>`	Optional default output format (`table` or `json`)

list

Lists all configured deployment names and marks the active one (current).

bash

xeroctl config list

use

Sets current to the named deployment. Subsequent commands use that deployment's base URL and (keychain-resolved or inline) API key by default.

bash

                    xeroctl config use production
xeroctl config use staging
                

current

Prints the active deployment and its resolved values, with the API key redacted to its last four characters.

bash

xeroctl config current

set

Sets a single field on a named deployment.

bash

                    xeroctl config set production base_url https://api.xerotier.ai/acme-prod/v1
xeroctl config set production api_key xero_acme-prod_your_api_key
xeroctl config set production output json
xeroctl config set production frontend_url https://app.xerotier.ai
                

Fields

Same set as the field reference: base_url, api_key, api_key_keychain, output, frontend_url.

get

Prints a single field from a named deployment. api_key is returned masked.

bash

                    xeroctl config get production base_url
xeroctl config get production output
                

remove

Deletes a deployment from the file. When the deployment is keychain-backed, the associated keychain entry is removed too. If current pointed at the removed deployment, it is cleared or repointed.

bash

xeroctl config remove staging

path

Prints the absolute path of the config file. Useful for manual edits or for pointing a deployment playbook at the right location.

bash

xeroctl config path

Keychain Backing

When a deployment uses api_key_keychain (set by add --use-keychain), the API key is stored in the operating system keychain whenever one is available. The provider is chosen automatically:

macOS, Security.framework (the same backing as security add-generic-password).
Linux, libsecret via secret-tool when installed; typically backed by gnome-keyring or kwallet.
No keychain available, falls back to ~/.xerotier/secrets/<ref> with 0600 mode. A warning is printed so you know the key is on disk.

Removing a keychain-backed deployment removes its keychain entry. You can also delete a keychain entry manually:

bash

                    # macOS
security delete-generic-password -s xeroctl -a xeroctl-production

# Linux (libsecret)
secret-tool clear service xeroctl account xeroctl-production
                

Environment Variables

The following environment variables influence configuration discovery and value resolution:

Variable	Effect
`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, taking precedence over the resolved deployment's field. Overridden by an explicit `--api-key` flag.

Examples

First-time setup

bash

                    # Register a production deployment
xeroctl config add production \
  --base-url https://api.xerotier.ai/acme-prod/v1 \
  --api-key "$PROD_API_KEY"

# Register a staging deployment, keychain-backed
xeroctl config add staging \
  --base-url https://staging.example/acme-stg/v1 \
  --api-key "$STAGING_API_KEY" \
  --use-keychain

# Default to production
xeroctl config use production

# Verify connectivity
xeroctl status
                

Switching deployments during a session

bash

                    xeroctl config current
# -> production

xeroctl config use staging
xeroctl agents
# Now lists staging project's agents

xeroctl config use production
xeroctl agents
# Back to production
                

Per-command override

To run one command against a non-active deployment, pass --context, --base-url, or --api-key on the invocation. These flags are global options that must appear after the leaf subcommand:

bash

                    # Query staging once, without switching the active deployment
xeroctl agents --context staging

# Or supply a bare URL for an ad-hoc target
xeroctl agents \
  --base-url https://api.xerotier.ai/acme-prod/v1 \
  --api-key "$KEY"
                

Reminder: global flags follow the leaf subcommand (see Deployment Selection).

Editing fields directly

bash

                    # Inspect what is configured
xeroctl config list
xeroctl config current

# Change the output format on a deployment
xeroctl config set production output json

# Read a single field back
xeroctl config get production base_url
                

xeroctl config & contexts

Overview

Quick Start

Config File

Field Reference

Deployment Selection

init

add

Options

list

use

current

set

Fields

get

remove

path

Keychain Backing

Environment Variables

Examples

First-time setup

Switching deployments during a session

Per-command override

Editing fields directly

Quick Start

xeroctl CLI

Authentication