Context Engine CLI reference

Overview

Installing promptev-context-engine (Python 3.12+) or @promptev/context-engine (Node 22+) puts a context-engine executable on your path. The four subcommands behave the same in both; the few differences are called out where they occur.

Running the command

Install the package and call context-engine, or run it once without installing. Remember the driver either way.

# Installed in your environment
pip install "promptev-context-engine[postgres]"
context-engine migrate --database-url postgresql://user:pass@localhost:5432/mydb

# Or without installing, via uv
uvx --from "promptev-context-engine[postgres]" context-engine migrate \
    --database-url postgresql://user:pass@localhost:5432/mydb

# Installed in your project
npm install @promptev/context-engine pg
npx context-engine migrate --database-url postgresql://user:pass@localhost:5432/mydb

# Or without installing (pg is an optional peer, so name it)
npx -p @promptev/context-engine -p pg context-engine migrate \
    --database-url postgresql://user:pass@localhost:5432/mydb

context-engine --help and context-engine <command> --help print the flags.

migrate

Creates or upgrades the engine’s schema. Run it on every deploy: it is idempotent, and the migration history ships inside the package, so you need no alembic.ini or copied scripts.

context-engine migrate --database-url postgresql://user:pass@localhost:5432/mydb --dim 1536

# Later, add the graph tables on top of the same database
context-engine migrate --database-url postgresql://user:pass@localhost:5432/mydb --dim 1536 --graph

npx context-engine migrate --database-url postgresql://user:pass@localhost:5432/mydb --dim 1536

# Later, add the graph tables on top of the same database
npx context-engine migrate --database-url postgresql://user:pass@localhost:5432/mydb --dim 1536 --graph

What it does

The same step is available from code:

from context_engine.cli import run_migrate

run_migrate("postgresql://user:pass@localhost:5432/mydb", dim=1536, graph=False)

import { runMigrate } from "@promptev/context-engine";

await runMigrate("postgresql://user:pass@localhost:5432/mydb", { dim: 1536, graph: false });

mcp

Serves the engine’s MCP tools (search_knowledge_base, search_tools and execute_tool) over streamable HTTP. It is a quick way to try the MCP surface, not a deployment target.

pip install "promptev-context-engine[postgres,mcp]"

export CE_EMBEDDING__PROVIDER=openai
export CE_EMBEDDING__MODEL=text-embedding-3-small
export CE_EMBEDDING__API_KEY=sk-...

context-engine mcp --database-url postgresql://user:pass@localhost:5432/mydb --port 8080
# streamable HTTP endpoint: http://127.0.0.1:8080/mcp

npm install @promptev/context-engine pg @modelcontextprotocol/server @modelcontextprotocol/node

export CE_EMBEDDING__PROVIDER=openai
export CE_EMBEDDING__MODEL=text-embedding-3-small
export CE_EMBEDDING__API_KEY=sk-...

npx context-engine mcp --database-url postgresql://user:pass@localhost:5432/mydb --port 8080
# prints: context-engine mcp listening on http://127.0.0.1:8080

Configuration it reads

Serving MCP for real

from context_engine import create_mcp_app, UNSCOPED

# Your own ASGI app, behind your own auth: principals come from the caller.
app.mount("/mcp", create_mcp_app(engine, principals=my_principals, scope=UNSCOPED))

import { createMcpApp, UNSCOPED } from "@promptev/context-engine";

// Behind your own auth: principals come from the caller.
const handler = await createMcpApp(engine, { principals: myPrincipals, scope: UNSCOPED });

principals and scope are both required: there is no default caller identity. Pass a narrower scope than UNSCOPED when the tool should reach only some sources. The knowledge tool reference covers the tool’s actions.

check-acl-exposure

Answers one question against your own database: for callers who can see only part of the corpus, does the vector leg return what an exact search would? It compares a bare scoped query and the engine’s own retrieval path, both scored against an exact scan computed inside Postgres.

context-engine check-acl-exposure --database-url postgresql://user:pass@localhost:5432/mydb

# In a deployment pipeline: fails the step only when the verdict is "exposed"
context-engine check-acl-exposure --database-url "$DATABASE_URL" --samples 200 --top-k 20

npx context-engine check-acl-exposure --database-url postgresql://user:pass@localhost:5432/mydb

# In a deployment pipeline: fails the step only when the verdict is "exposed"
npx context-engine check-acl-exposure --database-url "$DATABASE_URL" --samples 200 --top-k 20

Verdicts

The report prints recall and the share of empty results per scope, then a verdict from the worst scope tested:

On exposed the report suggests what to check: pgvector 0.8 or newer, a GIN index on the ACL column, and that searches go through the library rather than raw SQL.

bm25-enable, bm25-disable, bm25-compact

The bm25 keyword ranking is experimental and opt-in per database. Measured on five public datasets it is not a default and does not improve default search. Nothing changes for a database that does not use it: the migration adds two small tables and some SQL functions and never touches the chunk table. bm25-enable installs four triggers on the chunk table (taking its lock briefly, with a 2-second timeout and retries) and counts the chunks already stored, one source at a time, without blocking ingest. Run it again at any time; it recounts. Until it has finished, a bm25 search ranks with ts_rank_cd and reports why. Enabled, each chunk write adds one small statistics row and two writers never wait on each other. A source is compacted on its own after a write once it holds more than search.bm25.compact_after_deltas rows (default 1000); bm25-compact does the same for every source on demand, which matters only when that setting is turned off. Recounts and compactions take a per-source lock that only maintenance uses, so bm25-enable, bm25-compact and the automatic compaction are safe to overlap with each other and with ingest, for example several replicas enabling at startup. bm25-disable removes the triggers and statistics. Each takes --database-url only. The library calls are enable_bm25(), disable_bm25() and compact_bm25_stats()enableBm25(), disableBm25() and compactBm25Stats() on the engine.

context-engine bm25-enable --database-url "$DATABASE_URL"
context-engine bm25-compact --database-url "$DATABASE_URL"   # only needed with automatic compaction off
context-engine bm25-disable --database-url "$DATABASE_URL"

npx context-engine bm25-enable --database-url "$DATABASE_URL"
npx context-engine bm25-compact --database-url "$DATABASE_URL"   # only needed with automatic compaction off
npx context-engine bm25-disable --database-url "$DATABASE_URL"

install-skill

Copies the agent skill shipped inside the package (a SKILL.md stating the library’s invariants, such as TRUSTED instead of the deprecated principals=None) into a .claude/skills/context-engine/ directory. It is an explicit command rather than an install hook, because the file becomes instructions inside your agent.

context-engine install-skill            # -> ./.claude/skills/context-engine/SKILL.md
context-engine install-skill --global   # -> ~/.claude/skills/context-engine/SKILL.md
context-engine install-skill --dir ../app
context-engine install-skill --print > context-engine-skill.md

npx context-engine install-skill            # -> ./.claude/skills/context-engine/SKILL.md
npx context-engine install-skill --global   # -> ~/.claude/skills/context-engine/SKILL.md
npx context-engine install-skill --dir ../app
npx context-engine install-skill --print > context-engine-skill.md

Exit codes