Docs / Reference Operate
CLI Reference
Every ekos command, subcommand and flag.
Global option on every command: --config <FILE> (default ./ekos.toml; EKOS_CONFIG is the fallback). -h/--help, -V/--version.
Pipeline
| Command | Purpose | Flags |
|---|---|---|
ekos init |
create .ekos/ and a starter ekos.toml |
— |
ekos build |
observe sources, write artifacts and File objects |
— |
ekos recover |
run knowledge-recovery passes | --parallel |
ekos resolve |
resolve identities | --force (print conflicts, do not fail) |
ekos compile |
KIR → CKM | — |
ekos commit |
CKM → ledger, then post-commit steps | --yes (skip LLM-spend prompt) |
ekos clean |
clear the artifact cache | — |
Query
| Command | Flags |
|---|---|
ekos query find <QUERY> |
--mode lexical|vector|hybrid, --explain |
ekos query object <ID> |
— |
ekos query neighbourhood <ID> |
--depth N |
ekos ask <QUESTION> |
--json, --stream, --session <NAME>, --classic, --explain (not with --classic); --stream not with --json |
ekos ekl <QUERY> |
--json |
ekos diff |
--from <TS>, --to <TS> (both required) |
Inspect and maintain
| Command | Purpose |
|---|---|
ekos status |
entry and object counts |
ekos doctor [--json] |
environment and configuration check |
ekos config validate |
parse ekos.toml, report syntax and [observe] mistakes |
ekos config preview-scan |
count what build would observe |
ekos ledger status|migrate|repair|timeline|audit |
ledger management; migrate --v3 for the fact engine |
ekos graph export |
--workspace, --level object|aggregate, --format json|ndjson, --kind, --rel-kind, --exclude-rel-kind, --group-by kind|path-prefix, --path-prefix-depth, --max-nodes (default 5000) |
ekos artifact, ekos branch |
artifact-store and ledger-branch management |
Serve
ekos mcp serve — --workspace <DIR>, --tcp <ADDR>, --http <ADDR>, --http-allow-origin <ORIGIN>, --token-file <FILE>.
Review and analysis
| Command | Purpose |
|---|---|
ekos identity scan |
cross-system candidate matches (unconfirmed) |
ekos architecture investigate / diff |
architecture reasoning loop; architecture-level diff |
ekos treasury scan |
match committed TreasuryPayment objects to GovernanceProposal approvals; writes unconfirmed AuthorizedBy relationships and lists payments with no candidate (RFC 0032) |
Export
ekos docs generate — --output <DIR>, --format md|html, --layout objects|curated|solution-architect, --prose, --yes. ekos dbt — Pentaho-derived dbt models.
Migrate (RFC 0154–0168, needs [migrate] enabled = true)
| Command | Flags |
|---|---|
ekos migrate init |
--name, --source postgres://<alias>/<db>, --target clickhouse://<alias>/<db>, --source-secret-env, --target-secret-env (a DSN with a password is refused) |
ekos migrate discover |
--project, --schema (repeatable) |
ekos migrate profile |
--tier p0|p1|p2 (default p1), --unit |
ekos migrate assess |
--unit, --no-measure |
ekos migrate map |
--unit, --emit <FILE> |
ekos migrate review |
--unit (raise a request; omit to list), --env (default staging) |
ekos migrate approve <REQUEST> |
--as (twice for R4), --confirm <NAME> (R4), --show-evidence (required at R3+) — human-only |
ekos migrate reject <REQUEST> |
--as, --reason |
ekos migrate load |
--unit, --env (default sandbox), --chunk-rows (default 100000), --dry-run |
ekos migrate validate |
--unit, --tier v1|v2|v3 (default v3); non-zero exit on failure |
ekos migrate report |
--threshold (default 0.95), --out <FILE> |
ekos migrate status |
--project |
Every verb takes --project (default: [migrate] project). Guide: Migrating a Database.
Session memory (RFC 0151, needs [session-memory] enabled = true)
| Command | Purpose |
|---|---|
ekos session note <TEXT> |
--kind finding|decision|dead_end|constraint|todo, --rationale, --anchor — inbox only |
ekos session status |
counts, dropped and pending notes |
ekos session commit |
inbox → unconfirmed, anchored ledger claims |
ekos session recall <QUERY> |
earlier notes with tier and staleness verdict |
ekos session brief |
--scope (repeatable), --scope-from-git, --budget (default 800), --format text|claude-hook |
ekos session review <CLAIM_ID> confirm|reject|supersede |
human-only; --by <ID> for supersede |
ekos session purge |
delete inbox files and slices (committed claims remain) |
ekos session capture / extract |
redacted transcript slices; opt-in LLM claim proposals |
ekos session eval / fingerprint-noise |
deterministic continuity eval; anchor-fingerprint noise |
Guide: Agent Session Memory.
Distributed
ekos coordinator, ekos compile-worker, ekos query-worker (RFC 0113).
Auxiliary
ekos simulate <scenario.yaml> and ekos replay <scenario.yaml> (World Engine), ekos eval run|history (answer-quality harness), ekos marketing publish, ekos clickhouse (live NL-to-SQL).
ekos <command> --help is always authoritative for the version you have installed.