CLI reference

Setup and health

ctx setup
ctx setup --catalog-only
ctx setup --json
ctx setup --progress json --json
ctx status
ctx status --json
ctx doctor
ctx doctor --json
ctx validate
ctx validate --json

Setup creates local storage, discovers supported provider history, catalogs Codex sessions, imports discovered sources, and optimizes the local search index. Health checks read the local store. These commands do not change shell startup files, install repository integrations, write into source repositories, call model APIs, require API keys, or start background processes.

Sources

ctx sources
ctx sources --json

sources lists provider history locations that ctx knows how to check on this machine. JSON rows include provider, path, status, native import support, importability, source format, raw retention, and any unsupported reason. native_import: true means ctx has parser support for that provider format. importable: true means the current path has supported data available to import.

Import

ctx import
ctx import --all
ctx import --provider codex
ctx import --provider pi
ctx import --provider claude
ctx import --provider opencode
ctx import --provider antigravity
ctx import --provider gemini
ctx import --provider cursor
ctx import --provider copilot-cli
ctx import --provider factory-ai-droid
ctx import --path ~/.codex/sessions
ctx import --provider opencode --path ~/.local/share/opencode/opencode.db
ctx import --resume
ctx import --json
ctx import --progress json --json

import explicitly indexes provider history into the local SQLite store. The normal first-run path is ctx setup, which already imports discovered sources. Use import to repair, re-run, resume, or target a specific provider or path. Current --resume output marks an idempotent rescan; provider-native cursor resume is not yet a universal contract.

List, show, locate, export, and search

ctx list
ctx list --json
ctx show session <ctx-session-id> --mode lite
ctx show session <ctx-session-id> --format json
ctx show event <ctx-event-id> --window 3
ctx show event <ctx-event-id> --format json
ctx locate session <ctx-session-id>
ctx locate event <ctx-event-id>
ctx export session <ctx-session-id> --mode full --format markdown --out transcript.md
ctx search "build failure"
ctx search "build failure" --json
ctx search "sqlite storage" --provider opencode
ctx search "token budget" --refresh off
ctx search "token budget" --refresh strict

JSON output is intended for local agents and scripts. Treat it as private local data unless it has been reviewed and redacted.

search defaults to --refresh auto, which quietly refreshes discovered Codex session sources before querying indexed sessions and events. Use --refresh off to search the existing index without refreshing, or --refresh strict to fail when the pre-search refresh cannot run or import successfully. --limit is capped at 200. Search JSON includes a top-level freshness object describing the refresh mode and outcome.

Progress output

ctx setup --progress json --json
ctx import --progress json --json

setup and import accept --progress auto|plain|json|none. Progress writes to stderr and does not change structured stdout, so --json command results remain a single JSON object.