@m6d/cortex-cli

The cortex command line: scaffold Cortex servers, and run the generators that otherwise need a hand-written script.

bunx @m6d/cortex-cli new my-app   # from nowhere — scaffolds a project
bunx cortex swagger sync          # inside a project — reads its cortex.config.ts
bunx cortex graph seed

Commands are noun-first — cortex <resource> <verb> — except new, which acts on no existing resource. Run cortex --help, then cortex <resource> --help.

bun add -d @m6d/cortex-cli

Requires Bun. The binary re-execs itself under Bun when Node started it, and tells you how to install Bun when it is genuinely absent.

cortex new

Scaffolds ./<name>: a standalone project with cortex.config.ts, index.ts, .env and .env.example, inlined eslint/prettier/cspell/fallow config, and a docker-compose.yml when a selection contributes a service. It then runs bun install, and git init unless the target is already inside a work tree. An existing non-empty directory is an error.

bunx @m6d/cortex-cli new widget-backend --knowledge --redis

On a TTY it asks only what the flags left open — the name, the database, and one multi-select over the undecided features. With no TTY it never prompts and behaves as --yes, so a missing name is a hard error rather than a hang.

| Flag | Default | Writes | | ------------------------------------------ | ---------- | ------------------------------------------------------------------------- | | --database <postgres\|mssql> | postgres | The database block. postgres also gets a compose service; mssql not | | --attachments / --no-attachments | off | storage + vision — MinIO uploads, described by a vision model | | --redis / --no-redis | off | redis — resumable streams across restarts | | --auth / --no-auth | off | auth — JWT verification via JWKS | | --knowledge / --no-knowledge | off | neo4j + embedding + knowledge, plus a src/domains/ tree | | --control-center / --no-control-center | off | controlCenter | | --yes | | Accept the defaults instead of asking |

Unselected features are still written to cortex.config.ts, commented out, alongside fastModel, reranker, and context — the generated config documents what else exists. Every credential and URL is a placeholder in .env; none of them is prompted for.

cortex swagger sync / check

Fetches every Swagger URL the config names — server-level and per-agent, deduped — and reconciles the .endpoint.ts files under the domains directory against it.

bunx cortex swagger sync
bunx cortex swagger check
bunx cortex swagger sync --domains-dir ./server/src/domains

sync rewrites each endpoint's params, body, and response schemas in place and prints only the files it changed; unchanged ones live in the footer count. check writes nothing, reports the drift it found, and exits 2 — which is what makes it a CI step.

An endpoint file pointing at a route the spec no longer serves is MISSING. sync prints those last, so they are the thing you read, and still exits 0: writing is its job. check counts them as a finding, same as drift.

-d, --domains-dir <path> is declared on the swagger group, so it works on either side of the verb. It defaults to src/domains, resolved relative to the config file.

cortex graph seed

Loads every domain the config declares — server-level knowledge.domains and per-agent ones, deduped — and seeds Neo4j with the concepts, endpoints, services, and rules they declare, then embeds them. Reports per domain, because a domain is the unit you edit. No flags.

bunx cortex graph seed

Seeding is MERGE-based, so re-running is safe. If any statement failed, the graph is partially seeded and the command exits 1 — a half-seeded graph should not pass as success.

Global options

| Option | Description | | --------------------- | ----------------------------------------------------- | | -c, --config <path> | Path to the config file. Default ./cortex.config.ts | | -v, --verbose | Print full errors and the commands being run | | -V, --version | Output the version number | | -h, --help | Display help for command |

Config discovery is that exact filename in the directory you run in, with no upward search. There is no --cwd: Bun auto-loads .env relative to the process cwd before any of our code runs, so reading another directory's config from here would pair it with the wrong environment. cd first, or point --config at the file.

The config is inert data — a plain object literal the CLI imports. Any key that is present but evaluates to undefined, usually a missing environment variable, is listed by path and stops the run.

graph seed runs standalone: it never constructs or serves your @m6d/cortex-server — it only imports your cortex.config.ts (whose own imports may pull the server's modules in, inertly). Its Neo4j client, its embedder and its GRAPH_SCHEMA come from the graph contract the server reads the graph back with (each package vendors its own copy at pack time; the server re-exports it) — one contract, shared from both ends. Seeding stamps the schema version it wrote onto the graph; if that graph already carries a different one, the CLI says so and seeds anyway, noting that nodes from the old schema are not removed. Skew is caught on the reading side, where it matters: the server checks the stamp on its first resolve and refuses a graph it cannot read.

swagger writes .endpoint.ts source whose generated block has to satisfy the server's own EndpointDef, so a codegen that outran the installed version is a loud type error in your bun run check.

Your cortex.config.ts imports @m6d/cortex-server for defineAgent, so a project without it installed fails on the import — reported as an unloadable config, with the missing package named.

Exit codes

| Command | 0 | 1 | 2 | | --------------- | --------------------------------------------- | ----------------------------------- | ---------------------- | | new | Files written — even if bun install failed | Bad target, missing name, cancelled | — | | swagger sync | Wrote what it could, MISSING files included | Couldn't run | — | | swagger check | Every endpoint file matched and in sync | Couldn't run | Drift and/or MISSING | | graph seed | Everything seeded | A statement failed, or couldn't run | — |

Couldn't run means no config file, an unloadable config (a missing @m6d/cortex-server in the project reads as one), undefined values in it, an absent domains directory, or an unreachable Swagger host or Neo4j.

Design: docs/design/cortex-cli.md.