Command Reference

All commands are run from a project directory that has been initialized with keel init.

Global flags

  • --json -- Output as structured JSON
  • --llm -- Output as token-optimized LLM format
  • --verbose -- Include info block and diagnostic messages on stderr
  • --max-tokens N -- Token budget for LLM output (default: 500)

keel init

Initialize keel in a repository.

terminal

$ keel init

Creates .keel/ directory, detects languages, creates .keelignore, installs a pre-commit hook, and detects AI tool integrations. Performance: <10s for 50k LOC. Fails if .keel/ already exists -- run keel deinit first.

keel map

Build or rebuild the full structural graph.

terminal

$ keel map [--depth 0-3] [--scope modules] [--strict]

  • --depth N -- Output detail level. 0 = summary. 1 = modules + hotspots (default). 2 = functions with signatures. 3 = full graph.
  • --scope <modules> -- Comma-separated module names to restrict output
  • --strict -- Exit non-zero on any ERROR-level violations

Parses every source file with tree-sitter, applies per-language resolvers (Oxc for TS, ty for Python, heuristics for Go, rust-analyzer for Rust), builds call/import/contains edges, and stores everything in .keel/graph.db. Performance: <5s for 100k LOC.

keel compile

Incrementally validate code after changes.

terminal

$ keel compile [file...] [flags]

  • --batch-start / --batch-end -- Defer non-critical checks during rapid scaffolding
  • --strict -- Treat warnings as errors
  • --suppress <code> -- Suppress a specific error/warning code
  • --changed -- Validate only git-changed files
  • --since <commit> -- Validate files changed since a commit

Clean compile: exit 0, empty stdout. Violations: exit 1 with structured output. Performance: <200ms for a single file.

examples

# Validate a single file

$ keel compile src/auth.ts

# Batch mode for scaffolding

$ keel compile --batch-start

# ... create files ...

$ keel compile --batch-end

# Minimal output for LLM

$ keel compile --depth 0 src/auth.ts --llm

keel discover

Look up a symbol's callers, callees, and graph context.

terminal

$ keel discover <hash> [--depth N] [--suggest-placement]

  • --depth N -- Number of hops to traverse (default: 1)
  • --suggest-placement -- Return top 3 placement suggestions

Performance: <50ms.

keel where

Resolve a hash to its file and line number.

terminal

$ keel where a7Bx3kM9f2Q

src/auth.ts:42

keel explain

Show the resolution reasoning chain for an error.

terminal

$ keel explain <error_code> <hash> [--depth 0-3] [--tree]

  • --depth N -- Resolution chain depth. 0 = summary. 3 = full chain.
  • --tree -- Human-readable tree output

keel fix

Generate fix plans for violations, optionally applying them.

terminal

$ keel fix [hash...] [--file <path>] [--apply]

  • --file <path> -- Restrict to violations in a specific file
  • --apply -- Write fixes to disk and re-compile to verify

Without --apply, outputs a plan only (read-only). With --apply, writes changes then re-compiles to confirm the fix is clean.

keel name

Suggest names and file locations for new code.

terminal

$ keel name "validate user authentication"

  • --module <path> -- Constrain suggestions to a specific module
  • --kind <type> -- Kind of entity: fn, class, method

keel serve

Run a persistent server for real-time enforcement.

terminal

$ keel serve [--mcp] [--http] [--watch]

  • --mcp -- Expose as an MCP tool server over stdio
  • --http -- Start HTTP API on localhost:4815
  • --watch -- Auto-recompile on file changes

Memory usage: ~50-100MB.

keel stats

Display graph statistics and compilation history.

terminal

$ keel stats [--json]

keel deinit

Remove all keel-generated files. Deletes .keel/, .keelignore, and the pre-commit hook. Does not modify source code.

Exit codes

  • 0 -- Success, no violations
  • 1 -- Violations found
  • 2 -- Internal error (not initialized, database error)