Copy as MD MD

CLI Reference

The public command surface returned by ctxe --help. Internal service and diagnostic entrypoints are intentionally not documented here.

ctxe <command> --help
ctxe --version

Output formats

Commands that expose -f, --format accept:

• human — readable terminal output (default)
• json — stable structured output
• compact — one-line-per-entry, pipe-friendly output

Format is not a global flag. It is available only on the commands listed with --format below.

Authentication

ctxe login

Start browser-based OAuth for the CTXE Server. Without a provider override, the browser shows a Google/GitHub chooser.

ctxe login
ctxe login --provider github
ctxe login --format json

ctxe whoami

Show the currently authenticated identity.

ctxe whoami
ctxe whoami --format json

-f, --format accepts human, json, or compact.

ctxe logout

Revoke the server session and remove local credentials.

ctxe logout

ctxe index

Incrementally parse a workspace, update its local index, and run configured embedding and enrichment phases.

ctxe index [OPTIONS] [PATH]

ctxe index .
ctxe index ./project --watch
ctxe index ./project --dry-run
ctxe index ./project --force --watch --format json

Plain ctxe index PATH remains a one-shot, catalog-only operation. With --watch, a complete durable report keeps exit 0 and a durable incomplete report keeps exit 2; both may record watch intent only after catalog activation succeeds. A hard failure or a foreground timeout without a durable report does not record intent, even though that timeout also exits 2.

Human, JSON, and compact stdout remain one index report in the existing schema. Watch persistence and daemon-reconcile status are written only to stderr. If global daemon configuration or watch persistence fails after catalog activation, the index report remains valid, stderr explains that watch registration was not fully confirmed, and the command exits 1. If durable watch persistence succeeds but the running daemon cannot be notified, the original exit 0 or 2 is preserved and the next daemon start or periodic reconciliation applies the saved intent.

--watch never enables or starts the daemon. After a durable index report, ctxe index PATH followed by the standalone, idempotent ctxe daemon watch PATH command is equivalent in watch intent.

ctxe status

Read index health and counts without migrating or modifying the workspace index.

ctxe status [OPTIONS] [PATH]

ctxe status .
ctxe status ./project --format json

ctxe ask

Investigate an indexed workspace with the goal-driven evidence planner: it searches the code with semantic search, reads, greps and outlines the source it finds, and composes an answer with evidence.

ctxe ask [OPTIONS] <QUERY>

ctxe ask "How does authentication work?"
ctxe ask "Find callers of UserService" --effort high
ctxe ask "Summarize the indexing pipeline" --workspace ./project --format json

ctxe fetch

Print full chunk bodies by the chunk IDs that semantic_search, ask_context or ctxe ask returned. Missing IDs are reported as not found; the command fails only when no ID exists.

ctxe fetch [OPTIONS] <CHUNK_ID>...

ctxe fetch 412 418
ctxe fetch --workspace ../other-project 412 --format json

ctxe records

List, search, read and re-compose saved Ask records. Use it to recover an Ask whose MCP client stopped waiting. Record IDs are workspace-local.

ctxe records list --kind ask --source mcp --limit 5
ctxe records get 42 --format json
ctxe records compose 42

Every subcommand accepts --workspace <PATH> and -f, --format.

ctxe config

Inspect built-in defaults and manage targeted global or workspace overrides. No config file is required. Workspace overrides live at .ctxe/config.toml; global overrides live at ~/.ctxe/config.toml.

ctxe config get ask_v4.effort
ctxe config set ask_v4.effort medium
ctxe config list --section ask_v4
ctxe config show --format json

ctxe ignore

Inspect and update which files a workspace indexes, without indexing.

ctxe ignore list --workspace ./project
ctxe ignore add 'target/**' --workspace ./project
ctxe ignore preview --workspace ./project --limit 200 --format json

Every subcommand accepts --workspace <PATH> and -f, --format.

ctxe daemon

Manage supervised background indexing and durable workspace watch intent. Watching is independent from accepted catalog membership; ctxe daemon watch PATH remains the standalone, idempotent alternative to composing that transition with ctxe index PATH --watch. Lifecycle commands do not accept workspace paths.

ctxe daemon watch ./project
ctxe daemon enable --now
ctxe daemon status --format json
ctxe daemon list
ctxe daemon unwatch ./project
ctxe daemon disable --now

ctxe workspace

List accepted catalog workspaces, or remove one workspace's CtxE data. This is separate from daemon watch intent.

ctxe workspace list
ctxe workspace list --format json
ctxe workspace remove /path/to/project

workspace list shows each accepted workspace with its watch intent. workspace remove removes recorded CtxE artifacts and catalog membership for the workspace. It preserves source files, workspace configuration, global configuration, and unrelated workspace state, and it can resume an interrupted cleanup.

ctxe update

Upgrade accepted workspace data to the format of the installed release. Upgrades resume where they stopped.

ctxe update [OPTIONS] [PATH]...

ctxe update
ctxe update /path/to/project
ctxe update status --format json

ctxe mcp

Start the MCP server over stdio. MCP clients launch this command as a subprocess. It exposes semantic_search and ask_context; see Tools Reference.

ctxe mcp

ctxe dashboard

Launch the local web dashboard and open it in a browser by default.

ctxe dashboard
ctxe dashboard --port 25007 --no-open

ctxe version

Show version and build information.

ctxe version
ctxe version --format json

-f, --format accepts human, json, or compact.