docs
//

The full Erebine surface from one binary. Inference, stored resources, project management, Erebine Inference Microservices (EIMs) and EEMs, webhooks, MCP setup, EEM execution, prompts, approvals, and learnings, all routed through your active deployment, all OpenAI-shape where the API is.

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:

Pattern B: verb subcommands
erectl <group> <verb> [id] [flags] # e.g. erectl endpoints update my-ep

Pattern B is used by these groups:

The router API exposed by Erebine is fully OpenAI-compatible. erectl wraps that API along with the router's management endpoints (keys, EIMs, EEMs, SLOs).

Installation

Homebrew (macOS and Linux)

bash
brew install erebine/tap/erectl

Pre-built Binaries

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

Debian and RPM packages 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" [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.

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:

  1. --context <name> flag on the invocation.
  2. EREBINE_CONTEXT environment variable.
  3. current in the config file.
  4. If exactly one [deployment.*] section exists, that one.
  5. 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 lookup 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.
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 eims --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.
--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 Print what a command that changes something would do, and send nothing. Every command that creates, updates, deletes, binds, grants, links or runs something honours it.
-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, fitted to the terminal by shortening long cells (marked ...). An id column is never shortened, so an id can always be copied into the next command. 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: the API's own response, with its field names and types. A list prints the response envelope, usually an object with a data array. A command that changes something prints the changed object, or {"id": ..., "status": ...} when the API returns no body (with path for a download). Useful for piping to jq.

Shaping the Output

The --columns, --sort-by, --filter, --no-headers, and --no-footer options (see Global Options) shape table and wide. json always carries the full response; select and filter it with jq.

  • --columns <a,b,c> renders only the selected columns, in that order.
  • --sort-by <col> sorts rows by the named column. Prefix with - for descending.
  • --filter col=val drops rows that do not match. Repeat for AND semantics.
  • --no-headers suppresses the column header row.
  • --no-footer suppresses the row-count footer.
  • --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 '.data[].id' # Wide table with all columns erectl endpoints -o wide # Watch mode: refresh every 5 seconds erectl endpoints --watch --watch-interval 5 # Table with column projection, filter, and sort erectl endpoints --columns id,status,model --filter status=ready --sort-by name # Scriptable: the same selection from the JSON response erectl endpoints -o json --quiet \ | jq '.data[] | select(.status == "ready") | {id, slug, model_id}'

For scripts: confirmation questions go to standard error, so standard output holds only the command's output; pass --force to skip them. A command whose change the API reports as not done, such as a delete answered with "deleted": false, exits with status 1, as does batches --wait when the batch fails, is cancelled, or expires.

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
eims Manage EIMs and their join keys (uses active-context resolution) erectl/eims
eems Manage EEMs and their join keys (uses active-context resolution) erectl/eims
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 EIMs (create, provision, CORS, health, weighted multi-EIM 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, files, EEM bindings, and auto-approval grants erectl/platform
project Manage project members and invitations 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 the router captures after tool runs and chats erectl/learnings
deploy Deploy EIMs or an EEM on this host end to end; the kind (eim or eem) is required erectl/deploy
tiers List service tiers and the slugs accepted by deploy eim --tier and join-key minting erectl/deploy
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
knowledge Inspect, edit, and delete workspace knowledge erectl knowledge --help
anchors Manage anchor marketplace metadata erectl anchors --help
admin Platform administration (platform admins only) erectl admin --help
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
license Show the MIT license and third-party notices (releases after v1.13.0) 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. Prints the round-trip time on success and the raised error on failure.

On a host with an Intel discrete GPU, or an Intel GPU EIM deploy, it also checks that vm.overcommit_memory is 1, and when it is not, prints a warning with the fix (sudo erectl deploy eim --update) and any sysctl file that sets it back at boot. The warning does not change the exit status.

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

license

Prints the MIT License erectl is distributed under, then the notices for the third-party packages linked into the binary, and exits 0. Release binaries after v1.13.0 carry the command; both texts are compiled in, so it needs no configuration or network. The EIM and EEM binaries from those releases print the same texts with erebine-eim-agent --license and erebine-eem-agent --license. See License.

bash
erectl license