Install and index local history

Install the CLI

The canonical installer for the standalone search CLI is https://ctx.rs/install. It installs the binary, installs the bundled agent-history skill, and runs ctx setup by default so discovered local history is indexed before the installer exits.

macOS, Linux, and FreeBSD:

curl -fsSL https://ctx.rs/install | sh

Windows PowerShell:

irm https://ctx.rs/install.ps1 | iex

Use --no-setup on Unix or -NoSetup on Windows for install-only CI, packaging, or review flows. Install-only mode skips both the skill step and history indexing unless you pass a skill target explicitly:

curl -fsSL https://ctx.rs/install | sh -s -- --no-setup

The installer downloads release metadata and the ctx binary, then verifies release metadata and SHA-256 checksums before installing artifacts. It also writes a managed install marker so ctx upgrade can apply signed CLI updates, installs generated man pages unless --no-man or CTX_INSTALL_NO_MAN=1 is used, and installs ctx-agent-history-search unless --no-skill or CTX_INSTALL_NO_SKILL=1 is used. Target a specific skill folder with --skill-agent codex, repeat --skill-agent, or use --all-skill-agents; Windows exposes the same controls as -NoSkill, -SkillAgent, and -AllSkillAgents. Hosted binaries are published for Linux x64, Linux ARM64, macOS, Windows, and FreeBSD. Setup and search do not send transcript text, prompts, or indexed search content to a model API. See the Privacy Policy before installing when you need strict command-metadata controls.

When working from source:

cargo build -p ctx
cargo install --path crates/ctx-cli

Create local storage

ctx setup
ctx status

Setup creates the configured ctx data root, initializes SQLite, writes config.toml when missing, discovers known provider history paths, catalogs local history sources, imports discovered native provider sources, optimizes the local search index, and prints next steps. The default data root is ~/.ctx.

Use a different root for tests:

ctx --data-root /tmp/ctx-demo setup
CTX_DATA_ROOT=/tmp/ctx-demo ctx status

Setup is local with respect to provider history and storage. It does not write to source repositories, call model APIs, or require API keys. Official installer-managed binaries can run a signed background auto-upgrade check after later successful non-JSON commands; that updater does not collect provider history.

Set up your agent

The installer runs the bundled agent-history skill installer by default. To refresh the skill manually:

ctx integrations install skills

See Install the ctx skill for agent targeting, project installs, and manual fallback instructions.

Import and search

ctx sources
ctx import --all
ctx search "failed migration"
ctx show session <ctx-session-id>
ctx show event <ctx-event-id> --window 3

Use JSON output for scripts and exact field extraction:

ctx sources --json
ctx import --resume --json
ctx search "sqlite migration failed" --workspace ctx --json
ctx show session <ctx-session-id> --format json
ctx show event <ctx-event-id> --format json

Use repeatable --term when you need to search several explicit words or phrases:

ctx search --term "sqlite migration" --term rollback --term cursor

Built-in docs and upgrades

ctx docs search "upgrade"
ctx docs show cli-reference
ctx docs man --print ctx
ctx upgrade status
ctx upgrade check

ctx docs is embedded in the binary. ctx upgrade works only for official installer-managed binaries with a matching sidecar marker; source builds and package-manager installs stay unmanaged.