CLI reference
every command, with the flags that matter
The screen
Bare deja in a terminal opens a full-screen search over every agent's history. It starts on the sessions behind your uncommitted change, then recent ones in this project grouped by day, each card led by the question asked. Type and the list updates as you type; tab switches between this project, all projects and Deleted (sessions their agent deleted that deja still holds). The preview shows how the session went, turn by turn, and the files it edited. A search that finds nothing names the other projects that have it, or the spelling your history uses. Press ? for the keys:
| Key | Does |
|---|---|
↑↓, 1-9 | Pick a session. ↑ in an empty box brings back past searches. |
a | Filter by agent. The box takes filters too: an agent with a colon (codex:), today, yesterday, week, month, and in:<project>. |
↵ | Open the session at the match. Inside: / finds a word in the session, n / N next and previous match, ] / [ next and previous turn you asked, t unfolds long messages, g / G top and bottom, esc back to the list. |
r | Resume in the agent that wrote it. |
o or ctrl-o | Continue in any agent: the session's context goes to the agent you pick and it starts. The agent you used last is picked and marked; agents not installed fold into one line. |
c or ctrl-y | Copy the context. |
R | Put a deleted session back where its agent can reopen it (deja resume <id> --write-back). |
ctrl-k | Every command by name, including copy the session id (i), copy the project path (p) and forget the session (F), which asks first. |
ctrl-u, ctrl-w | Clear the box, drop a word. esc clears or goes back; q quits from the list. |
The mouse works too: click a card, double-click to open, scroll. DEJA_THEME=light or dark picks the palette when the terminal does not say; DEJA_THEME=dracula paints it in Dracula. DEJA_TUI=0 or TERM=dumb prints the text brief instead.
Commands
| Command | Description |
|---|---|
deja "query" | Search indexed history (deja search "query" is the same, for a query that starts with a dash). Filters: --harness --project --since --role --session --limit --all --re --no-embed --json. --sort date lists the newest match first; the default is --sort relevance. --limit takes 1–100; without it an exact match shows 15 hits (--all shows every one) and a ranked fallback shows its own window. |
deja show <id> | Read one session, message by message. The id is the one a search hit, deja last or deja log prints; a unique prefix is enough. --harness picks one when the prefix matches sessions from two agents; --offset and --limit (50 messages by default) page through the messages; --json. |
deja ctx <query|id> | Print a context digest to stdout, for pasting or piping into an agent: the best-matching session for a query, or the session an id names, followed by the code it changed, each edit as the lines it removed and added. |
deja recall "words" | The page the MCP recall tool gives an agent: about 4 KB, this project first. For skills and scripts that run deja through the shell. --project, --harness, --limit (5 sessions by default, within the same 4 KB), --offset for the next page, which the page names at its end. |
deja blame <path>[:<line>] | Sessions that discussed a file, most specific first. With a line: the commit that last changed it and the session whose edit replaced the text that commit deleted, or one sentence saying why that cannot be answered. Answers from the project of the working directory, since a path names a file in this checkout; --all-projects asks the whole machine. --all lists every session rather than the top 10 (blame takes no --limit), --project, --harness, --since, --json; --attribution prints the line answer alone and --git-note writes it as a git note. |
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. Answers from the project of the working directory; --project asks about another one, --all-projects asks the whole machine. --limit bounds the list (10 by default); --json. Reads the file and command records deja extracts from transcripts; most agents it reads write them. |
deja secrets | Which credentials your agent transcripts are carrying, from deja’s own redaction markers — provider keys, private keys, connection strings, session cookies — with the harness, project, date and the file still holding each one. Never the value: deja’s copy is redacted. The assignment and entropy rules are a count at the bottom rather than a list. --scrub rewrites the transcripts that still hold one, putting the same [redacted:kind] marker where the value was and keeping the original beside the file; it touches only the kinds the report names, refuses a session an agent is in, and says how many findings it could not reach — a store with no per-session file (opencode, Zed, Cursor IDE, Copilot Chat) cannot be rewritten at all. --limit (10 sessions on the screen by default, 0 for all), --json, --scrub, --dry-run. |
deja tests | Your build and test runs as a series, week by week, from the commands and output already in the transcripts — nothing new is captured. A run counts as failed or passed only when the runner’s own verdict line says so; the third band is the runs whose verdict was filtered out of the pipeline before the output was recorded. Then the tests that failed on more than one day, which is the cut that separates one afternoon’s fixing from a test that keeps coming back. --limit (8 tests by default, 0 for all), --json. |
deja recap | What the last week settled, quoted from the sessions themselves and grouped by project, with the harness, date and session id behind every line. Writes no prose of its own. Because the output is meant for a PR description or a standup message, every line goes through a second redaction pass on top of the index’s — addresses, internal hostnames, emails and home paths — and the screen says what that removed. --since, --limit (12 sessions by default, 0 for all), --json. |
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 (10 by default), --json. Each row prints an id: --settle <id> marks the wall fixed so the session-start block stops naming it, --unsettle <id> takes that back. A settled wall hit again in a newer session is open again. |
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 (3 by default), --json. |
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. Answers from the project of the working directory; --project asks about another one, --all-projects asks the whole machine. --limit bounds the list (8 by default); --json. |
deja delete <id> | Erases a session from its agent and from deja's index, after asking; there is no undo. --dry-run lists the files, --yes skips the question. Claude Code, Codex, Cursor CLI, Gemini CLI, Qwen Code, Copilot CLI, Cline CLI, Kimi Code, Grok, dsh, pi, Senpi, OpenClaw and Antigravity sessions are removed as files; opencode through opencode session delete. A running session is refused, and so are agents whose session list deja has not checked. D in the TUI does the same. |
deja restore <path> | Spans an agent replaced in that file, newest first: the newest 30, --all every one. --span n prints one and -o file writes it. Never writes over an existing file unless --force is given, 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, --all-matches when a prefix names more than one session, --list, --unforget <id>. It names forks that still hold a copy of the forgotten turns, with the command to forget them too. |
deja stats | Totals, top projects, activity, and how many replaced spans deja restore could hand back. --card (SVG, PNG in the browser), --html (timeline), --redaction, --json, and the same --project --harness --since --role filters as search. --impact prints the measured impact report (recalls, reuse, distillation ratio) with the arithmetic labeled. --year is the last twelve months of your own work in one screen — sessions and agents, the files and commands the agents worked through, what was asked twice, what they kept tripping over — with every number labelled with the arithmetic behind it and the outbound redaction pass applied, because it is written to be shown to other people. |
deja | Bare, on a terminal: the interactive screen (above). Piped, it prints what is indexed and three commands to start from. |
deja brief | Today's activity as text: 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. This is what bare deja printed before the screen; DEJA_TUI=0 brings it back there. |
deja log [n] | Audit trail: recent recalls and injections; --last prints the most recent injected digest verbatim; --json. |
deja last [n] | Recent sessions. --project, --harness, --since, --role, --from <machine> (sessions synced from one machine; local for this one), --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. For a transcript the agent has since deleted, --write-back first writes it back into the agent's store from what deja indexed, so the command reopens it; the file holds the conversation, not the tool calls. It never replaces a file. --app opens a Codex CLI session in the ChatGPT desktop app instead, on macOS and Windows. The matrix has the column. On the screen, r resumes the selected session and R puts a deleted one back. |
deja wip | What the last session in this project was doing: the task, what it settled, the files in flight, the last command and whether it failed. Derived from the transcript — nothing is asked of the agent, and nothing is stored. After a compaction a session spends a median of 28 actions before its next edit, against 10 from a cold start; this is the context it is missing. --json. |
deja warmup | Build or refresh the index without searching — for a shell profile or a provisioning script. With automatic indexing off it only reports the index. |
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 install statusline puts it in Claude Code's status bar; the -auto targets for Cursor CLI, Copilot CLI, Qwen Code, CodeBuddy Code, Grok Build, Kimi Code, TRAE CLI and Antigravity CLI put it in theirs, and leave one you already set up. opencode and Kilo CLI get it through a TUI plugin, VS Code through a small local extension vscode-auto adds, dsh under its web composer, and OpenClaw as a deja tab in the Control UI. |
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 help [command] | Every command with a line on each, or one command's usage, description and examples. deja <command> --help says the same, except after aider and goose, where it is that tool's own help. |
deja sources | Discovered stores per harness, with redaction counts. |
deja install <target|--all|--auto> | Wire MCP recall (and hooks) into your agents. --all wires MCP recall into every agent found on this machine; --auto adds the hooks and plugins each one takes. --no-guidance skips the instruction block, --no-index skips the first index build, --force replaces a deja skill file you have edited since deja wrote it. deja help install lists the targets. |
deja rules [sync] | Your standing rules in one file, ~/.config/deja/rules.md. deja rules lists each installed agent's global rules file and whether its copy is in sync; sync writes the rules there as a marked block, leaving the rest of the file alone, and an empty file takes the copies back out. Agents whose global rules file deja has not verified are listed and left alone. |
deja rules candidates [--json] [--limit n] [--since 90d] | The turns where you corrected an agent, across every tool on the machine, each numbered with the session it came from — every one by default, the newest n with --limit. deja does not group them: the same rule comes back in different words each time. Ask your agent to suggest your rules and its skill runs this, groups the list, and shows the rules with the turns behind them; nothing goes into rules.md until you pick. Writes nothing. |
deja embed | Build the semantic vector sidecar from an embedding endpoint. |
deja sync export/import/ssh | Move redacted memory between machines. Bare deja sync exchanges with every machine deja knows; sync ssh <host> pushes, --pull pulls, --both does both, --full sends everything rather than what changed. sync export also takes --include-imported and --peer name. |
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. Stores that are not on this machine fold into one line; --all lists them. --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|prompt|block|ingest|read | Reproducible benchmarks: search quality, context readiness, what the per-prompt hook fires on, whether the block carries the answer, what an index update costs per class of change, and what reading each store costs. |
deja update | Update a standalone install (Homebrew/npm update via the package manager). --force writes over a binary a package manager owns or one built from source. At most once a day, an interactive command also says when a newer release is out, with the upgrade command for whatever installed deja; DEJA_OFFLINE=1 turns that off, and so does DEJA_NO_UPDATE_NOTICE set to any value, which also hides the note a new version prints on its first run. Hooks and the MCP server never show it. |
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; --quiet says nothing when it worked, for a run out of a shell profile or a hook, and still reports every failure. On a busy machine, DEJA_NO_AUTO_INDEX=1 or "auto_index": false in ~/.config/deja/policy.json stops every automatic update: search, show, MCP tools and hooks answer from the last finished index and say when it was updated, with no index they print this command instead of building, and nothing deja starts on its own writes it: deja index, search --rebuild and commands that change the index on purpose, like forget and sync, still do. Run it from cron or a timer: piped or under cron it prints one line per phase, and it exits 1 when the index could not be written and 3 when it was written but part of the input was not read (a path it could not read, a line it skipped, or a file whose read stopped moving for DEJA_STORE_TIMEOUT, ten minutes by default). Set the variable before deja install so hooks started without your environment see it too; the file reaches them either way. |
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. The digest is the same text whichever agent it is for: --to <agent> checks the name and prints the command line that opens that agent with it, and --exec runs that command. |
deja aider [args] | Refresh aider's read-only context file from this project's history, then start aider with the rest of the line. On macOS and Linux it also answers each message with a recall for it. Everything after aider is aider's own flags, --help included; deja help aider is deja's page for it. |
deja goose [args] | Start Goose with recall re-read every turn rather than fixed when the session opened; the rest of the line goes to Goose, --help included. |
deja check - | Read a plan from stdin and print the errors past sessions on this machine kept running into that name something in it. It checks repeated errors, not decisions; deja and recall answer those. |
deja hook-* | What agent hooks call; deja install --auto wires them. hook-context gives the project digest once at session start, hook-prompt a recall for each prompt, hook-tool what a command or edit already has before it runs, hook-tool-after what followed a failed command before, and hook-antigravity the digest on Antigravity's first turn. hook-plan gives the repeated errors history has on a plan before it runs, but no installer wires it: add it by hand as a PreToolUse hook matched on ExitPlanMode. Each reads the host's payload on stdin. |
What the index keeps
Every switch below is off by default and goes in the environment; search_only can also go in ~/.config/deja/policy.json, which reaches hooks started without your shell. A parse switch applies to what is read from then on, so run deja index --rebuild after changing one. The parse switches and DEJA_INCLUDE_SUBAGENTS=0 also hold for what deja sync brings from another machine, as it arrives; a rebuild keeps imported sessions as they came, so to take what a switch left out, unset it and import the batch again (deja sync ssh <host> --pull --full for a pull). Search-only is applied by the first build and by deja index run by hand, which rebuilds once when it changes; a hook or agent running under a different environment keeps the index as it was built.
| Setting | Leaves out | Stops working |
|---|---|---|
DEJA_SEARCH_ONLY=1 or "search_only": true | The tables mined after the records are written: fixes, co-occurrence, commands, command failures and session facts. About a fifth of a build's CPU on a tool-heavy store. | deja fix and the MCP fix mode, which say the index is search-only. Silent instead: the remedy line after a failed command, fix hints at session start and on a plan, the remedy for a missing program, the "last time this ran" line and command hints before a command, the "ran:" line on recall hits and under the pre-edit note, recurring commands in orient, the "try deja how" hint on a search, and the neighbour-word rescue when a search finds nothing else. Search and recall results, blame, friction and the pre-edit note itself keep working. |
DEJA_INDEX_COMMANDS=0 | Commands the agent ran. | deja how and deja fix, which name the switch, command hints, and the command tables above. |
DEJA_INDEX_TOOL_OUTPUT=0 | What tools printed. | deja friction, deja fix, searching tool output, and recall by error text. |
DEJA_INDEX_PATHS=0 | Which files a session touched. | The pre-edit note, deja files, and file-level deja blame, which falls back to sessions that name the file. |
DEJA_INDEX_EDITS=0 | The text an edit replaced. | deja restore, which names the switch, and line blame by replaced text. |
DEJA_INDEX_WRITES=0 | The per-line hashes of what an edit wrote. | Line blame by written text. |
On a 3,000-session tool-heavy synthetic store, deja index --rebuild took 2.1 s (3.3 s of CPU), 1.9 s (2.7 s of CPU) search-only, and 1.55 s (1.6 s of CPU) search-only with all five parse switches off.
deja help lists every command with a line on each, and any command takes --help for its flags and examples. Everything is offline except update, sync ssh, the doctor version check, the once-a-day release check on an interactive command (DEJA_OFFLINE=1 turns it off) and deja embed against an endpoint you set, after which each search sends its query there too.Found this useful? Star deja-vu on GitHub.