CLI

Olivares AI ships as one static Go binary, controlplane. The same artifact is the engine, the embedded web console (served on the same origin as the API), and the edge collector — which role you get is chosen by the subcommand you run. There is no separate “server” and “agent” download.

This page documents the commands and flags confirmed in the current binary. It is not exhaustive, and the surface is pre-1.0: subcommands, flags and defaults can change. When in doubt, run controlplane <command> --help against the exact build you deployed and treat that as authoritative. For how to obtain and run the binary, see Self-host; for settings that live in the environment rather than flags, see Configuration.

Command overview

controlplane <command> [flags]

The root command groups, among others:

The sections below cover the commands most operators reach for first. keys, license and evals are real but specialised; run them with --help for their flag surfaces.

controlplane serve

Runs the control plane: the HTTP server (REST API plus the embedded console) and the gRPC server. Three properties are defaults, not opt-ins:

• TLS is on by default. With no certificate supplied, the engine generates a self-signed certificate in the data directory and logs its SHA-256 fingerprint; clients must trust or pin it. The gRPC server fails closed — outside --insecure it refuses to start in plaintext rather than silently downgrading.
• Loopback by default. Both listeners bind 127.0.0.1. Exposing the control plane beyond the local host is a deliberate change: you set a non-loopback bind and front it with your own ingress. The control plane runs in your infrastructure and can be air-gapped.
• No default credentials. On a fresh install with no users, the engine mints a one-time, single-use setup token (prefix olst_) and prints it to stdout only (never the logs). You bootstrap the first administrator by posting that token to POST /v1/setup, then log in.

controlplane serve
# Read the one-time olst_ setup token from this process's stdout.

Useful flags

SQLite (pure-Go, single-node) suits air-gapped, single-node installs. Selecting postgres is what you do for multi-tenant or scale-out deployments, where row-level security is the tenant backstop. There are further flags for Postgres residency and roles (--admin-dsn, --region, --known-regions, --allow-privileged-db-role) — see their --help and Configuration.

--insecure serves plaintext HTTP and gRPC, so bearer tokens travel in the clear. Never use it on any address reachable beyond the local host.

--seed-demo is demo-only

--seed-demo provisions a synthetic, fabricated estate together with a demo administrator whose password is public (it lives in the source tree). It exists to make the console and end-to-end tests render against live-shaped data. Because the credential is public, serve refuses to start with --seed-demo on any non-loopback bind and exits with an error directing you to bind 127.0.0.1.

Treat it as throwaway: use a disposable data directory and never point it at data you care about. A real install is serve without --seed-demo, where the engine mints a one-time setup token and you create your own administrator. See Quickstart for the demo walkthrough.

controlplane collector

Runs the binary as an edge collector for the distributed topology. A collector loads the configured source connectors locally and pushes their observations to a remote core over gRPC. It opens no inbound listener — it dials out, it does not accept connections, so a failing collector never sits in the data path of any agent.

controlplane collector --core-addr host:port [flags]

--core-addr is required. The collector authenticates to the core with a bearer token holding an ingest principal (--token-file, or $OLIVARES_INGEST_TOKEN) and — when the core enforces mutual TLS — a collector client certificate (--client-cert, --client-key, with --ca to pin a self-signed core cert). Both serve and collector wire their connectors from the same configuration; an unconfigured source warns honestly rather than failing the process. Configuring sources is covered in Connect a source.

controlplane version

Prints the version, commit, build date, OS/arch and Go runtime, plus this binary’s FIPS 140-3 mode (a mode, not a validation claim).

controlplane version

The version string is injected at build time; a build from an untagged working tree reports a development version. Do not treat the string as provenance — verify releases with the signed artifacts. See Verify a release.

controlplane openapi

Prints the engine’s OpenAPI 3.1 document to stdout, deterministically indented so the output diffs cleanly, without a running server.

controlplane openapi > openapi.json

This is the same contract the engine serves at GET /openapi.json. The served REST surface covers the core paths; some module routes are reachable but deliberately not part of the served document.

controlplane audit and dr

The evidence ledger has two offline command groups:

• audit operates on the append-only ledger: verify a tenant’s hash chain and its signed checkpoints, checkpoint to write a new one, export to a SIEM format (cef/syslog/otlp), and archive export / archive verify for the immutable archive that re-verifies offline. audit verify and audit archive verify print a JSON report and exit 0 by default; pass --strict to exit non-zero on a failed integrity check so cron or CI can gate on it. External key pins (--pubkey, --event-pubkey) replace the on-box advisory keys for an attacker-resistant check.
• dr is a ledger-continuity-safe backup / restore, plus verify (a non- destructive DR drill) and inspect. Unlike a raw database dump it captures the signing keys under your key-encryption key, records the per-tenant chain tips, and re-verifies the whole chain on restore. restore and verify exit non-zero unless the restored ledger is green.

These commands back the verification model described in Governance and Verify a release.

Stability

Pre-1.0, in active development. The commands and flags above are confirmed in the current binary, but the full surface is still evolving. Run controlplane <command> --help against your build and treat that as authoritative over any document. For what is implemented today versus planned, see Honesty and limits.