CLI reference
every command, with the flags that matter
| Command | Description |
|---|---|
deja "query" | Search indexed history. Filters: --harness --project --since --role --limit --re --json. |
deja show <id> | Read one session. Machine reads use an exact composite identity: --harness name --json, with bounded --offset and --limit message windows. |
deja ctx "query" | Print a context digest to stdout (for piping into an agent). |
deja blame <path> | Sessions that discussed a file, most specific first. |
deja files <topic> | Which files were opened or edited while that subject was being worked on, ranked by how specific each one is to it. --project, --limit. Reads the file and command records deja extracts from Claude Code, opencode, Cursor and Codex transcripts. |
deja friction | Errors that recur across three or more separate sessions, with the harnesses that hit them and the newest occurrence. Specific failures only — a missing binary, an uninstalled module — not generic Traceback lines. --limit. |
deja fix "<error>" | The command this machine ran after that same error before, when the error did not come back. Paste the failing output or pipe it in; matched on the error itself, not its words. Evidence from your own history, not a guaranteed fix. --limit. |
deja how "<tool>" | How this machine actually runs a thing — the real command with the real flags, from what agents ran before, ordered by how many separate sessions ran it. Query the tool or target (go test, docker compose, a script name). Command records stay out of ordinary search, so this is the only way to reach them. --project, --limit. |
deja restore <path> | Spans an agent replaced in that file, newest first; --span n prints one and -o file writes it. Never writes over the original, and flags a span that passed through redaction. |
deja remember "text" | Store a durable note. --project optional; --tag (repeatable) attaches keywords that boost matching queries. |
deja forget | Remove sessions by --session/--project/--before; --dry-run, --list, --unforget <id>. |
deja stats | Totals, top projects, activity, and how many replaced spans deja restore could hand back. --card (SVG), --html (timeline), --redaction, --json. --impact prints the measured impact report (recalls, reuse, distillation ratio) with the arithmetic labeled. |
deja | Bare, on a terminal: the living brief — today's activity, recalls served, déjà vu moments, a question asked in more than one session, the piece of work agents have re-used most, an error several sessions hit, a suggested search from your own history. |
deja log | Audit trail: recent recalls and injections; --last prints the most recent injected digest verbatim; --json. |
deja last [n] | Recent sessions. --project, --harness, --since, --role, --json. |
deja resume <id> | Reopen a session in the agent that wrote it. Prints the command; --exec runs it. Where the harness scopes its session list to one project, the command carries the cd that makes the id resolve; where a harness has no way to reopen a conversation from a terminal, it says so rather than printing something that would start a new one. The matrix has the column. |
deja warmup | Build or refresh the index without searching — for a shell profile or a provisioning script. |
deja statusline | One line for an agent's status bar: today's sessions and what deja has served, and — when the host pipes its session payload — the file this session is working on most with what earlier sessions decided about it. Silent when no earlier session touched it. |
deja completion <bash|zsh|fish|powershell> | Print a completion script for your shell. pwsh is accepted as an alias for PowerShell. |
deja uninstall <target|--all> | Remove deja's wiring from an agent. Other servers in shared config files are left alone. |
deja version | Print the version. |
deja sources | Discovered stores per harness, with redaction counts. |
deja install <target|--all|--auto> | Wire MCP recall (and hooks) into your agents. |
deja embed | Build the semantic vector sidecar from an embedding endpoint. |
deja sync export/import/ssh | Move redacted memory between machines. |
deja sync forget <host> | Drop a machine deja knows, so a bare deja sync stops trying it. |
deja promote <id> | Distill a session into a curated note: quoted evidence with provenance and a lifecycle state (--state accepted|rejected|superseded|stale). Corrections append; the note outranks the raw transcript in recall. --to path also appends a Markdown block for repo-visible notes. --tag adds keywords; promoting into ground another accepted note already covers prints a conflict warning naming the older note. |
deja view | Browse memory in one self-contained local HTML: sessions with previews, recall audit trail, curated notes. --out path, --no-open. |
deja doctor | Diagnose stores, wiring, index and version. --json, --offline. --deep re-parses a sample of source files and resolves postings to prove the index against the sources; exits non-zero on drift. |
deja bench recall|context | Reproducible search-quality and context-readiness benchmarks. |
deja update | Update a standalone install (Homebrew/npm update via the package manager). |
deja index | Read what the agents on this machine have written since the last pass. --rebuild reads everything again, which is what a parser change needs. |
deja mcp | Run the MCP server on stdio. deja install wires this for you; run it by hand only to debug a client. |
deja share <id-prefix> | A redacted digest of one session, for pasting to someone else. |
deja handoff [id-prefix] | What the next agent needs to carry on: the problem, what was tried, what was settled, and where it stopped. --to <agent> phrases it for that agent and --exec opens it there. |
deja check - | Read a plan from stdin and print what this machine's history says about the things in it — what was decided, and what went wrong last time. |
Bare
deja on a terminal prints the living brief; piped or redirected it prints the usage summary, which deja --help also shows, and any command takes --help for its flags. Everything is offline except update, sync ssh and the doctor version check.