EKOSdocs
Docs / Reference Operate

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.