erectl CLI - Erebine

Overview

Two command shapes coexist:

Pattern A: resource groups with action flags

                    erectl <resource>                   # List all items
erectl <resource> <id>              # Show item details
erectl <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

erectl <group> <verb> [id] [flags] # e.g. erectl 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 Erebine is fully OpenAI-compatible. erectl wraps that API along with management endpoints (keys, agents, SLOs) that go through the frontend service.

Installation

Homebrew (macOS and Linux)

bash

brew install erebine/tap/erectl

Pre-built Binaries

bash

                    # macOS (Apple Silicon)
curl -L https://github.com/Erebine/binaries/releases/latest/download/erectl-Darwin-arm64 -o erectl
chmod +x erectl
sudo mv erectl /usr/local/bin/

# Linux (x86_64)
curl -L https://github.com/Erebine/binaries/releases/latest/download/erectl-Linux-x86_64 -o erectl
chmod +x erectl
sudo mv erectl /usr/local/bin/
                

Debian and RPM packages, the desktop app, and every other binary option are on the Downloads page.

Verify Installation

bash

                    erectl --version
erectl --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/erectl/config.toml.
erectl config init

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

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

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

Configuration

erectl reads 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.

The full config command group is documented on its own page, erectl/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/erectl/config.toml

                    current = "prod"

[deployment.prod]
base_url = "https://api.erebine.ai/proj_ABC123/v1"
api_key  = "ere_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 = "erectl-staging"
                

Each deployment requires base_url plus exactly one of an inline api_key or a keychain-backed api_key_keychain. Erebine-issued API keys follow the ere_<project_external_id>_* shape. Legacy OpenAI-style sk-* keys are not issued by Erebine; use the ere_* 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.erebine.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 `~/.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: 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.
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.

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/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 (`ere_*` 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 EREBINE_BASE_URL="https://api.erebine.ai/proj_ABC123/v1"
export EREBINE_API_KEY="ere_proj_ABC123_your_api_key"
                

Config Commands

The config subcommand manages the single deployment file. Full detail, including keychain backing, lives on the erectl/config page.

Command	Description
`erectl config init`	Interactive setup. Prompts for the project-scoped base URL and API key, writes the deployment, and points `current` at it.
`erectl 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.
`erectl config list`	List all configured deployment names and mark the active one (`current`).
`erectl config use <name>`	Set `current` to the named deployment.
`erectl config current`	Print the active deployment and its resolved values, with the API key redacted to its last four characters.
`erectl 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`.
`erectl config get <name> <field>`	Print a single field from a named deployment. The API key is returned masked.
`erectl config remove <name>`	Delete a deployment from the file. A keychain-backed deployment's keychain entry is removed too.
`erectl config path`	Print the resolved config file path.

Quick Setup

bash

                    # Interactive wizard
erectl config init

# Or register a deployment directly
erectl config add production \
  --base-url https://api.erebine.ai/proj_ABC123/v1 \
  --api-key ere_proj_ABC123_your_api_key

# Verify
erectl config list
erectl config current
                

Multiple Deployments

bash

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

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

# Switch the active deployment
erectl config use staging

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

Global Options

These options are available on all commands:

Option	Description
`--base-url <url>`	API base URL including project ID. Overrides `EREBINE_BASE_URL` and config file.
`--api-key <key>`	API key with appropriate scopes. Overrides `EREBINE_API_KEY` and config file.
`--frontend-url <url>`	Frontend URL for management operations. Overrides `EREBINE_FRONTEND_URL` and config file.
`--context <name>`	Use a named deployment instead of the active one. Overrides `current` in the config file and the `EREBINE_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
erectl models -o json | jq '.[].id'

# Wide table with all columns
erectl endpoints -o wide

# Watch mode: refresh every 5 seconds
erectl endpoints --watch --watch-interval 5

# Scriptable: JSON output with column projection, filter, and quiet mode
erectl 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	erectl/chat
`completions`	Manage stored chat completions (requires `--endpoint`)	erectl/chat
`responses`	Manage stored responses from the OpenAI Responses API	erectl/responses
`models`	List, inspect, update, delete, share, and revalidate models	erectl/models
`embeddings`	Create text embeddings via the embeddings endpoint	erectl/embeddings
`rerank`	Rerank documents by relevance to a query	erectl/rerank
`score`	Score text similarity between pairs	erectl/rerank
`batches`	Submit, list, and manage batch inference jobs	erectl/batches
`files`	Upload and manage batch input/output files	erectl/files
`webhooks`	Manage webhook subscriptions	erectl/webhooks
`keys`	Create, list, and revoke API keys	erectl/keys
`agents`	Manage agents and join keys (uses active-context resolution)	erectl/agents
`slos`	Define and manage Service Level Objectives	erectl/slos
`uploads`	List and manage existing upload sessions	erectl/uploads

Pattern B: verb subcommands

Command	Description	Docs
`conversations`	Manage conversations and their items	erectl/conversations
`endpoints`	Manage inference endpoints and their agents (create, provision, CORS, health, weighted multi-agent membership)	erectl/endpoints
`semantic-router`	Configure the semantic router, manage dynamic routing rules, and inspect route decisions and health	erectl/semantic-router
`evolution`	Inspect and control a workspace's two self-evolution lanes: state, per-lane switch, queued runs, breaker, history, and rollback	erectl/evolution
`chats`	Manage chats, branches, messages, memories, and context	erectl/platform
`workspaces`	Manage workspaces, search, memories, and files	erectl/platform
`project`	Manage project members, roles, and invitations	erectl/platform
`team`	Manage team members, invitations, and role delegations	erectl/platform
`settings`	Read, update, or delete project-level settings	erectl/platform
`preferences`	Manage per-context preferences (model defaults, output, behavior)	erectl/platform
`config`	Manage named deployments and stored credentials in the config file	erectl/config
`exec`	Execute server-side tools and prompts directly from the CLI	erectl/exec
`templates`	List and render prompt templates	erectl/templates
`approvals`	List, approve, and reject pending human-in-the-loop approval requests	erectl/approvals
`learnings`	Inspect and curate distilled learnings captured by the agent	erectl/learnings
`upload`	Upload a model directory or archive to Erebine	erectl/uploads
`maintenance`	Schedule, update, cancel, complete, and purge maintenance windows	erectl/platform
`usage`	Query usage events, request logs, per-endpoint rollups, and uptime	erectl/platform
`exports`	Create, monitor, download, and cancel data exports	erectl/platform
`health`	View project and service health dashboards	erectl/platform
`discovery`	Manage EEM agent discovery candidates	erectl/platform
`bootstrap`	Bootstrap a EEM agent on the local host (uses `EREBINE_AGENT_JOIN_KEY` when set)	erectl/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

erectl status

version

Prints the erectl version, Git commit hash, build date, and platform.

bash

erectl 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

erectl doctor

guide

Displays in-depth help guides in the terminal. Available topics: auth, config-file, output, endpoints.

bash

                    # List available guides
erectl guide

# Read a specific guide
erectl guide auth
erectl guide config-file
erectl guide output
erectl guide endpoints
                

completion

Generates shell completion scripts for tab-completion of commands, subcommands, and flags.

bash

                    # Bash
erectl completion bash > /etc/bash_completion.d/erectl
# Or for the current user:
erectl completion bash > ~/.local/share/bash-completion/completions/erectl

# Zsh
erectl completion zsh > /usr/local/share/zsh/site-functions/_erectl
# Ensure your ~/.zshrc has the following before completions are loaded:
#   autoload -Uz compinit && compinit
# Then restart your shell, or run: compinit

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