Quickstart

This walkthrough gets from a fresh install to one useful result in the local index.

Install and confirm setup

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

The installer installs the standalone CLI and runs ctx setup by default. Setup creates the ctx data root, initializes SQLite, discovers supported local history, and imports what it can read.

The install script downloads release metadata and the ctx binary. Setup, import, search, show, locate, and export operate on local provider history and the local ctx store.

If you need install-only behavior for packaging or CI, pass --no-setup to the installer:

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

Run setup yourself when you are ready to index local history:

ctx setup

Setup, import, search, and show do not call model APIs, require API keys, write into source repositories, or start a daemon.

Check available sources

ctx sources

Use this before debugging search results. It shows which provider history locations ctx found on this machine and whether they can be imported.

For scripts or agent workflows, use JSON:

ctx sources --json

In source JSON, native_import: true means ctx has parser support for that provider's history format. importable: true means the source exists on this machine and has supported data available to import.

Search for a remembered detail

Search for a phrase, filename, tool output, error, decision, or feature name from earlier work:

ctx search "failed migration"

Search returns cited snippets with ctx-owned IDs. The two IDs you will use most often are:

• ctx_event_id, which points at one matching event;
• ctx_session_id, which points at the whole session that contained it.

Search defaults to --refresh auto. Today that means ctx may run a bounded best-effort refresh of discovered Codex session sources before querying the index. If refresh cannot run, auto still searches the existing index.

Use --refresh off when you want only the current index:

ctx search "failed migration" --refresh off

Use --refresh strict when a failed refresh should fail the search:

ctx search "failed migration" --refresh strict

--limit defaults to 20 and is capped at 200.

Open the matching event

When a result has a ctx_event_id, open the surrounding context:

ctx show event <ctx-event-id> --window 3

Increase the window when the answer depends on the lead-up or the follow-up:

ctx show event <ctx-event-id> --window 8

Open the full session

When the event is promising, open the session:

ctx show session <ctx-session-id> --mode lite

Use JSON when another tool will consume the result:

ctx show session <ctx-session-id> --format json
ctx show event <ctx-event-id> --format json

Locate the original source

Use locate when you need the provider-owned file or cursor behind a ctx result:

ctx locate session <ctx-session-id>
ctx locate event <ctx-event-id>

If the original file has moved or been deleted, ctx can still return indexed text from SQLite. Source availability is reported when ctx has enough information to check it.

Search as JSON

JSON search output is useful for agents and local scripts:

ctx search "sqlite migration failed" --repo ctx --limit 5 --json

Search JSON includes result metadata, citations, suggested next commands, and a top-level freshness object that describes the refresh mode and outcome.

A compact first-run script

curl -fsSL https://ctx.rs/install | sh
ctx status
ctx sources
ctx search "build failure" --limit 5
ctx show event <ctx-event-id> --window 3
ctx show session <ctx-session-id> --mode lite

If search misses work you expect to find, run ctx sources --json first. A supported provider can still be missing, empty, or unavailable on a particular machine.