CLI Reference

The recall command line

Every command and flag, with real example output. The CLI reads the same repository database as the desktop app.

The recall binary is a git-like command-line interface to the same engine and repository database the desktop app uses. It works whether or not the app is running (products like status and checkpoint scan the workspace directly; the daemon is only needed for watch and for agent access over the WebSocket).

Global options

recall --help
recall --db-path <path>    # Path to the ReCall registry DB (defaults to the app data location)
recall --workspace <id>     # Workspace id to operate on (defaults to the active workspace)

Environment variables:

Variable	Purpose
`RECALL_DB_PATH`	Overrides the database path used by the CLI
`RECALL_WS_URL`	Overrides the WebSocket daemon URL (`ws://127.0.0.1:9876` by default)
`RECALL_LICENSE_API`	Overrides the license server base URL (default `https://brain.rowrecall.com`)

The database defaults to the app data location (e.g. %APPDATA%\com.rowai.recall\recall.chdb on Windows). If no database exists yet, commands report a clear error and tell you to run the desktop app once to create it.

Command summary

Command	Summary
`recall status`	Files added / modified / deleted since the last checkpoint
`recall checkpoint [-l label]`	Create a checkpoint snapshot of the workspace
`recall restore <event_id> [file]`	Restore the workspace (or one file) to a past event
`recall undo`	Undo the most recent rollback/restore operation
`recall redo`	Re-apply the most recently undone operation
`recall log [-n N] [--file path]`	List recent events
`recall diff <event_id> [--to-event-id N] [--file path]`	Show a unified diff for an event (or between two events)
`recall branch [name] [--switch name]`	Create, list, or switch branches
`recall where`	Print the workspace and database paths
`recall watch`	Stream new events as they are recorded
`recall license <action>`	Plan / license management
`recall workspace <action>`	Workspace management
`recall webhook <action>`	Team webhook configuration
`recall recovery <action>`	Cross-device DB-key recovery (Stage 0)

Status

Shows files added, modified, or deleted relative to the last checkpoint snapshot. It compares the workspace on disk against the last checkpoint, so it works even when the watcher is not running.

$ recall status
M src/main.rs
A src/new_module.rs
D src/old_file.rs

Markers: A added, M modified, D deleted. When there is nothing to report:

$ recall status
nothing to commit, working tree clean

Checkpoint

Creates a checkpoint: a full snapshot of every tracked file under a labeled marker event on the timeline. The label is optional and defaults to cli checkpoint.

$ recall checkpoint -l "before refactor"
Checkpoint created: event #31 (142 files)

Ignored entries (not snapshotted) are dotfiles, node_modules and target directories, and files larger than 1 MB.

Restore

Restores the workspace (or a single file) to the state it had at a specific event id. The operation is itself recorded as an event and can be undone.

# Restore the whole workspace to event 1243
$ recall restore 1243
Restored 5 files to event 1243

# Restore only one file
$ recall restore 1243 src/main.rs
Restored src/main.rs to event 1243 (3 files changed)

This is the real restore surface. There is no recall restore --time and no restore-by-path-without-event-id form — restores are always keyed to an event id (optionally scoped to one file).

Undo / Redo

Every restore (rollback, single-file restore, branch switch) is recorded and placed on an undo stack.

$ recall undo
Undid last operation (event #1244): 5 files changed

$ recall redo
Redid last operation (event #1245): 5 files changed

Log

Lists recent events, newest first, with a microsecond timestamp, action type, file path and line-change counts.

$ recall log -n 10
#31    2026-08-11 14:02:11.118 [Checkpoint] cli checkpoint
#30    2026-08-11 14:02:09.004 [Write]      src/cache.rs     +12 -3
#29    2026-08-11 14:01:55.001 [Create]     src/new_module.rs

Action types: Write, Delete, Create, Rollback, Checkpoint, Move, Undo, Redo.

recall log -n 50 --file src/main.rs # only events touching that file

Diff

Shows a unified diff for an event against its predecessor, or between two events.

$ recall diff 30
diff src/cache.rs (event 29 → 30)
@@ -12,3 +12,4 @@
 const MAX_CACHE: usize = 1024;
 ...
 
# diff a range, or restrict to one file
recall diff 30 --to-event-id 35
recall diff 30 --file src/main.rs

Branch

Creates (rooted at the last checkpoint by default), lists, or switches branches. Switching restores the workspace to the branch’s base event and records it as an undoable operation.

$ recall branch experiment-cache
Created branch 'experiment-cache' at event #31

$ recall branch
experiment-cache   (base event #31)   *
main               (base event #12)

$ recall branch --switch main
Workspace restored to event #12
Switched to branch 'main'

Where

Prints the workspace and database paths.

$ recall where
workspace: D:\projects\app
database:  C:\Users\you\AppData\Roaming\com.rowai.recall\recall.chdb

Watch

Streams new events as the engine records them (this is the CLI-side daemon; it listens for new events every 500 ms). Stop with Ctrl+C.

$ recall watch
Watching for events (Ctrl+C to stop)...
#35    14:03:22.118 [Write]      src/cache.rs

License

Plan and license management. Subcommands: status, activate <key>, redeem <code> [--email ...], machine, deactivate.

$ recall license status
plan:        free
events used: 85
events cap:  100
expiry:      —

$ recall license machine
machine fingerprint: 9f2a...1c0e

# Activate a Pro license key (verified against the license server)
$ recall license activate ROWPRO-XXXX-XXXX-XXXX
Pro license activated (30 days remaining).

# Redeem a 30-day welcome coupon (binds to this machine)
$ recall license redeem WELCOME-XXXX-XXXX-XXXX --email you@example.com
Welcome coupon redeemed — Pro activated for 30 days on this machine.
License updates will be sent to you@example.com.
Enjoy ReCall Pro! When the trial ends you can renew from the app.

$ recall license deactivate
Back to the free plan.

On the free plan, new file-change events stop recording once the 100-event cap is reached; restore-point operations (rollback/undo/redo/checkpoint) always work. See Licensing & Plans.

Workspace

Subcommands: list, add <path>, switch <id>, remove <id>. Each workspace has its own timeline and database. Free plan: 1 workspace; Pro: up to 5.

$ recall workspace list
* default           D:\projects\app

$ recall workspace add D:\projects\other
Workspace 3f8a2c1e added (D:\projects\other).

$ recall workspace switch 3f8a2c1e
Active workspace switched to 3f8a2c1e.

$ recall workspace remove 3f8a2c1e
Workspace 3f8a2c1e removed (history kept on disk).

Note: you cannot remove the currently active workspace — switch to another one first. When a workspace is added, its per-workspace database stores the workspace path so checkpoint and status work immediately.

Webhook

Team webhook configuration. Subcommands: set <url> [secret], status, clear. Payloads are HMAC-SHA256 signed and pushed over TLS; plain http is only allowed for localhost.

$ recall webhook set https://team.example.com/recall
Webhook configured: https://team.example.com/recall
Secret: 3f4a...9c0d
Keep the secret safe — it signs every payload (HMAC-SHA256).

$ recall webhook status
configured:  yes
url:         https://team.example.com/recall
secret:      yes (set)

$ recall webhook clear
Webhook removed.

Recovery (cross-device key recovery — Stage 0)

Subcommands: status, enable <passphrase>, disable, build <passphrase>, apply <passphrase> <blob>, where. This wraps the database encryption key under a passphrase-derived key (PBKDF2-HMAC-SHA256 → AES-256-GCM) so the ciphertext can be stored safely and used to recover on a formatted or replaced machine. See Security & Privacy.

$ recall recovery status
recovery: not enabled
data dir: C:\Users\you\AppData\Roaming\com.rowai.recall

$ recall recovery enable "a long strong passphrase"
recovery enabled (pbkdf2-hmac-sha256, iterations=150000). The DB key is now wrapped under your passphrase.
Run `recall recovery build ` to get the blob to upload next.

$ recall recovery build "a long strong passphrase"
ciphertext={...}
metadata={"v":1,"kdf":"pbkdf2-hmac-sha256","iters":150000,"scope":"db-key"}

$ recall recovery where
C:\Users\you\AppData\Roaming\com.rowai.recall

The build output is the opaque ciphertext blob to upload (for example via POST /api/recovery/upload against the licensing backend); apply recovers the key on a (possibly new) machine from the blob JSON and your passphrase, installing it into the OS secure store so existing timeline data can be opened.

Also see

All of these operations are available through the WebSocket agent API and the MCP server, which share the same engine and timeline.