EKOSdocs
Docs / Usage Build

CLI

The ekos command groups, organised by task.

Global options

Every subcommand accepts these. Full flags: CLI Reference, or ekos <command> --help.

Option Meaning
--config <FILE> the ekos.toml to use (default ./ekos.toml; EKOS_CONFIG is the fallback)
--project <NAME> run against a project in the EKOS home: its config, its sources, its own ledger (also EKOS_PROJECT)
--tenant <NAME> the tenant that project belongs to (default default; also EKOS_TENANT)
--home <DIR> the EKOS home (default EKOS_HOME, then ~/.ekos)
--read-scope <FILE> show only what a JSON file of allow / deny rules (by source, path or object) allows; accepted by mcp serve, ekl and query only, refused elsewhere (also EKOS_READ_SCOPE)

ekos init and --config are refused together with --project.

Command groups

Task Commands
Index init [--detect], build [--source <name>], recover, resolve, compile, commit
Projects and inputs project add|list|show|remove, source add|list|remove, database add|list|test|remove ¹
Query query find|object|neighbourhood, ask, ekl, diff
Inspect status, doctor, coverage, freshness, ledger status|audit|timeline, graph export, config validate|preview-scan|schema
Check check refs, check explain ¹
Review and sign-off review list|show|scope|pii|identity|write-behaviour ¹, signoff show|approve|revoke ¹, workflow status ¹, conflicts list|show|resolve, identity scan, treasury scan|confirm|reject
Business semantics semantics list|show|gaps|confirm|reject|edit|gold-template|eval, export linkml, import linkml, export ossie, import ossie
Connect mcp serve
Export docs generate, dbt generate, graph export
Architecture architecture investigate|diff
Models llm routes|usage|probe ¹
Maintain clean, ledger repair|migrate, artifact repack, branch create|list|merge|delete
Install and console setup, uninstall, console run|start|stop|restart|status|open|logs, home backup|restore, commands, extensions ¹
Migrate ([migrate] enabled = true) migrate init|discover|profile|assess|map|review|approve|reject|load|validate|report|status|lower|v5|reconstruct|check-candidate
Session memory ([session-memory] enabled = true) session note|status|commit|recall|brief|review|purge|capture|extract|eval|fingerprint-noise
Distributed coordinator, compile-worker, query-worker
Auxiliary simulate, replay, eval run|regrade|history, marketing publish|post, clickhouse ask

¹ New in v1.2.0: see Installation.

Commands that decide something — review scope|pii|identity|write-behaviour, signoff approve|revoke, conflicts resolve, semantics confirm|reject|edit, import linkml, import ossie, treasury confirm|reject, session review — are human-only: no MCP tool reaches them.

The full pipeline

ekos build && ekos recover && ekos resolve && ekos compile && ekos commit
ekos coverage

Each verb is a compiler stage that writes artifacts the next one reads; run them in order. In the web console, a project's Init & compile button runs the same chain and ends with the coverage report.

Projects, sources and databases

ekos project add shop --source api=/repos/payments-api --source web=/repos/storefront --detect
ekos --project shop source add handbook --path /srv/handbook
ekos --project shop build --source handbook          # re-observe one source only
ekos --project shop database add erp --kind postgres --connect db.local:5432/erp \
  --user erp_ro --password-env ERP_DB_PASSWORD --owner public
ekos --project shop database test erp                # read-only connect, write refused, census vs compiled
ekos project remove shop                             # moves the data to the home's trash; --purge --yes deletes

source and database edit the project's ekos.toml and keep its comments. Removing either leaves the compiled objects in the ledger. database add --kind is oracle (default), postgres or clickhouse; --password-env takes the name of a variable, never a password.

Review, sign-off and integrity

ekos review list                       # subjects: scope, PII, conflicts, identity, write behaviour, glossary
ekos review show pii
ekos signoff show pii                  # the digest a sign-off needs
ekos signoff approve pii --digest <digest>
ekos workflow status                   # the seven-step bar; steps 4–7 blocked until every subject is signed
ekos check refs --format sarif --fail-on error
ekos check explain --limit 5           # model suggestions for ambiguous references; labelled, never facts

A sign-off is bound to the digest it was given on; when a signed fact changes, it reads as stale. ekos check explain makes model calls; a model that is not a local Ollama one needs --allow-metered.

Backups

ekos home backup                        # every project and the console database, one .tar.zst
ekos --tenant acme home backup          # one tenant's projects only
ekos home restore <file>                # replaces nothing that exists without --force
ekos home backup --to s3://bucket/ekos/ # object storage (S3, gs://, Azure Blob https://…); needs the object-storage build
ekos home restore --from s3://bucket/ekos/ --force   # the newest backup there

See Backup & Recovery.