@keel_flow/cli

The Keel command-line interface. Runs the four-check verify gate (spec compliance, architecture compliance, principles compliance, tests + lint) against any git diff and exits non-zero on critical violations. Also provides the orchestrator agent loop, structured planning, self-improvement commands, the autonomous goal loop, and keel up to boot the hosted workspace.

Part of the Keel framework.

Global install (recommended)

From npm (once published)

npm install -g @keel_flow/cli
keel --version

From source (development)

npm install -g ./packages/cli will not work because package.json uses workspace:* dependency specifiers that npm cannot resolve. Use pnpm link instead:

pnpm --filter @keel_flow/cli build
cd packages/cli && pnpm link --global
keel --version

To unlink:

pnpm unlink --global @keel_flow/cli

Note: the published npm install -g @keel_flow/cli path requires all @keel_flow/* peer packages to be published to the npm registry at the same version.

Command surface

Verify gate

keel verify --diff origin/main..HEAD   # four-check gate; exit 2 = blocked
keel verify --diff origin/main..HEAD --spec "add KB retrieval"  # + LLM spec check
keel verify --json result.json         # write VerifyResult JSON

Architecture map

keel map                              # print nodes, connections, contexts
keel map --check                      # validate schema; exit non-zero if invalid
keel map --repo                       # auto-derived repo-map (symbol summary)
keel map --repo --json                # structured JSON output
keel map --repo --no-cache            # skip .keel/repo-map.cache.json
keel map --repo --output <path>       # write output to file instead of stdout
keel map --repo --max-tokens <n>      # token budget for the repo-map summary

Principles

keel principles list
keel principles list --severity critical

Orchestrator

keel orchestrate "<task>"                       # run agent loop end-to-end
keel orchestrate "<task>" --dry-run             # plan only; no writes
keel orchestrate "<task>" --max-iterations 10
keel orchestrate "<task>" --no-questions        # skip clarifying questions
keel orchestrate "<task>" --json <path>         # write final result JSON to file

Build (structured planning loop)

keel build start "<topic>"      # draft → distill REPL
keel build status [slug]        # show one or all builds
keel build approve <slug>       # approve summary; codify spec
keel build reject <slug> <reason>
keel build resume <slug>        # re-enter REPL for a paused build
keel build abort <slug>
keel build execute <slug>       # run approved spec via orchestrator

Reflect (end-of-session retrospective)

keel reflect                    # generate reflection for most recent session
keel reflect --session <id>
keel reflect ls                 # list recent reflections

Learn (framework self-improvement)

keel learn                      # step through pending proposals interactively
keel learn ls                   # list proposals (default: pending)
keel learn ls --status accepted
keel learn apply <proposalId>   # apply a proposal non-interactively (CI)

Goal (autonomous goal loop)

keel goal list [--status active|paused|achieved|abandoned]
keel goal create [title]
keel goal status <id>
keel goal evaluate <id>         # force immediate evaluation
keel goal approve <actionId>    # approve a pending action
keel goal reject <actionId> <reason>
keel goal pause <id>
keel goal resume <id>
keel goal abandon <id>

Knowledge base

keel kb upload <path>           # upload file or directory to workspace KB
keel kb reindex                 # re-embed all chunks with active model
keel kb stats                   # show docs, chunks, embedder, rerank state

Memory

keel memory list [--global]
keel memory add "<fact>" [--global]
keel memory show <pattern> [--global]
keel memory rm <entryId>

Keys and setup

keel keys list
keel keys set <name> [value]
keel keys test <name>
keel keys rm <name>
keel setup                      # interactive walkthrough for required keys

Doctor and workspace boot

keel doctor                     # env + project sanity checks
keel up                         # boot API + UI + database; open browser

All subcommands that read project files (verify, map, principles list) resolve architecture/data.ts and principles/index.ts from the current working directory, not from where @keel_flow/cli is installed. Run them from the root of the project you want to check.

keel up must be run from a Keel monorepo checkout (needs apps/api + apps/workspace). It loads .env from the repo root, warns if ANTHROPIC_API_KEY or KEEL_TOKEN_ENCRYPTION_KEY are missing, starts Docker/Postgres (or uses an existing DATABASE_URL), runs migrations, starts the API on port 3001 and the UI on port 3000, and opens the browser.

License

MIT