CLI Reference
Every ekos command, subcommand and flag.
Global options on every command:
| Option | Meaning |
|---|---|
--config <FILE> |
ekos.toml to use (default ./ekos.toml; EKOS_CONFIG is the fallback) |
--home <DIR> |
the EKOS home (default $EKOS_HOME, then ~/.ekos) |
--project <NAME> |
run against a project in the home: its config, its sources, its own ledger ($EKOS_PROJECT) |
--tenant <NAME> |
the project's tenant (default default; $EKOS_TENANT) |
--read-scope <FILE> |
show only what a JSON read scope allows; accepted by mcp serve, ekl and query only, refused elsewhere ($EKOS_READ_SCOPE) |
-h/--help, -V/--version. ekos commands --json prints every command with its arguments and its class — read, write, review, admin, external or local — which decides who may run it from the web console.
Pipeline
| Command | Purpose | Flags |
|---|---|---|
ekos init |
create .ekos/ and a starter ekos.toml |
--detect (write a config from what is in the tree: SQL dialects, exclusions, inputs), --dry-run, --force |
ekos build |
observe sources and live databases, write artifacts and File objects |
--source |
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 | — |
ekos coverage |
which input kinds compiled into objects, and which silently produced nothing | --json, --strict (non-zero exit on a zero), --all |
Projects, sources and databases
| Command | Purpose |
|---|---|
ekos project add <NAME> --source <DIR | NAME=DIR>… |
a project in the home; --detect; sources are never written to |
ekos project list / show <NAME> / remove <NAME> |
--json; remove moves data to the trash unless --purge (--yes) |
ekos source add <NAME> --path <DIR> |
add a named input; --kind dir|git |
ekos source list / remove <NAME> |
remove keeps compiled objects and the directory |
ekos database add <NAME> |
--kind oracle|postgres|clickhouse (default oracle), --connect, --user, --password-env <VAR> (the variable's name), --owner (repeatable), --profile p0|p1|p2 and --dictionary idempiere (Oracle only) |
ekos database list |
never a password; whether its variable is set |
ekos database test <NAME> |
connect read-only, read the catalog, check writes are refused, compare the census with what was compiled; --json |
ekos database remove <NAME> |
compiled objects stay |
ekos home backup |
--out <FILE>, --to <URL> (S3, Azure Blob, GCS) |
ekos home restore <ARCHIVE> |
--from <URL> (a backup, or a location ending in / for the newest), --force |
Install and console
| Command | Purpose |
|---|---|
ekos setup |
install or reconfigure: wizard in the browser, or --answers <FILE>; --dry-run, --no-browser, --port |
ekos uninstall |
remove what setup installed; --purge, --yes, --ui, --detach |
ekos console run|start|stop|restart|status|open|logs |
the web console of this home; open --no-browser, logs --lines N |
ekos commands, ekos extensions |
the command catalogue and extension console pages as JSON |
Query
| Command | Flags |
|---|---|
ekos query find <QUERY> |
--mode lexical|vector|hybrid, --explain |
ekos query object <ID> |
--format |
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 [--storage] [--json] |
entry and object counts, and whether the ledger still matches the source |
ekos doctor [--json] |
environment and configuration check |
ekos freshness [--json] [--limit N] |
files changed, added or removed since the last commit, and the objects that cite them |
ekos config validate / preview-scan / schema |
check ekos.toml; count what build would observe; the JSON schema of every setting |
ekos ledger status|migrate|repair|timeline|audit <ID> |
ledger management; migrate --v3 for the fact engine; timeline --bucket day|week|month --since |
ekos llm routes|usage|probe |
each task's model route and price; recorded usage and cost (--since); probe sends one tiny request per model (metered) |
ekos graph export |
--level object|aggregate, --format json|ndjson, --kind, --rel-kind, --exclude-rel-kind, --group-by kind|path-prefix, --path-prefix-depth, --max-nodes (default 5000), --max-edges (default 20000), --min-degree, --include-property, --as-of, --first-seen, --output |
ekos artifact repack |
loose artifacts into packed segments |
ekos branch create|list|merge|delete |
ledger branches |
Integrity (RFC 0233)
| Command | Purpose |
|---|---|
ekos check refs |
references that resolve to nothing or to several objects. --scope cross-system|code|all, --min-confidence, --format table|json|sarif, --fail-on error|warning, --baseline <time|report.json>, --show-suppressed, --reachability, --from-index |
ekos check explain |
ask the configured model to suggest a target for an ambiguous reference; --fingerprint, --limit, --allow-metered, --json |
Suppressions go in <state>/xref-ignore.toml, each with a mandatory reason.
Serve
ekos mcp serve — --workspace <DIR>, --tcp <ADDR>, --http <ADDR>, --http-allow-origin <ORIGIN>, --token-file <FILE>, --read-scope <FILE>.
Review, sign-off and workflow (RFC 0213)
| Command | Purpose |
|---|---|
ekos review list / show <SUBJECT> |
subjects (scope, pii, conflicts, identity, write-behaviour, glossary) with counts and sign-off state; --undecided, --limit, --json |
ekos review scope <TABLES> |
human-only: --in / --out, --reason, --as |
ekos review pii <COLUMNS> |
human-only: --confirm / --reject, --mask, --reason, --as |
ekos review identity <MATCHES> |
human-only: --confirm / --reject by id or A = B label; --note, --as |
ekos review write-behaviour <TABLES> |
human-only: --confirm, or --set with --reason |
ekos signoff show <SUBJECT> |
the digest and whether the sign-off is valid, stale or missing |
ekos signoff approve <SUBJECT> --digest <D> |
human-only: sign on the digest show printed; --note, --as |
ekos signoff revoke <SUBJECT> |
human-only; --reason, --as |
ekos workflow status |
the seven-step bar and every subject's sign-off; --json |
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 (RFC 0032) |
ekos treasury confirm|reject <ID> |
human-only; --as, --note (required for reject) |
Conflicting evidence (RFC 0172, on by default)
| Command | Purpose |
|---|---|
ekos conflicts list |
--status open|resolved|dismissed, --type duplicate_definition|merge_loss|label_mismatch|doc_vs_data or, from a live Oracle database, model_table_missing|table_without_model|model_column_missing|mandatory_but_nullable|routine_text_differs; --json |
ekos conflicts show <NAME> |
every claim with its path:line and source, what EKOS kept, the decision; --json |
ekos conflicts resolve <NAME> |
human-only: --pick N (1-based claim) or --both-valid --note …; --as (default $USER) |
Business semantics (RFC 0170, needs [semantics] enabled = true)
| Command | Purpose |
|---|---|
ekos semantics list |
--kind concept|enum|constraint|gap|conflict|rationale, --status hypothesis|confirmed|rejected|needs_review, --json |
ekos semantics show <ITEM> |
one item with its evidence (path:line), links and commits |
ekos semantics gaps |
unexplained codes, undocumented concepts, conflicts, the needs_review queue |
ekos semantics confirm <ITEM>... |
human-only, all or nothing; --as (default $USER), --note |
ekos semantics reject <ITEM> |
--note (required), --as |
ekos semantics edit <ITEM> |
confirm with corrections: --name, --description, --label (coded value), --as, --note |
ekos semantics gold-template |
blank, structure-only gold set for an expert; --tables, --out |
ekos semantics eval --gold <FILE> |
score against a gold set; --json |
ekos export linkml |
--status confirmed|hypothesis|all (default confirmed), --out, --name, --json |
ekos import linkml <FILE> |
edits → review decisions, all or nothing; --dry-run, --as, --json |
ekos export ossie |
the compiled schema as an Apache Ossie model (spec 0.2.0.dev0); --status confirmed|hypothesis|all (default confirmed, for business meanings), --out (.json writes JSON), --json, --name, --database, --source — on main |
ekos import ossie <FILE> |
edits to an exported Ossie model's EKOS extensions → review decisions, all or nothing; human-only; --dry-run, --as, --json — on main |
ekos export dbt-semantic --out <DIR> |
the project's Apache Ossie models as a dbt semantic layer: MetricFlow semantic_models.yml, key tests in models.yml, skipped.md; --with-time-spine adds a daily time spine model — on main (RFC 0246) |
Guide: Business Semantics and LinkML.
Export
ekos docs generate — --output <DIR>, --format md|html, --layout objects|curated|solution-architect|estate, --prose, --yes. estate (RFC 0214) renders a database estate as wiki pages: areas, tables, glossary, lifecycles, logic, history, findings. ekos dbt generate --output <DIR> — dbt models from Pentaho-derived transformations.
Migrate (RFC 0154–0167, 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 |
--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 |
units by state, and what is blocking |
ekos migrate lower |
lower every recovered view to ClickHouse and propose a redesign per trigger; --database, --sql, --record, --json |
ekos migrate v5 |
run each lowered view on two sandbox engines and compare; --source-sandbox, --target-sandbox, --record, --json |
ekos migrate reconstruct |
ask the configured model for a ClickHouse implementation of one PL/pgSQL routine; --source, --allow-metered, --record, --json |
ekos migrate check-candidate |
check a candidate target statement states nothing its source does not; --source, --candidate, --json |
On the migration verbs --project names the migration 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); --older-than-days |
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 serve|status, ekos compile-worker run, ekos query-worker serve (RFC 0113).
Auxiliary
ekos simulate <scenario.yaml> and ekos replay <scenario.yaml> (World Engine), ekos eval run|regrade|history (answer-quality harness), ekos marketing publish|post, ekos clickhouse ask (live NL-to-SQL).
ekos <command> --help is always authoritative for the version you have installed.