CLI Reference

Command-line interface commands for managing ContextOS in your repository.

Implementation Sourcesrc/index.ts

Usage

The ContextOS binary is installed globally or invoked via npx. All commands are executed within the context of your current working directory (which is expected to be a Git repository).

npx contextos <command> [options]

Commands

init

Initializes ContextOS in the current repository, creates the local .contextos state directory, writes missing MCP configuration entries, and schedules indexing in the background. The command returns before a large repository has necessarily finished indexing; use contextos status to check readiness.

contextos init

query

Execute a natural language search against the repository. This runs the RRF Hybrid Retriever and Graph Expansion engine to return the most contextually relevant codebase snippets.

contextos query "How is the authentication token validated?"

Options

  • --json: Output a machine-readable object containing intent, chunks, compiled context, and token count.

watch

Starts a background filesystem watcher (using chokidar). When you save a file in your editor, the watcher instantly diffs the AST and surgically updates the SQLite graph. This allows the index to stay up-to-date with zero manual re-indexing.

contextos watch

daemon

Manages the per-project background daemon. MCP clients normally launch serve, which connects to this daemon over a private local socket; the daemon does not expose an HTTP port.

contextos daemon start
contextos daemon status
contextos daemon stop

reindex

Stops the project daemon, deletes the local database and its SQLite sidecars, and invokes initialization again. Use this after changing ignore rules or when you need a clean index. Back up manual knowledge first because rebuilding removes database-resident facts, feedback, and session history.

Note: Normal upgrades can schedule a background rebuild when the index format changes. Explicit reindexing is for a deliberate clean rebuild, and contextos reindex --embeddings backfills vectors without wiping an existing database.

contextos reindex

status

Prints the current indexing metrics of the repository, including chunk counts, total relationship edges, and the SQLite database file size.

contextos status

serve

Runs the MCP stdio bridge used by an AI client. It reads and writes JSON-RPC on standard streams and connects to the project daemon; run it manually only when integrating a client that starts commands itself.

contextos serve

clean

Removes indexed junk paths such as build output and node_modules from the local and resolved global databases. It does not stop the daemon or rebuild the index. Pass --rebuild for the destructive local database reset, and --global to include the shared global database.

contextos clean
contextos clean --rebuild
contextos clean --global