CLI commands
Every command of the chat-recall CLI, with its options. chat-recall <command> --help prints the same text.
chat-recall init
Set up chat-recall: connect to your server, configure MCP, ship your local sessions
chat-recall init [options]
| Option | Description |
|---|---|
--server <url> | chat-recall server URL to connect this machine to |
--token <token> | Self-host device token (skips the interactive OIDC login) |
--skip-mcp | Skip MCP server configuration |
--skip-sync | Skip the first session sync |
--with-codeindex | Force-download the codeindex binary during init. Default behavior is to detect an already-installed codeindex on PATH and register it as an MCP server. |
--skip-codeindex | Skip the codeindex companion entirely (no detection, no registration). |
--skip-service | Skip installing the per-user background sync service (Linux/macOS/Windows). By default init installs it so new conversations ship automatically. |
--skip-hooks | Skip installing the Claude Code hooks |
--yes | Do not pause before the first upload. The scope summary still prints. (default: false) |
--prompt-json | Print the device prompt as one JSON line on stdout, then continue (default: false) |
chat-recall install-skills
Install the chat-recall skills into every local AI tool (Claude/Codex/Cursor/OpenCode/Antigravity/Pi) so agents know how to use the recall_* tools
chat-recall install-skills [options]
| Option | Description |
|---|---|
--uninstall | Remove the chat-recall-managed skills from every tool |
--all-tools | Install to every supported tool, even ones not detected on this machine |
chat-recall index
Collect local sessions and ship them to your server (alias for sync)
chat-recall index [options]
| Option | Description |
|---|---|
-f, --force | Ignore the per-server ledger and re-ship everything (default: false) |
chat-recall repair
Rebuild sessions an upstream tool truncated in place (e.g. Claude Code resume rewrite) from the shrink-protected raw archive. DRY-RUN by default — pass --apply to write.
chat-recall repair [options] [sessionIds...]
| Option | Description |
|---|---|
--all | Scan the recency window and repair EVERY damaged session (no ids needed) (default: false) |
--since-hours <n> | With --all: only scan sessions modified in the last N hours (default: "72") |
--apply | Actually write the recovered conversations to the server(s). Without this, nothing is mutated. (default: false) |
--server <url> | Target ONLY this server (e.g. the SaaS), instead of every configured sync endpoint |
--force | Push even to servers that already look full (default: false) |
-v, --verbose | Per-session detail (default: false) |
chat-recall search
Search your server for relevant sessions (requires login)
chat-recall search [options] <query>
| Option | Description |
|---|---|
-n, --top <number> | Number of results to show (default: "5") |
-p, --project <path> | Filter by project path (substring match) |
chat-recall status
Show your server's sync status and statistics (requires login)
chat-recall status [options]
chat-recall optimize
Deprecated: storage is server-side now, nothing to optimize locally
chat-recall optimize [options]
chat-recall show
Show conversation content from a session (requires login)
chat-recall show [options] <session_id>
| Option | Description |
|---|---|
-m, --messages <number> | Number of messages to show (default: "10") |
-f, --full | Show full conversation (all messages) (default: false) |
-l, --line <number> | Show only the message at this line, with every tool input and result whole |
chat-recall memory
Unified memory system - index and search across all data sources
chat-recall memory [options] [command]
chat-recall memory index
Collect local sessions and ship them to your server (alias for sync)
chat-recall memory index [options]
| Option | Description |
|---|---|
-f, --force | Ignore the per-server ledger and re-ship everything (default: false) |
chat-recall memory search
Search across all memory types on your server (requires login)
chat-recall memory search [options] <query>
| Option | Description |
|---|---|
-n, --top <number> | Number of results (default: "10") |
-t, --types <types> | Filter by source types (comma-separated) |
chat-recall memory status
Show your server's memory statistics across all source types (requires login)
chat-recall memory status [options]
chat-recall memory links
Show relationships for a memory item (requires login)
chat-recall memory links [options] <source_type> <item_id>
chat-recall memory wake-up
Generate wake-up context (high-importance facts + knowledge graph snapshot) for an AI session (requires login)
chat-recall memory wake-up [options]
| Option | Description |
|---|---|
-p, --project <filter> | Restrict facts/KG to a project (substring match) |
chat-recall escalate
Escalate a finished session's learnings (decisions, user corrections, outcome) into the knowledge graph (requires login)
chat-recall escalate [options] [sessionId]
| Option | Description |
|---|---|
--latest | Pick the most recent synced session of the current project |
-p, --project <name> | Knowledge-graph entity name for the facts (default: project folder name) |
--dry-run | Extract and print the learnings without writing them |
chat-recall feedback
Send a message to the people who build chat-recall. No account needed.
chat-recall feedback [options] <message...>
| Argument | Description |
|---|---|
message | what you want to say — anything at all |
| Option | Description |
|---|---|
--email <address> | so we can reply; optional |
chat-recall doctor
Quick health check across login, server, credentials, hooks, MCP server, and codeindex
chat-recall doctor [options]
| Option | Description |
|---|---|
--purge-local | Remove the legacy local index (cache.db + vector/KG files) left by pre-thin-collector versions — storage is server-side now. Requires login; keeps credentials, sync ledger, identity, and the audit log. |
chat-recall companions
Manage companion tools (codeindex)
chat-recall companions [options] [command]
chat-recall companions status
Show whether codeindex is installed and what it provides
chat-recall companions status [options]
chat-recall companions install
Install codeindex (downloads from munhq/codeindex GitHub release)
chat-recall companions install [options]
| Option | Description |
|---|---|
--force | Re-download even if already installed |
chat-recall companions uninstall
Remove the codeindex binary chat-recall installed (does not touch your other tools)
chat-recall companions uninstall [options]
chat-recall verify
Check that the server holds everything this machine has, per session
chat-recall verify [options]
| Option | Description |
|---|---|
--deep | Compare per-session content size against each server (default: false) |
--records | With --deep: also diff the exact record (uuid) sets — proof, not inference (default: false) |
--since-hours <n> | Only check sessions modified in the last N hours (default: all) |
--repair | Re-ship every STRANDED session found (clears its ledger cursor) (default: false) |
--json | Machine-readable output (default: false) |
chat-recall sources
See and choose which AI-tool transcript folders get synced
chat-recall sources [options] [command]
chat-recall sources list
Show every transcript folder found, and whether it is synced
chat-recall sources list [options]
chat-recall sources add
Sync a transcript folder we did not find automatically
chat-recall sources add [options] <path>
chat-recall sources approve
Start syncing a folder that was waiting for a decision
chat-recall sources approve [options] <path>
chat-recall sources decline
Keep a folder out of sync (e.g. a work account you do not want here)
chat-recall sources decline [options] <path>
| Option | Description |
|---|---|
--delete-remote | Also delete sessions already uploaded FROM this folder (irreversible) (default: false) |
--yes | Skip the confirmation prompt for --delete-remote (default: false) |
chat-recall sources forget
Undo a decision, so the folder is asked about again
chat-recall sources forget [options] <path>
chat-recall detectors
Manage the optional external secret detectors (gitleaks, trufflehog)
chat-recall detectors [options] [command]
chat-recall detectors status
Show which detectors are installed, pinned and verified
chat-recall detectors status [options]
chat-recall detectors install
Download + verify a pinned detector into ~/.chat-recall/bin (default: both)
chat-recall detectors install [options] [name]
| Option | Description |
|---|---|
--force | Re-download even if the pinned version is already installed |
chat-recall detectors remove
Remove detectors chat-recall installed (never touches your own binaries)
chat-recall detectors remove [options] [name]
chat-recall code
Index a codebase with codeindex and ship findings/hotspots/actions to your server
chat-recall code [options] [command]
chat-recall code index
Run codeindex on a repo (default: cwd) and sync the results to your server
chat-recall code index [options] [path]
| Option | Description |
|---|---|
--no-install | Don't auto-install codeindex if missing |
chat-recall code status
List code-indexed projects on your server
chat-recall code status [options]
chat-recall code show
Show a project: health, findings summary, and the top action items
chat-recall code show [options] <project>
chat-recall toolkit
Copy skills / commands / agents / MCPs between your AI tools
chat-recall toolkit [options] [command]
chat-recall toolkit sync
Fan every artifact out to every tool that is missing it (runs locally now)
chat-recall toolkit sync [options]
| Option | Description |
|---|---|
--types <list> | comma-separated subset: skill,mcp,command,agent |
chat-recall toolkit pull
Install artifacts this device is missing, from the server (cross-device setup)
chat-recall toolkit pull [options]
| Option | Description |
|---|---|
--types <list> | comma-separated subset: mcp |
--dry-run | report what would change, write nothing |
--mcp <names> | comma-separated MCP servers to install even if only another platform registered them |
chat-recall toolkit drain
Process cross-tool sync intents queued from the web UI, now
chat-recall toolkit drain [options]
chat-recall toolkit copy
Copy one artifact (skill|mcp|command|agent) from one tool to another
chat-recall toolkit copy [options] <type> <name> <fromTool> <toTool>
chat-recall shares
List the projects you share with your team
chat-recall shares [options]
chat-recall share
Share a project with your team (teammates can then see your work on it)
chat-recall share [options] <project_id>
chat-recall unshare
Stop sharing a project with your team
chat-recall unshare [options] <project_id>
chat-recall tasks
Collaborative team tasks
chat-recall tasks [options] [command]
chat-recall tasks list
List team tasks assigned to you
chat-recall tasks list [options]
chat-recall tasks pull
Write TEAM_TASKS.md for your tasks in this project (default: cwd)
chat-recall tasks pull [options] [dir]
| Option | Description |
|---|---|
-f, --force | overwrite even if the local file has unpushed edits |
chat-recall tasks push
Push TEAM_TASKS.md status edits back to the team
chat-recall tasks push [options] [dir]
chat-recall team
Sync team toolkit (skills, CLAUDE.md, MCPs, agents, commands)
chat-recall team [options] [command]
chat-recall team whoami
Show the user + team memberships the server sees for your token
chat-recall team whoami [options]
chat-recall team create
Create a new team. You become the owner. Stores teamId in settings.
chat-recall team create [options] <name>
chat-recall team invite
Generate a single-use invite token for your team (owner-only)
chat-recall team invite [options]
| Option | Description |
|---|---|
--email <hint> | Display hint (e.g. teammate@company.com); not validated |
chat-recall team join
Accept a team invite. Stores team id locally.
chat-recall team join [options] <invite-token>
chat-recall team pull
Pull artifacts changed since the last pull and write them into your local ~/.claude/, ~/.gemini/, ~/.codex/ dirs
chat-recall team pull [options]
| Option | Description |
|---|---|
--dry-run | Fetch but don't write to disk (preview only) |
chat-recall team publish
Publish a local file as an artifact (skill|command|agent|mcp|plan|plugin|instructions|hook)
chat-recall team publish [options] <type> <name> <file>
| Option | Description |
|---|---|
--tool <tool> | Target tool: claude|gemini|opencode|codex|agy|cursor|cross_tool (default: "cross_tool") |
--pinned-to <glob> | Limit which projects pull this artifact |
chat-recall team list
List artifacts in the team library (metadata only, no bodies)
chat-recall team list [options]
chat-recall team revoke
Revoke an artifact from the team library (owner-only)
chat-recall team revoke|unpublish [options] <artifact-id>
chat-recall team leave
Clear local team config (does not delete pulled artifacts; does not remove your server-side membership)
chat-recall team leave [options]
chat-recall vault
Encrypted multi-device chat backup (E2EE — server cannot decrypt)
chat-recall vault [options] [command]
chat-recall vault enable
Set up the Vault on this device. Generates a per-user salt; derives the master key from your passphrase.
chat-recall vault enable [options]
| Option | Description |
|---|---|
--passphrase <s> | Passphrase (insecure — prefer interactive or --passphrase-env) |
--passphrase-env <name> | Read passphrase from this env var |
--existing-salt <hex> | Reuse a salt from another device (64 hex chars) |
--no-keyring | Don't store the passphrase in the OS keyring (the background daemon then cannot decrypt) |
chat-recall vault sync
Walk local chat sources, encrypt new/changed sessions, upload ciphertext to the server
chat-recall vault sync [options]
| Option | Description |
|---|---|
--passphrase <s> | Passphrase (insecure — prefer interactive or --passphrase-env) |
--passphrase-env <name> | Read passphrase from this env var |
chat-recall vault restore
Pull encrypted blobs from the server, decrypt locally, write them where chat-recall can index them
chat-recall vault restore [options]
| Option | Description |
|---|---|
--passphrase <s> | Passphrase (insecure — prefer interactive or --passphrase-env) |
--passphrase-env <name> | Read passphrase from this env var |
--since <ms> | Only restore blobs uploaded after this ms-epoch (default 0 = all) |
chat-recall vault status
Show whether the Vault is enabled, salt fingerprint, last sync time, and whether this machine can decrypt unattended
chat-recall vault status [options]
chat-recall vault forget
Remove the stored passphrase from this machine's OS keyring (the vault stays enabled; the daemon stops being able to decrypt)
chat-recall vault forget [options]
chat-recall guard
Check a pending tool call against the decision register (used by the pre-execution hooks)
chat-recall guard [options]
| Option | Description |
|---|---|
--harness <name> | claude | codex | agy | cursor | opencode (default: "claude") |
--project <id> | Resolve decisions for this project |
--enforce | Return a blocking verdict instead of a warning |
chat-recall task-hook
Move a board card when a prompt or a commit names its id (used by the task hooks)
chat-recall task-hook [options]
| Option | Description |
|---|---|
--claim | UserPromptSubmit: claim every open card the prompt names |
--close | SessionEnd: close every open card a recent commit names |
--since <hours> | How far back --close reads commits (default: "24") |
chat-recall install-hooks
Install the chat-recall hooks into every Claude profile (init does this; use this to change which hooks run)
chat-recall install-hooks [options]
| Option | Description |
|---|---|
--uninstall | Remove the hooks, and keep them out when the MCP server starts |
--no-resume-hint | Don't install the UserPromptSubmit resume-hint hook |
--no-escalate | Don't install the SessionEnd learnings-escalation hook |
--no-wakeup | Don't install the SessionStart wake-up hook |
--no-guard | Don't install the PreToolUse decision guard |
--no-task-board | Don't install the hooks that claim and close board cards |
--no-messages | Don't install the hook that delivers messages between sessions |
chat-recall dossier
Generate a project dossier (overview/architecture/decisions/etc) as markdown (requires login)
chat-recall dossier [options] <project>
| Option | Description |
|---|---|
--sessions <n> | Max sessions to enumerate (default: "10") |
--tasks <n> | Max open tasks to list (default: "20") |
--plans <n> | Max plans to list (default: "20") |
--out <file> | Write report to this file instead of stdout |
chat-recall project-id
Show the resolved project_id for a path (debug helper)
chat-recall project-id [options] <path>
chat-recall watch
Run the live indexer daemon (watches all AI-tool session stores, generates summaries, precomputes, syncs when logged in)
chat-recall watch [options]
| Option | Description |
|---|---|
--install-service | Install + start a per-user background service so collection keeps running (Linux: systemd --user · macOS: launchd · Windows: Scheduled Task). No admin rights. |
chat-recall service
Manage the per-user background sync service (Linux: systemd --user · macOS: launchd · Windows: Scheduled Task). No admin rights.
chat-recall service [options] <action>
chat-recall exclude
Control what never leaves this machine (per-tool, per-project). Bare exclude lists the current rules.
chat-recall exclude [options] [command]
chat-recall exclude list
Show current exclusions
chat-recall exclude list [options]
chat-recall exclude project
Exclude a project path from syncing (substring match on the project path; e.g. ~/.claude-pr-bot)
chat-recall exclude project [options] <path>
chat-recall exclude tool
Exclude an AI tool entirely (claude | gemini | codex | opencode | agy | cursor | hermes | pi)
chat-recall exclude tool [options] <tool>
chat-recall exclude remove
Remove an exclusion (tool name or project path)
chat-recall exclude remove [options] <value>
chat-recall include
Opt a personal folder (Pictures/Music/Documents/…) back into code indexing. Bare include lists opted-in paths.
chat-recall include [options] [command]
chat-recall include list
Show paths opted back into indexing
chat-recall include list [options]
chat-recall include project
Re-permit a path under a personal folder (substring match; e.g. ~/Documents/code)
chat-recall include project [options] <path>
chat-recall include remove
Undo an opt-in (personal folder goes back to skipped)
chat-recall include remove [options] <path>
chat-recall retention
How long the server keeps your synced sessions. Bare retention shows the current window.
chat-recall retention [options] [command]
chat-recall retention show
Show the window and how many sessions it would delete
chat-recall retention show [options]
chat-recall retention set
Set the window in days, or 0 to keep everything. Prints what it would delete and asks first.
chat-recall retention set [options] <days>
| Option | Description |
|---|---|
--yes | Skip the confirmation (for scripts). The warning still prints. (default: false) |
chat-recall sync-only
Opt-in sync: ship ONLY chosen projects. Bare sync-only shows the mode + allowlist.
chat-recall sync-only [options] [command]
chat-recall sync-only list
Show the sync mode and allowlisted projects
chat-recall sync-only list [options]
chat-recall sync-only add
Add a project id (git:…/ws:…/path:…) or path substring to the allowlist (switches mode to "only")
chat-recall sync-only add [options] <project>
chat-recall sync-only remove
Remove a project from the allowlist
chat-recall sync-only remove [options] <project>
chat-recall sync-only all
Switch back to syncing ALL non-excluded projects (keeps the list, just disables opt-in mode)
chat-recall sync-only all [options]
chat-recall projects
List distinct project ids discovered on this machine (for sync-only add)
chat-recall projects [options]
chat-recall login
Log in (device flow) and mint a sync device token → ~/.chat-recall/credentials.json (0600). Defaults to https://chatrecall.dev.
chat-recall login [options] [server-url]
| Option | Description |
|---|---|
--token <token> | Self-host: skip OIDC and save this device token directly |
--check | Report-only: exit 0 if a working credential for this server exists, 1 otherwise (never interactive) |
--issuer <url> | OIDC issuer URL (default: learned from the server via /api/capabilities) |
--client-id <id> | OIDC client id (default: chat-recall-web) |
--team <slug> | Team to mint the device token for (default: your only team) |
--device-id <id> | Device id for this machine (default: hostname) |
--prompt-json | Print the device prompt as one JSON line on stdout, then wait for approval (default: false) |
chat-recall logout
Remove one sync target (other targets keep syncing)
chat-recall logout [options] <server-url>
chat-recall delete
Delete sessions from chat-recall everywhere: purges them on every logged-in server and tombstones them so they can't resurrect on the next sync. Does NOT touch the AI tool's own transcript files.
chat-recall delete [options] [session-ids...]
| Option | Description |
|---|---|
--project <id> | Select every session in a project (e.g. git:github.com/me/repo) |
--match <text> | With --project: only sessions whose first prompt is EXACTLY this |
--tool <name> | With --project: only sessions from this tool (claude, codex, …) |
--stdin | Read session ids from stdin, one per line |
-n, --dry-run | List what would be deleted and exit |
-y, --yes | Skip the confirmation prompt |
chat-recall restore
Undo a delete: lifts the tombstone so those sessions can be synced again. Restores no content by itself — re-run chat-recall index --force on a machine that still has the transcript. With no ids, lists what has been deleted.
chat-recall restore [options] [session-ids...]
| Option | Description |
|---|---|
--stdin | Read session ids from stdin, one per line |
--list | Just show what has been deleted, newest first |
--limit <n> | How many deletions to list (default 50) |
chat-recall rename
Give a session a memorable name on every logged-in server (mirrors Claude Code's /rename — shows in recall recent and the web UI in place of the auto summary). Pass an empty name "" to clear it and revert to the auto title.
chat-recall rename [options] <session-id> <name>
chat-recall sync
Push redacted conversations to the configured server (secrets always masked). Bare sync is incremental (watermark-based); flags force an explicit window.
chat-recall sync [options]
| Option | Description |
|---|---|
--since-hours <n> | Only sync sessions modified in the last N hours |
--limit <n> | Max sessions to sync |
--full | Ignore the watermark and push everything |
--paths-cleartext | Send project paths in cleartext (self-host only; default hashes them) |
--throttle <ms> | Pause between upload batches in ms (default: 1000, or 3000 with --full) |
--prune | After syncing, drop server-side session rows that have no content (ghost rows) |
chat-recall reconcile
Reconcile DERIVED FIELDS (e.g. native title) on every logged-in server WITHOUT re-syncing conversations. Scans each session once for any missing field, pushes only that field, and records 'scanned/absent' so it never retries. Normal sync does this automatically; run this for an explicit on-demand backfill. --force re-scans every session (ignores the coverage ledger).
chat-recall reconcile [options]
| Option | Description |
|---|---|
--force | Re-scan and re-push every field for every session |
chat-recall update
Update this CLI now from the server you sync to (same-origin, checksum-pinned) and report exactly why if it cannot. Use --from-npm when the server has not rolled the newest release yet.
chat-recall update [options]
| Option | Description |
|---|---|
--from-npm | Install the newest published release straight from the npm registry instead of the server tarball |