CLI Reference

This page documents the public CLI surface. The source of truth is src/cli/; run sivtr --help and sivtr <command> --help for installed-version help.

Top-level

sivtr [COMMAND]
sivtr --all              # with bare TTY: also select remote mounts on open

With no command:

• TTY → multi-source workspace browser (Source / Sessions / Dialogues / Content).
• Piped stdin → single-buffer browser (same as sivtr pipe).

run

sivtr run <COMMAND> [ARGS...]

Runs a command, captures combined stdout/stderr, reports the exit status, saves history when enabled, and opens the captured output.

sivtr run cargo test
sivtr run git status --short

pipe

sivtr pipe

Reads stdin and opens it. Piping directly to sivtr is equivalent:

cargo build 2>&1 | sivtr

import

sivtr import

Opens the current structured shell session log. Requires shell integration.

init

sivtr init <TARGET>

Supported targets:

Target	Purpose
powershell	Install Windows PowerShell hook
pwsh	Alias for PowerShell integration
bash	Install Bash hook
zsh	Install Zsh hook
nushell / nu	Install Nushell hook
tmux	Install tmux picker binding
linux-shortcut	Generate Linux desktop/terminal picker launcher
macos-shortcut	Generate macOS Terminal/LaunchAgent picker launcher

copy

sivtr copy [MODE] [SELECTOR] [OPTIONS]

Command-block modes:

Mode	Meaning
no mode	Copy input plus output
in	Copy input
out	Copy output
cmd	Copy bare command

Aliases:

Alias	Expands to
sivtr c	sivtr copy
sivtr ci	sivtr copy in
sivtr co	sivtr copy out
sivtr cc	sivtr copy cmd

Common options:

Option	Meaning
--ansi	Copy ANSI-decorated text when available
--pick	Open the interactive picker
--print	Print copied text after copying
--regex <PATTERN>	Keep lines matching regex
--lines <SPEC>	Keep selected 1-based lines

Input-capable modes also support:

Option	Meaning
--prompt <TEXT>	Rewrite the copied input prompt

Examples:

sivtr copy
sivtr copy 3 --print
sivtr copy --prompt ":"
sivtr copy in 2..4
sivtr copy out --pick --regex panic
sivtr copy cmd --pick

copy agent provider sessions

sivtr copy <PROVIDER> [MODE] [SELECTOR] [OPTIONS]

Providers come from the AgentProvider registry (not a hand-written CLI list):

Provider	Command
Codex	sivtr copy codex
Claude Code	sivtr copy claude
Cursor	sivtr copy cursor
OpenCode	sivtr copy opencode
OpenClaw	sivtr copy openclaw
Hermes	sivtr copy hermes
Grok	sivtr copy grok
Pi	sivtr copy pi

Modes:

Mode	Meaning
no mode	Last completed user + assistant turn
in	Last user message
out	Last assistant reply
tool	Last tool output
all	Whole parsed session

Agent copy options include all common copy options plus:

Option	Meaning
`–session <N	ID>`

Examples:

sivtr copy claude
sivtr copy claude out --print
sivtr copy cursor out --print
sivtr copy hermes out --print
sivtr copy grok out --print
sivtr copy claude --session 2
sivtr copy codex 2..4
sivtr copy codex out --pick
sivtr copy opencode all --lines 1:20
sivtr copy pi tool --regex error

diff

sivtr diff <LEFT> <RIGHT> [OPTIONS]

Compares two recent command blocks from the current shell session. Each selector must resolve to exactly one block.

Content options:

Option	Meaning
--output	Compare output text. This is the default.
--block	Compare input plus output
--input	Compare input with prompt
--cmd	Compare bare command text

View option:

Option	Meaning
--side-by-side	Show a two-column text view

Examples:

sivtr diff 1 2
sivtr diff 3 1 --block
sivtr diff 2 1 --side-by-side

search

sivtr search <TARGET> [QUERY] [OPTIONS]

Searches captured terminal records and supported AI workspace sessions. The target chooses where to search; filters choose which records match. A plain-text positional QUERY (no regex) ranks the source by BM25 relevance and becomes the default sort; --match optionally bounds the set with a regex first.

Targets:

Target	Meaning
terminal[/<session>[/<record>[/p<part>]]]	Terminal command records
agent[/<session>[/<turn>[/p<part>]]]	All registered AI/agent records
codex / claude / cursor / opencode / openclaw / grok / hermes / pi / qoder [/<session>[/<turn>[/p<part>]]]	One provider’s records
<origin>:<target>	Named remote or other local workspace origin, for example desk:terminal or docs:codex/4

Use * for wildcard path segments, for example terminal/*/3 or pi/*/*. Origins come from sivtr remote add <alias> ... or local workspace names listed by sivtr ws list.

Options:

Option	Meaning
QUERY	Plain-text search query; BM25 ranks the source by these terms (no regex). Default sort becomes relevance.
--match <REGEX>, -m <REGEX>	Case-insensitive regex that bounds the set before relevance ranking
--exclude <REGEX>, -v <REGEX>	Case-insensitive exclusion filter applied after matches are found
--in <FIELD>, -i <FIELD>	content, title, session, input, output, command, or all; default is content
--kind <KIND>	Part kind filter: prompt, command, user, assistant, tool, tool_call, tool_result, skill, thinking, output, or error
--status <STATUS>	success, failure, or unknown
--exit-code <CODE>	Exact terminal process exit code
--min-duration <DURATION>	Minimum command duration, e.g. 500ms, 2s, 1m
--max-duration <DURATION>	Maximum command duration
--sort <SORT>	newest (default), relevance (default with a QUERY or --match), oldest, duration, duration-asc, exit-code, or exit-code-asc
--cwd <PATH>	Workspace directory used to resolve records
--since <TIME>	Only include records at or after this time
--until <TIME>	Only include records at or before this time
--last <DURATION>	Recent time window, e.g. 30m, 2h, 7d
--latest <N>	Return the latest N matching records before final sort. Defaults to 5 when neither --latest nor --limit is set (relevance sort ranks the whole set and skips the recency window).
-l, --limit <N>	Maximum result groups to print (hard ceiling after latest/sort)
--exclude-current, --other	Exclude the current agent session from agent searches
--json	Alias for --format workset
--refs	Alias for --format refs; prints refs, one per line
--format <FORMAT>, -f <FORMAT>	full, timeline, compact, md, refs, or workset; terminal stdout defaults to full, piped stdout defaults to workset

When stdout is piped and no explicit format is selected, WorkSet commands emit WorkSet JSON for the next command. Use --refs or -f timeline only at the final display step.

Time filters accept RFC3339 timestamps, Unix seconds/milliseconds, relative durations like 30m, 2h, 7d, and aliases such as today, yesterday, tomorrow, this morning, this afternoon, this evening, tonight, and now.

Examples:

sivtr search terminal --status failure --latest 1 --json
sivtr s terminal "docker pull failed" --latest 20 --refs
sivtr s terminal -m "panic|failed" -v "example|sample" --since today --refs
sivtr s terminal -m "panic|failed" | sivtr filter @ -v "demo" -i title -f timeline
sivtr search agent --match "TODO|failed|next step" --since yesterday --format md
sivtr search pi --since today --sort oldest --format timeline
sivtr search pi/019e5941 --match "cargo test" --format compact
sivtr search terminal/session_13104/3 --format workset

eval

sivtr eval [OPTIONS]

Benchmarks retrieval quality against golden queries: freezes the current workspace records into a snapshot, then ranks the corpus per query and reports recall@k / precision@k / MRR / NDCG@k. See docs/retrieval-eval.md for the methodology and measured results.

Option	Meaning
--k <K>	Evaluation depth (default 5)
--sort <SORT>	Sort strategy to benchmark (default newest)
--snapshot <PATH>	Frozen eval snapshot file (queries + corpus JSON)
--create-snapshot <PATH>	Dump current workspace records into a new snapshot (queries start empty)
--export <DIR>	Write qrels.txt and results.txt (trec_eval format) into this directory
--json	Emit the report as JSON

Example workflow:

sivtr eval --create-snapshot snap.json   # then edit snap.json: add labeled queries { name, query, relevant: [...] }
sivtr eval --snapshot snap.json --sort relevance --json

filter

sivtr filter [SOURCE] [OPTIONS]

Filters a source or piped WorkSet with the same shared WorkSet filter surface used by search. If SOURCE is omitted it defaults to @, meaning WorkSet JSON from stdin.

Options:

Option	Meaning
--parts	Select matching part anchors instead of preserving the input anchor granularity
--match <REGEX>, -m <REGEX>	Case-insensitive content filter
--exclude <REGEX>, -v <REGEX>	Case-insensitive exclusion filter
--in <FIELD>, -i <FIELD>	content, title, session, input, output, command, or all
--kind <KIND>	Part kind filter: prompt, command, user, assistant, tool, tool_call, tool_result, skill, thinking, output, or error
--status <STATUS>	success, failure, or unknown
--exit-code <CODE>	Exact terminal process exit code
--min-duration <DURATION>	Minimum command duration
--max-duration <DURATION>	Maximum command duration
--sort <SORT>	newest, oldest, duration, duration-asc, exit-code, or exit-code-asc
--cwd <PATH>	Workspace directory used to resolve records
--since <TIME> / --until <TIME> / --last <DURATION>	Time filters
--latest <N>	Return the latest N matching anchors before final sort
-l, --limit <N>	Maximum result anchors to print
--exclude-current, --other	Exclude the current agent session from agent searches
--json	Alias for --format workset
--refs	Alias for --format refs
--format <FORMAT>, -f <FORMAT>	full, timeline, compact, md, refs, or workset
--save <NAME>	Save the result WorkSet as @name

Examples:

sivtr search terminal --json | sivtr filter @ -m error --refs
sivtr filter terminal --status failure --refs
sivtr filter @last --parts --kind tool_result --refs

var

sivtr var <COMMAND>

Manages named WorkSet variables.

Command	Meaning
set <name> [source]	Save a source or piped WorkSet as @name
list	List saved variables with item counts and creation time
rm <name>	Remove one saved variable
merge <name> <source>...	Merge sources into a saved variable, deduplicating by anchor
drop <name> <source>...	Remove source anchors from a saved variable
cleanup	Remove all saved variables

Examples:

sivtr var set ctx @last
sivtr filter terminal -m panic --json | sivtr var set failures
sivtr var list
sivtr var merge ctx @failures @last[1]
sivtr var drop ctx @noise

nav

sivtr nav <SOURCE> <MOTION> [OPTIONS]

Moves WorkSet anchors deterministically through record/part/session structure. nav does not default-expand children; child movement must specify a 1-based index with >N.

Motion tokens compose left-to-right:

Token	Meaning
<	Parent. Part/line to record; record to containing session records.
>N	Nth child, 1-based. Record children are its parts.
+N	Next sibling by N at the current level.
-N	Previous sibling by N at the current level.
[A..B]	Sibling window at the current level, relative to the current anchor.
~	Containing session records.

Options:

Option	Meaning
--cwd <PATH>	Workspace directory used to resolve records
--json	Alias for --format workset
--refs	Alias for --format refs
--format <FORMAT>, -f <FORMAT>	full, timeline, compact, md, refs, or workset

Examples:

sivtr nav @hit '<' --refs
sivtr nav @hit '>1' --refs
sivtr nav @hit '<+1>1' --refs
sivtr nav @hit '<[-2..+2]' --refs
sivtr nav @hit '~' --refs

Use zoom for simple neighboring record context. Use nav when the exact movement path matters.

show

sivtr show <SOURCE> [OPTIONS]

Prints a workspace ref or WorkSet source such as @last, @name, or @.

Ref syntax:

source/session[/record-or-turn[/p<part>]]

Options:

Option	Meaning
--cwd <PATH>	Workspace directory used to resolve sessions
--json	Alias for --format workset
--refs	Alias for --format refs
--full	Alias for --format full
--format <FORMAT>, -f <FORMAT>	full, timeline, compact, md, refs, or workset

Examples:

sivtr show claude/<session-id>
sivtr show claude/<session-id>/3
sivtr show claude/<session-id>/3/p7 --json
sivtr show terminal/current/2
sivtr show desk:terminal/session_42/3/p1 --full
sivtr show @last --full
sivtr show @ctx -f timeline

serve

sivtr serve <COMMAND>

Manages the local remote-memory daemon. Share and remote commands auto-start it when needed.

Command	Meaning
start	Start the daemon in the background
stop	Stop the running daemon cleanly
restart	Restart the daemon
status	Show daemon identity and runtime state
logs	Print the daemon log path
foreground	Run the daemon in the foreground

sivtr serve start
sivtr serve status
sivtr serve logs
sivtr serve stop

share

sivtr share [OPTIONS]
sivtr share <COMMAND>

Explicitly shares a local workspace for remote peers. Bare sivtr share is interactive: pick a workspace (Enter = current) and ensure the share exists (no invite). Create an invite with sivtr share invite <name>.

Default interactive options:

Option	Meaning
--path <PATH>	Workspace path; skips the picker after confirm
--name <NAME>	Stable share name; defaults to the workspace directory name
--no-redact	Disable secret redaction for this share

Subcommands:

Command	Meaning
add [PATH] [--name NAME] [--no-redact]	Expose a workspace through the daemon
list	List local shares
remove <SHARE>	Remove a share and all grants and invitations attached to it
enable <SHARE> / disable <SHARE>	Toggle a share without deleting it
invite <SHARE> [--expires DURATION]	Create a single-use invite; prints the bare key on stdout
grants <SHARE>	List active peer grants for a share
revoke <SHARE> <PEER>	Revoke a peer’s access to a share

sivtr share
sivtr share add --name alice-desk
sivtr share invite alice-desk --expires 10m
sivtr share list
sivtr share grants alice-desk
sivtr share revoke alice-desk <peer>

remote

sivtr remote <COMMAND>

Names a peer share in the current git workspace (like git remote). The name is the left side of name:path refs.

Command	Meaning
list	List remotes in the current workspace
add <NAME> <INVITE>	Redeem an invite and add the remote
remove <NAME>	Remove a local remote name (grant remains until the owner revokes it)
rename <NAME> <NEW>	Rename a remote in this workspace
test <NAME>	Reachability + authorization probe

sivtr remote add desk <invite-key>
sivtr remote test desk
sivtr remote list
sivtr s desk:terminal --status failure --latest 5 --refs
sivtr show desk:agent/<session>/3 --full
sivtr remote rename desk bob-desk
sivtr remote remove desk

peer

sivtr peer <COMMAND>

Command	Meaning
list	List known peer identities
forget <PEER>	Forget a peer and remove all local remotes and grants involving it

sivtr peer list
sivtr peer forget <peer>

workspace

sivtr workspace [list]
sivtr ws list

Lists known local workspaces and their origin labels for name:body refs (for example docs:codex/4). Alias: sivtr ws.

sivtr ws list

Exact syntax for every remote subcommand is above. For the model, setup path, and safety defaults, see Remote Access. For a teammate scenario, see Remote collaboration memory.

mcp

sivtr mcp serve
sivtr mcp install [OPTIONS]
sivtr mcp uninstall [OPTIONS]
sivtr mcp print-config <claude|cursor|codex>

Read-only MCP server for agent hosts, plus one-shot host registration.

serve

Runs the MCP server on stdio:

sivtr mcp serve
sivtr mcp serve --idle-exit 60

--idle-exit <SECS> makes the server exit after that many seconds with no tool calls; the host respawns it on the next tool use, so an idle server never lingers (each agent session otherwise keeps one alive until it exits). 0 / absent = stay alive until the host closes stdin. The same value can be set globally with the [mcp] idle_exit_secs config key; the CLI flag wins over the config.

Tools:

Tool	Purpose
sivtr_search	Search terminal/agent memory; supports desk:... origins. Same bounds as CLI search (latest=5 by default).
sivtr_show	Expand a ref or WorkSet handle
sivtr_zoom	Neighboring record context
sivtr_filter	Narrow @last / @name / a source
sivtr_status	Version, hooks, providers, daemon, ws local origins, remotes, vars

install / uninstall

Writes or removes the sivtr MCP entry in agent host config (same idea as codegraph install):

sivtr mcp install -y                      # detect installed hosts, global
sivtr mcp install -p claude,cursor -l global
sivtr mcp install -p claude -l local      # project .mcp.json
sivtr mcp uninstall -p all -y

Flag	Meaning
-p, --provider	Provider host(s): claude, cursor, codex, opencode, openclaw, grok, pi, hermes, or all. Omit to detect installed hosts.
-l, --location	global (default) or local
-y, --yes	Non-interactive

Install locations (registry-driven; paths are host defaults):

Target	Global path
Claude Code	~/.claude.json → mcpServers.sivtr
Cursor	~/.cursor/mcp.json → mcpServers.sivtr
Codex	~/.codex/config.toml → [mcp_servers.sivtr]
OpenCode	OpenCode MCP config → mcp.sivtr
OpenClaw	OpenClaw config → mcp.servers.sivtr
Grok	Grok config TOML → MCP entry
Hermes	Hermes YAML → mcp_servers.sivtr
Pi	Pi config → mcpServers.sivtr

Registered command is always:

sivtr mcp serve

print-config

Print a snippet without writing files:

sivtr mcp print-config claude
sivtr mcp print-config cursor
sivtr mcp print-config codex
sivtr mcp print-config grok

MCP is not a full CLI mirror. Interactive, write, and capture commands stay on the CLI. Strategy still lives in the sivtr-memory skill.

version

sivtr version [--verbose]

Prints the Sivtr version. Use --verbose to diagnose which binary is running and whether it differs from the local debug build in the current repository.

sivtr version
sivtr version --verbose

Verbose output includes:

• package version;
• binary path;
• current working directory;
• debug/release profile;
• git commit and build time when available;
• detected repo root;
• local target/debug/sivtr binary status;
• a warning when a different global binary is being used inside the repo.

history

sivtr history [COMMAND]

Subcommands:

Command	Meaning
list [-l, --limit <N>]	List recent entries
search <KEYWORD> [-l, --limit <N>]	Search saved capture history
show <ID>	Show a specific history entry

If no history subcommand is provided, list is used.

config

sivtr config [COMMAND]

Subcommands:

Command	Meaning
show	Show config path and content
init	Create default config
edit	Open config in editor

If no config subcommand is provided, show is used.

hotkey

sivtr hotkey [COMMAND]

Subcommands:

Command	Meaning
start [--chord <CHORD>] [--provider <PROVIDER>]	Start Windows global hotkey daemon
status	Show daemon status
stop	Stop daemon

If no hotkey subcommand is provided, status is used.

Examples:

sivtr hotkey start
sivtr hotkey start --chord alt+y
sivtr hotkey start --provider claude
sivtr hotkey status
sivtr hotkey stop

codex export

sivtr codex export --dest <PATH> [OPTIONS]

Exports local Codex rollout JSONL files into a target directory containing a sessions/ tree.

Options:

Option	Meaning
--dest <PATH>	Destination directory that will receive the sessions/ tree
--limit <N>	Keep only newest N session files; 0 means export all
--watch	Continue mirroring with native filesystem wakeups and periodic reconciliation
--interval <SECONDS>	Maximum seconds between reconciliation passes; default is 1
--interval-ms <MILLISECONDS>	Maximum milliseconds between reconciliation passes; overrides --interval

Native filesystem events can trigger an earlier pass. If native watching is unavailable or disconnects, export falls back to periodic polling. Stable files are not republished; verified append-only growth writes only the new suffix. After a restart or filesystem migration, export verifies file content before resuming incremental writes.

Examples:

sivtr codex export --dest /srv/sivtr/root-codex
sivtr codex export --dest /srv/sivtr/root-codex --watch
sivtr codex export --dest /srv/sivtr/root-codex --limit 100

clear

sivtr clear [--all]

Clears current shell session logs. --all clears all recorded session logs and state files managed by sivtr.

Shared syntax

See Selectors and Filters for recency selectors, --session, providers, --regex, --lines, --ansi, --print, and workspace refs.