erectl config - Erebine

Overview

The config command group manages a single configuration file at ~/.config/erectl/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 erectl 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 erectl subcommand uses the active deployment for its base URL and API key. Run erectl 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 erectl subcommand.

bash

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

erectl config use production
erectl 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/erectl/config.toml

                    current = "prod"

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

[deployment.staging]
base_url         = "https://staging.example/acme-stg/v1"
api_key_keychain = "erectl-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.erebine.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 `~/.erebine/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. erectl 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.
EREBINE_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 (EREBINE_BASE_URL, EREBINE_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. erectl --context staging agents fails to parse; the correct form is erectl 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

erectl 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

                    erectl config add production \
  --base-url https://api.erebine.ai/acme-prod/v1 \
  --api-key ere_acme-prod_your_api_key

erectl 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

erectl 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

                    erectl config use production
erectl config use staging
                

current

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

bash

erectl config current

set

Sets a single field on a named deployment.

bash

                    erectl config set production base_url https://api.erebine.ai/acme-prod/v1
erectl config set production api_key ere_acme-prod_your_api_key
erectl config set production output json
erectl config set production frontend_url https://app.erebine.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

                    erectl config get production base_url
erectl 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

erectl 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

erectl 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 ~/.erebine/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 erectl -a erectl-production

# Linux (libsecret)
secret-tool clear service erectl account erectl-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/erectl/config.toml`, falling back to `~/.config/erectl/config.toml`.
`EREBINE_CONTEXT`	Selects the active deployment, taking precedence over `current` in the file. Overridden by an explicit `--context <name>` flag.
`EREBINE_BASE_URL`	Supplies the base URL ad hoc, taking precedence over the resolved deployment's field. Overridden by an explicit `--base-url` flag.
`EREBINE_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
erectl config add production \
  --base-url https://api.erebine.ai/acme-prod/v1 \
  --api-key "$PROD_API_KEY"

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

# Default to production
erectl config use production

# Verify connectivity
erectl status
                

Switching deployments during a session

bash

                    erectl config current
# -> production

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

erectl config use production
erectl 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
erectl agents --context staging

# Or supply a bare URL for an ad-hoc target
erectl agents \
  --base-url https://api.erebine.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
erectl config list
erectl config current

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

# Read a single field back
erectl config get production base_url
                

erectl 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

erectl CLI

Authentication