Docs / CLI quickstart

CLI quickstart

Search Contextify from the terminal.

The contextify CLI reads your local Contextify database. On macOS, that is the same database used by the Mac app. It also installs Total Recall skills and runs cloud sync commands.

Use it when you want fast local search, scriptable status checks, or Cloud setup on macOS and Linux.

Install path by platform

Install What to do Why
Mac DMG Open Contextify once. The app installs or repairs the CLI from Settings → CLI. DMG builds can install the local shim and Total Recall skill directly.
Mac App Store brew install PeterPym/contextify/contextify-query The sandboxed app cannot write the CLI into system paths.
Linux Install the Linux release binary and put contextify on your PATH. Linux is CLI-first and does not have Contextify.app.

Verify the CLI

contextify --version
contextify status
contextify doctor

status checks the database. doctor checks the CLI and skill install surface. If doctor reports missing skills, run: 

contextify install-plugin
contextify doctor

The legacy command name contextify-query still works, but contextify is the command to document and teach.

On Linux, use contextify ingest to index transcripts before searching. Use contextify install-service when you want periodic background ingestion.

Run your first local search

Start with a distinctive phrase, task ID, branch name, file path, or error string from an AI session. 

contextify search "sign-in handoff" --limit 5
contextify search "ct 1703" --days 30
contextify search "cloud sync" --project . --limit 10

Hyphenated identifiers are tokenized by search. If ct-1703 does not match as expected, try "ct 1703" or nearby words from the same conversation.

Search only sees history that has been indexed locally. If a fresh conversation is missing, run ingestion first or let the Mac app finish processing.

Connect Cloud from the CLI

Hosted Cloud setup starts the sign-in handoff by default: 

contextify cloud setup
contextify cloud status
contextify cloud sync

For self-hosted setup, prefer the interactive prompt when you can. It avoids putting an API key in your shell history. 

contextify cloud setup --url https://your-server.example.com
contextify cloud projects
contextify cloud projects --exclude my-private-project
contextify cloud sync

cloud projects --exclude changes Project Sync for this Mac. Excluded projects stop future uploads from this device for that project.

For headless automation, --key is supported. Treat the command transcript as sensitive if it contains a real key. 

contextify cloud setup --url https://your-server.example.com --key ctx_REDACTED --no-input

Related docs

Total Recall for Claude Code

Install, verify, and use the assistant skill.

Total Recall for Codex

Codex-specific skill locations and verification.

Cloud sync troubleshooting

Understand offline, error, deferred, and attention states.

Ingestion and syncing

Separate local transcript processing from Cloud upload and download.

Last updated: May 6, 2026