CLI Reference

Complete reference for all sfs commands.

Global Options

sfs [OPTIONS] COMMAND [ARGS]...

Option	Description
`--help`	Show help and exit

`sfs list`

List captured sessions.

sfs list [OPTIONS]

Option	Type	Default	Description
`--tool`	string	—	Filter by source tool (e.g., `claude-code`)
`--since`	string	—	Show sessions since time (`7d`, `24h`, or ISO date)
`--tag`	string	—	Filter by tag
`--sort`	string	`recent`	Sort order: `recent`, `oldest`, `messages`, `tokens`
`--json`	flag	`false`	Output as JSON
`--quiet`, `-q`	flag	`false`	Only print session IDs

Example:

$ sfs list --since 7d --sort tokens

                       Sessions (5)
┌──────────────┬─────────────┬────────┬──────────┬───────────┐
│ ID           │ Tool        │ Model  │ Messages │ Title     │
├──────────────┼─────────────┼────────┼──────────┼───────────┤
│ a1b2c3d4e5f6 │ claude-code │ opus-4 │       23 │ Debug ... │
└──────────────┴─────────────┴────────┴──────────┴───────────┘

`sfs show`

Show session details.

sfs show SESSION_ID [OPTIONS]

Argument	Required	Description
`SESSION_ID`	yes	Session ID or prefix (min 4 chars)

Option	Type	Default	Description
`--messages`, `-m`	flag	`false`	Show conversation messages
`--cost`, `-c`	flag	`false`	Show cost estimate
`--page-size`	int	`20`	Messages per page (with `--messages`)

Example:

$ sfs show a1b2 --cost

╭──────────── Session Details ────────────╮
│ Session ID: a1b2c3d4-e5f6-...          │
│ Title: Debug auth flow                  │
│ Tool: claude-code 1.0.23               │
│ Model: claude-opus-4 (anthropic)       │
│ Messages: 23                            │
│ Input tokens: 34,200                    │
│ Output tokens: 12,800                   │
╰─────────────────────────────────────────╯
╭──────────── Cost Estimate ──────────────╮
│ Input cost: $0.5130                     │
│ Output cost: $0.9600                    │
│ Total: $1.4730                          │
╰─────────────────────────────────────────╯

`sfs resume`

Resume a captured session in any supported AI tool.

sfs resume SESSION_ID [OPTIONS]

Argument	Required	Description
`SESSION_ID`	yes	Session ID or prefix

Option	Type	Default	Description
`--project`	path	—	Target project path (overrides workspace)
`--in`	string	`claude-code`	Target tool: `claude-code`, `codex`, `copilot`, or `gemini`
`--model`, `-m`	string	—	Model to use in target tool (e.g. `gpt-4.1`, `claude-sonnet-4`, `gemini-2.5-pro`)
`--no-rules-sync`	flag	`false`	Skip preflight of the target tool’s project rules file. Per-invocation only.
`--force-rules`	flag	`false`	Overwrite an unmanaged target-tool rules file with SessionFS-managed content. One-time permission — the file becomes SessionFS-managed afterward and subsequent resumes refresh it normally.

Converts the session to the target tool’s native format and injects it into that tool’s session storage. Cursor, Cline, Roo Code, and Amp are capture-only — --in cursor (and the others) is rejected with an error. Use --in with one of the four supported resume targets instead.

Before launching the target tool, sfs resume preflights the tool’s project rules file from the current canonical SessionFS rules. Missing files are written; SessionFS-managed files are refreshed; unmanaged files are left alone with a warning on stderr unless --force-rules is passed. Preflight failures are non-fatal — resume still exits 0. See Resume-Time Rules Sync for the full policy.

--model support per tool:

Claude Code: passed as --model to the claude binary
Codex: used in session injection and codex resume --model
Gemini: passed as --model to the gemini binary
Copilot: not supported (warns, uses Copilot’s default)

If omitted, each tool uses its own default model.

Examples:

$ sfs resume ses_abc123 --in codex

Source session used rules v3 (sessionfs).
Current project rules are v5.
Synced codex.md from SessionFS rules v5.
Launching codex resume ...

Session resumed successfully.
  CC Session ID: abc123-def456
  JSONL: /Users/me/.claude/projects/.../abc123-def456.jsonl
  Messages: 23

Skip preflight for a one-off resume:

$ sfs resume ses_abc123 --in codex --no-rules-sync

Take ownership of a hand-written codex.md:

$ sfs resume ses_abc123 --in codex --force-rules

`sfs checkpoint`

Create a named checkpoint of a session’s current state.

sfs checkpoint SESSION_ID --name NAME

Argument	Required	Description
`SESSION_ID`	yes	Session ID or prefix

Option	Type	Default	Description
`--name`	string	required	Checkpoint name

Example:

$ sfs checkpoint a1b2 --name "before-refactor"

Checkpoint 'before-refactor' created for session a1b2c3d4e5f6.

`sfs fork`

Fork a session into a new independent session.

sfs fork SESSION_ID --name NAME [OPTIONS]

Argument	Required	Description
`SESSION_ID`	yes	Session ID or prefix

Option	Type	Default	Description
`--name`	string	required	Title for the forked session
`--from-checkpoint`	string	—	Fork from a named checkpoint instead of current state

Example:

$ sfs fork a1b2 --name "Try different approach"

Forked session created: f6e5d4c3b2a1
  Title: Try different approach
  Parent: a1b2c3d4e5f6

`sfs export`

Export a session to a file.

sfs export SESSION_ID [OPTIONS]

Argument	Required	Description
`SESSION_ID`	yes	Session ID or prefix

Option	Type	Default	Description
`--format`	string	`sfs`	Export format: `sfs`, `markdown`, `claude-code`
`--output`, `-o`	path	`.`	Output directory

Example:

$ sfs export a1b2 --format markdown -o ~/exports

Exported to /Users/me/exports/a1b2c3d4-e5f6-....md

`sfs import`

Import sessions from external sources.

sfs import [FILE] [OPTIONS]

Argument	Required	Description
`FILE`	no	File to import (for file-based import)

Option	Type	Default	Description
`--from`	string	—	Import source: `claude-code`
`--format`	string	—	Input format (for file import)

Example:

# Import all Claude Code sessions
$ sfs import --from claude-code

Found 47 Claude Code session(s).
Imported 47 new session(s).

`sfs daemon start`

Start the SessionFS daemon in the background.

sfs daemon start [OPTIONS]

Option	Type	Default	Description
`--config`	path	—	Path to `config.toml`
`--log-level`	string	`INFO`	Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`

Example:

$ sfs daemon start

Daemon started (PID 12345).
Logs: /Users/me/.sessionfs/daemon.log

`sfs daemon stop`

Stop the running daemon.

sfs daemon stop

Example:

$ sfs daemon stop

Sent SIGTERM to daemon (PID 12345).

`sfs daemon status`

Show daemon status and watcher health.

sfs daemon status

Example:

$ sfs daemon status

         SessionFS Daemon Status
┌──────────────────┬────────────────────────┐
│ Field            │ Value                  │
├──────────────────┼────────────────────────┤
│ PID              │ 12345                  │
│ Running          │ Yes                    │
│ Sessions         │ 47                     │
│ Watcher: cc      │ healthy (47 sessions)  │
└──────────────────┴────────────────────────┘

`sfs daemon logs`

Show daemon log output.

sfs daemon logs [OPTIONS]

Option	Type	Default	Description
`--lines`, `-n`	int	`50`	Number of lines to show
`--follow`, `-f`	flag	`false`	Follow log output (like `tail -f`)

Example:

$ sfs daemon logs -n 10

2026-03-20 14:30:00 sfsd INFO sfsd starting with 1 watcher(s)
2026-03-20 14:30:01 sfsd INFO sfsd running (PID 12345)

`sfs config show`

Show the current configuration.

sfs config show

Example:

$ sfs config show

Config: /Users/me/.sessionfs/config.toml

log_level = "INFO"
scan_interval_s = 5.0

[claude_code]
enabled = true

`sfs config set`

Set a configuration value.

sfs config set KEY VALUE

Argument	Required	Description
`KEY`	yes	Config key (dotted path, e.g., `claude_code.enabled`)
`VALUE`	yes	Value to set

Example:

$ sfs config set scan_interval_s 10

Set scan_interval_s = 10

`sfs alias`

Set or clear a session alias for easy reference.

sfs alias SESSION_ID [ALIAS]

Argument	Required	Description
`SESSION_ID`	yes	Session ID or prefix
`ALIAS`	no	Alias name (omit to clear)

Example:

$ sfs alias ses_a1b2 auth-debug
Alias set: auth-debug -> ses_a1b2c3d4e5f6

$ sfs show auth-debug   # Now works with alias

`sfs search`

Full-text search across all local sessions.

sfs search QUERY [OPTIONS]

Argument	Required	Description
`QUERY`	yes	Search text

Option	Type	Default	Description
`--tool`	string	—	Filter by source tool
`--cloud`	flag	`false`	Search cloud sessions instead of local
`--json`	flag	`false`	Output as JSON

Example:

$ sfs search "rate limiting middleware"

2 results:
  ses_a1b2  claude-code  "...added rate limiting middleware to..."
  ses_c3d4  codex        "...the rate limiter should handle..."

`sfs summary`

Show a session summary — files changed, tests run, commands executed.

sfs summary SESSION_ID [OPTIONS]

Argument	Required	Description
`SESSION_ID`	yes	Session ID or prefix

Option	Type	Default	Description
`--format`	string	—	Export format: `md` for markdown

Example:

$ sfs summary ses_a1b2

Debug auth middleware
2.3h | 327 msgs | 28 tool calls | Claude Code
Branch: feature/auth-fix @ a1b2c3d

Files modified (3):
  src/auth/middleware.py
  src/auth/tokens.py
  tests/test_auth.py

Commands: 34
Tests: 6 runs (5 passed, 1 failed)
Packages: pyjwt, redis

`sfs audit`

Audit a session for hallucinations using LLM-as-a-Judge.

sfs audit SESSION_ID [OPTIONS]

Argument	Required	Description
`SESSION_ID`	yes	Session ID or prefix

Option	Type	Default	Description
`--model`	string	`claude-sonnet-4`	Judge LLM model
`--api-key`	string	—	LLM API key (or use config/env)
`--provider`	string	auto-detect	Provider: anthropic, openai, google, openrouter
`--base-url`	string	—	Custom OpenAI-compatible endpoint (LiteLLM, vLLM, Ollama)
`--consensus`	flag	`false`	Run 3 passes, report where 2+ agree (3x cost)
`--report`	flag	`false`	Show existing report only
`--json`	flag	`false`	Output as JSON
`--format`	string	—	Export: `json`, `markdown`, `csv`

Example:

$ sfs audit ses_a1b2 --model gpt-4o --base-url https://litellm.internal/v1

Trust Score: 74%
3 contradictions | 9 unverified | 42 verified

CRITICAL  test_result   msg #34  "Test passes" -> exit code 1
HIGH      file_existence msg #12  "Created validator.py" -> No Write call

`sfs delete`

Delete a session from the cloud, the local device, or both. Requires an explicit scope flag — there is no default.

sfs delete SESSION_ID [OPTIONS]

Argument	Required	Description
`SESSION_ID`	yes	Session ID or prefix

Option	Type	Default	Description
`--cloud`	flag	—	Delete from server, keep local copy
`--local`	flag	—	Remove local copy, keep cloud copy
`--everywhere`	flag	—	Delete from both server and local
`--force`	flag	`false`	Skip confirmation prompt

If no scope flag is provided, the command prints an error and exits.

Examples:

# Remove from cloud only (local copy stays)
$ sfs delete ses_abc123 --cloud
Delete ses_abc123 from cloud? Local copy will be kept. [y/N] y
Deleted from cloud. Recoverable for 30 days.

# Remove from this device only
$ sfs delete ses_abc123 --local
Delete ses_abc123 from this device? Cloud copy is unaffected. [y/N] y
Removed local copy.

# Delete everywhere (recoverable for 30 days)
$ sfs delete ses_abc123 --everywhere --force
Deleted from cloud and local device. Recoverable for 30 days.

See Delete Lifecycle for full details on retention, recovery, and sync behavior.

`sfs trash`

List soft-deleted sessions in the retention window.

sfs trash

Example:

$ sfs trash

Trash (3 sessions -- purge after 30 days)

ID           Deleted       Scope        Purge after
ses_abc123   2 days ago    cloud        2026-05-14
ses_def456   5 days ago    everywhere   2026-05-11
ses_ghi789   12 days ago   everywhere   2026-04-28

`sfs restore`

Undo a soft-delete. Clears the server-side deletion flag and removes the session from the local exclusion list.

sfs restore SESSION_ID

Argument	Required	Description
`SESSION_ID`	yes	Session ID or prefix

If the local copy was also removed (scope was everywhere), run sfs pull <id> afterward to re-download it.

Example:

$ sfs restore ses_abc123
Session restored. Run 'sfs pull ses_abc123' to re-download locally.

`sfs push`

Push a session to the cloud.

sfs push SESSION_ID

`sfs pull`

Pull a session from the cloud.

sfs pull SESSION_ID

`sfs pull-handoff`

Pull a session from a handoff link.

sfs pull-handoff HANDOFF_ID

Example:

$ sfs pull-handoff hnd_x7k9

Session pulled. 47 messages.
Run: sfs resume ses_abc --in claude-code

`sfs list-remote`

List sessions stored on the cloud server.

sfs list-remote [OPTIONS]

Option	Type	Default	Description
`--page`	int	`1`	Page number
`--page-size`	int	`20`	Results per page

`sfs handoff`

Hand off a session to a teammate with email notification.

sfs handoff SESSION_ID --to EMAIL [OPTIONS]

Option	Type	Default	Description
`--to`	string	required	Recipient email
`--message`	string	—	Message to include in the email

`sfs sync`

Bidirectional sync and autosync management.

`sfs sync` (default)

Run bidirectional sync — push local changes, pull remote-only sessions.

sfs sync

`sfs sync auto`

Set autosync mode.

sfs sync auto --mode MODE

Mode	Behavior
`off`	No autosync (default). Manual `sfs push` only.
`all`	Every new or updated session auto-pushes to cloud.
`selective`	Only sessions in the watchlist auto-push.

`sfs sync watch`

Add sessions to the autosync watchlist (selective mode).

sfs sync watch SESSION_ID [SESSION_ID...]

`sfs sync unwatch`

Remove sessions from the autosync watchlist.

sfs sync unwatch SESSION_ID [SESSION_ID...]

`sfs sync watchlist`

Show all sessions in the autosync watchlist.

sfs sync watchlist

`sfs sync status`

Show current autosync mode, counts, and storage usage.

sfs sync status

`sfs project`

Manage shared project context — a single document shared across the team via MCP.

`sfs project init`

Create a project context for the current repo (matched by git remote).

sfs project init

`sfs project show`

Display the current project context with metadata.

sfs project show

`sfs project edit`

Open the context document in $EDITOR. Changes upload on save.

sfs project edit

`sfs project set-context`

Set project context from a file.

sfs project set-context FILE

`sfs project get-context`

Output raw project context markdown to stdout.

sfs project get-context

`sfs project compile`

Compile pending knowledge entries into the project context document.

sfs project compile

Example:

$ sfs project compile

Compiling pending entries...
Project context updated. 12 entries compiled.

`sfs project rebuild`

Force a full re-compile of the project context. Resets compiled_at=NULL on all active claims and clears context_document, so the next compile pass pulls every active claim from scratch. Useful on settled projects where normal compile would be a no-op.

sfs project rebuild

Example:

$ sfs project rebuild

Project context reset. Run `sfs project compile` to regenerate.

`sfs project entries`

List knowledge entries for this project.

sfs project entries [OPTIONS]

Option	Type	Default	Description
`--pending`	flag	`false`	Show only pending (uncompiled) entries
`--type`	string	—	Filter by type: `decision`, `pattern`, `discovery`, `convention`, `bug`, `dependency`
`--limit`	int	`20`	Max entries to show

Example:

$ sfs project entries --type decision --limit 5

┌────┬──────────┬────────────────────────────────────────┬──────────┬──────────────────┬──────────┐
│ ID │ Type     │ Content                                │ Age      │ Session          │ Status   │
├────┼──────────┼────────────────────────────────────────┼──────────┼──────────────────┼──────────┤
│ 42 │ decision │ HTTP + ETags only, no WebSockets       │ 3d ago   │ ses_a1b2c3d4e5.. │ compiled │
│ 38 │ decision │ Sessions are append-only                │ 5d ago   │ ses_f6e5d4c3b2.. │ pending  │
└────┴──────────┴────────────────────────────────────────┴──────────┴──────────────────┴──────────┘
Showing 2 of 2 entries

`sfs project ask`

Ask a question about the project using the knowledge base.

sfs project ask QUESTION

Argument	Required	Description
`QUESTION`	yes	Question about the project

Searches knowledge entries and project context for relevant answers. Optionally saves the Q&A back to the knowledge base.

Example:

$ sfs project ask "How does session conflict resolution work?"

╭─ Question: How does session conflict resolution work? ─╮
╰────────────────────────────────────────────────────────╯

Matching Knowledge Entries (2):
  [decision] Sessions are append-only — conflict resolution appends both sides
    Session: ses_a1b2 | 2026-03-15 | confidence: 95%
  [pattern] Merge strategy: append both sides rather than 3-way merge
    Session: ses_c3d4 | 2026-03-10 | confidence: 90%

Related Sessions:
  sfs show ses_a1b2
  sfs show ses_c3d4

Save this Q&A to the knowledge base? [y/N]:

`sfs project pages`

List wiki pages for this project.

sfs project pages

Example:

$ sfs project pages

┌──────────────────┬──────────────────────────┬──────────┬───────┬─────────┬──────┐
│ Slug             │ Title                    │ Type     │ Words │ Entries │ Auto │
├──────────────────┼──────────────────────────┼──────────┼───────┼─────────┼──────┤
│ session-format   │ Session Format (.sfs)    │ concept  │   420 │       8 │ yes  │
│ conflict-resolve │ Conflict Resolution      │ concept  │   310 │       5 │ yes  │
│ daemon-arch      │ Daemon Architecture      │ manual   │   850 │       0 │ no   │
└──────────────────┴──────────────────────────┴──────────┴───────┴─────────┴──────┘
3 pages

`sfs project page`

View a wiki page by slug.

sfs project page SLUG

Argument	Required	Description
`SLUG`	yes	Page slug

Example:

$ sfs project page session-format

╭──────────── Session Format (.sfs) ────────────╮
│ A .sfs session is a directory containing:     │
│ manifest.json, messages.jsonl, workspace.json, │
│ tools.json. All file paths within are relative │
│ to workspace root.                             │
│ ...                                            │
╰──────────── session-format (auto-generated) ──╯

Backlinks:
  entry:42 (references)
  entry:38 (defines)

`sfs project health`

Run health checks on the project knowledge base.

sfs project health

Reports entry counts, compilation status, staleness, and a health score.

Example:

$ sfs project health

Project Health: sessionfs

  ✓  Context document exists (2400 words, 8 sections)
  ✓  45 knowledge entries (38 compiled, 2 dismissed)
  ⚠  5 entries pending compilation
  ✓  Last compiled: 2026-03-28
  ✓  Context appears up to date

Health Score: 90%

`sfs project regenerate`

Regenerate an auto-generated concept article from the latest knowledge entries.

sfs project regenerate SLUG

Argument	Required	Description
`SLUG`	yes	Page slug to regenerate

Example:

$ sfs project regenerate session-format

Regenerating page 'session-format'...
Article regenerated (420 words from 8 entries).

`sfs project set`

Update project settings.

sfs project set [OPTIONS]

Option	Type	Description
`--auto-narrative` / `--no-auto-narrative`	flag	Enable or disable auto-narrative generation on sync

Example:

$ sfs project set --auto-narrative

auto_narrative = True

`sfs project dismiss`

Dismiss an irrelevant knowledge entry so it is excluded from future compilations.

sfs project dismiss ENTRY_ID

Argument	Required	Description
`ENTRY_ID`	yes	Numeric entry ID

Example:

$ sfs project dismiss 38

Entry 38 dismissed.

`sfs rules`

Manage canonical project rules and compile them into the tool-specific files each AI agent reads (CLAUDE.md, codex.md, .cursorrules, .github/copilot-instructions.md, GEMINI.md). See Rules Portability for the full reference.

`sfs rules init`

Seed canonical rules for the current project. Detects the git remote, preselects enabled tools from existing rule files + recent tool usage, and optionally imports a single unmanaged rule file as the canonical seed.

sfs rules init [--local-only]

Option	Type	Default	Description
`--local-only`	flag	`false`	Gitignore the compiled rule files instead of committing them

Only the five v0.9.9-supported tools are preselected: claude-code, codex, cursor, copilot, gemini. The picker shows the reason for each preselection (file present, recent usage, or manual pick).

Example:

$ sfs rules init

Detected rule files:
  CLAUDE.md       (reason: file present)
  .cursorrules    (reason: file present)

Recent tool usage (last 90 days):
  codex           (reason: recent usage)

Enable these tools? [Y/n]
Seeded canonical rules for myorg/my-project.
Run 'sfs rules edit' to edit preferences, then 'sfs rules compile'.

`sfs rules edit`

Open the canonical static_rules document in $EDITOR.

sfs rules edit

`sfs rules show`

Show current canonical version, enabled tools, knowledge/context injection config, and whether compiled outputs are in sync.

sfs rules show

Example:

$ sfs rules show

Project: myorg/my-project
Canonical version: 4
Enabled tools: claude-code, codex, cursor, gemini

Knowledge injection: on
  Types: convention, decision
  Budget: 2000 tokens

Context injection: on
  Sections: overview, architecture
  Budget: 2000 tokens

Compiled outputs: in sync (last compile: 2026-04-12)

`sfs rules compile`

Compile canonical rules into tool-specific files. Deterministic — no new version is created unless a compiled output changes by hash.

sfs rules compile [--tool TOOL] [--dry-run] [--force]

Option	Type	Default	Description
`--tool`	string	—	Compile for a single tool only
`--dry-run`	flag	`false`	Show what would be written without touching disk
`--force`	flag	`false`	Overwrite files not managed by SessionFS

Example:

$ sfs rules compile

Compiling canonical rules v4...
  CLAUDE.md                               written  (sha256:9a1c…)
  codex.md                                written  (sha256:4e2f…)
  .cursorrules                            written  (sha256:b7d1…)
  .github/copilot-instructions.md         written  (sha256:c3a8…)
  GEMINI.md                               written  (sha256:5f90…)

New rules version: 5

SessionFS refuses to overwrite a rule file that is not managed (no SessionFS marker and not created by sfs rules init). Use sfs rules init to import it, or pass --force.

`sfs rules push`

Push the canonical record and latest compiled version to the SessionFS API. Uses optimistic concurrency — a stale write returns 409 Conflict.

sfs rules push

`sfs rules pull`

Pull canonical rules from the SessionFS API. Run sfs rules compile afterwards to regenerate tool files.

sfs rules pull

`sfs rules emit`

Print the latest compiled rules for a tool to stdout. Reads from the local rule cache populated by sfs rules compile and sfs rules pull — never hits the network.

sfs rules emit --tool TOOL [--format hook|file]

Option	Type	Default	Description
`--tool`	string	required	Target tool (`claude-code`, `codex`, `cursor`, `copilot`, `gemini`)
`--format`	string	`hook`	`hook` for Claude Code’s hook JSON spec, `file` for the plain compiled body

--format hook is the format the SessionStart hook installed by sfs hooks install consumes. --format file is useful for piping the compiled body into another tool or inspecting it from the shell. If the local cache is empty, the command prints an empty payload and exits 0 — it never breaks Claude Code startup.

Example:

$ sfs rules emit --tool claude-code --format hook
{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "..."
  }
}

`sfs hooks`

Manage SessionFS hooks for tools with native hook support. v0.9.9.9 supports Claude Code only. See Hook-based injection for the full reference.

`sfs hooks install`

Wire the SessionFS SessionStart hook into the target tool’s settings. The hook calls sfs rules emit on every session start and pipes the compiled rules into the system prompt. Idempotent — running twice does not duplicate the entry.

sfs hooks install --for TOOL [--user|--project] [--force]

Option	Type	Default	Description
`--for`	string	required	Target tool (`claude-code` only in v0.9.9.9)
`--user`	flag	default	Install at user scope (`~/.claude/settings.json`)
`--project`	flag	`false`	Install at project scope (`.claude/settings.json` in repo root)
`--force`	flag	`false`	Skip the conflict warning when a managed `CLAUDE.md` already exists

Example:

$ sfs hooks install --for claude-code
Hook installed: ~/.claude/settings.json (SessionStart)
SessionFS will inject project rules at every Claude Code startup.

`sfs hooks uninstall`

Remove the SessionFS-managed hook entry from the target tool’s settings. Idempotent — no-op if not installed.

sfs hooks uninstall --for TOOL [--user|--project] [--force]

Option	Type	Default	Description
`--for`	string	required	Target tool (`claude-code` only in v0.9.9.9)
`--user`	flag	default	Uninstall from user scope
`--project`	flag	`false`	Uninstall from project scope
`--force`	flag	`false`	Skip the confirmation prompt

`sfs hooks status`

Show which SessionFS hooks are installed across supported tools and scopes. Tools without native hook support appear as N/A.

sfs hooks status

Example:

$ sfs hooks status

SessionFS Hooks
───────────────
claude-code (user):     INSTALLED at ~/.claude/settings.json (SessionStart)
claude-code (project):  not installed
codex:                  N/A (no native hook system)
gemini:                 N/A
cursor:                 N/A

`sfs storage`

Manage local session storage.

`sfs storage` (default)

Show local disk usage, session counts, and retention policy.

sfs storage

`sfs storage prune`

Prune old sessions to free disk space.

sfs storage prune [OPTIONS]

Option	Type	Default	Description
`--dry-run`	flag	`false`	Show what would be pruned without deleting
`--force`	flag	`false`	Skip confirmation prompt

`sfs daemon restart`

Restart the daemon (stop + start).

sfs daemon restart

`sfs watcher`

Manage tool watchers.

`sfs watcher list`

List all tool watchers and their status.

sfs watcher list

`sfs watcher enable`

Enable a tool watcher.

sfs watcher enable TOOL

`sfs watcher disable`

Disable a tool watcher.

sfs watcher disable TOOL

`sfs auth`

Manage cloud authentication.

`sfs auth login`

Authenticate with the cloud server.

sfs auth login [OPTIONS]

Option	Type	Default	Description
`--url`	string	`https://api.sessionfs.dev`	Server URL
`--key`	string	—	API key

`sfs auth signup`

Create a new account.

sfs auth signup [OPTIONS]

Option	Type	Default	Description
`--url`	string	`https://api.sessionfs.dev`	Server URL

`sfs auth status`

Show current authentication status.

sfs auth status

`sfs mcp serve`

Start the MCP server on stdio transport.

sfs mcp serve

Tools exposed: search_sessions, get_session_context, list_recent_sessions, find_related_sessions, get_project_context, add_knowledge, update_wiki_page, list_wiki_pages, search_project_knowledge, ask_project, get_session_summary, get_audit_report.

`sfs mcp install`

Auto-configure SessionFS as an MCP server for an AI tool. Also injects knowledge-contribution instructions into the tool’s project config file.

sfs mcp install --for TOOL [OPTIONS]

Option	Type	Description
`--for`	string	Target tool: `claude-code`, `codex`, `gemini`, `cursor`, `copilot`, `amp`, `cline`, `roo-code`
`--skip-instructions`	flag	Skip injecting knowledge-contribution instructions into project config

Example:

$ sfs mcp install --for claude-code

Added SessionFS MCP server in Claude Code.
  Config: /Users/me/.claude.json
  Restart Claude Code to activate.

Appended knowledge instructions to CLAUDE.md

Your AI agent can now search past sessions:
  "Has anyone on the team seen this error before?"
  "What was the fix for the auth middleware bug?"

`sfs mcp uninstall`

Remove SessionFS MCP server registration and knowledge instructions from an AI tool.

sfs mcp uninstall --for TOOL

Option	Type	Description
`--for`	string	Target tool: `claude-code`, `codex`, `gemini`, `cursor`, `copilot`, `amp`, `cline`, `roo-code`

Example:

$ sfs mcp uninstall --for cursor

Removed SessionFS MCP server from Cursor.
  Restart Cursor to apply.
Removed knowledge instructions from .cursorrules

`sfs mcp index`

Rebuild the full-text search index from all local sessions.

sfs mcp index

Example:

$ sfs mcp index

Search index rebuilt: 47 sessions indexed.

`sfs init`

Interactive setup wizard for SessionFS. Detects installed AI coding tools, writes configuration, optionally sets up cloud sync, and starts the daemon.

sfs init

Detects: Claude Code, Cursor, Codex, Gemini CLI, Copilot, Amp, Cline, Roo Code.

Example:

$ sfs init

SessionFS Setup

Scanning for AI coding tools...
  ✓ Claude Code detected (~/.claude)
  ✓ Cursor detected (~/Library/Application Support/Cursor)
  ✓ Gemini CLI detected (~/.gemini)
  ✗ Codex not found

Found 3 tools. Track all? [Y/n]: y

Cloud sync lets you access sessions from any machine and share with teammates.

Set up cloud sync now? [y/N]: n

Start the SessionFS daemon now? [Y/n]: y

✓ Daemon started! Watching 3 tools.
  Sessions stored in: /Users/me/.sessionfs/sessions

Next steps:
  sfs list              — View captured sessions
  sfs show <id>         — Inspect a session
  sfs resume <id>       — Resume in any tool
  sfs search "query"    — Search past sessions

`sfs doctor`

Run 8 health checks with auto-repair. Checks store directory, session count, index integrity, index freshness, daemon status, API reachability, authentication, and config permissions. Automatically repairs corrupted indexes.

sfs doctor

Example:

$ sfs doctor

              SessionFS Health Check
┌─────────────────────┬────────┬──────────────────────────┐
│ Check               │ Status │ Detail                   │
├─────────────────────┼────────┼──────────────────────────┤
│ Store directory      │ ✓      │ /Users/me/.sessionfs     │
│ Sessions directory   │ ✓      │ 47 session(s) on disk    │
│ Session index        │ ✓      │ 47 indexed               │
│ Index freshness      │ ✓      │ in sync                  │
│ Daemon               │ ✓      │ running (PID 12345)      │
│ API server           │ ✓      │ reachable (https://...)  │
│ Authentication       │ ✓      │ me@example.com (team)    │
│ Config permissions   │ ✓      │ permissions OK (0o600)   │
└─────────────────────┴────────┴──────────────────────────┘

`sfs dlp scan`

Scan local sessions for secrets and PHI. SessionFS ships with 22 secret patterns (API keys, access tokens, private keys, database URLs) and 14 PHI patterns (SSN, phone, credit card, medical IDs).

sfs dlp scan [SESSION_ID ...] [--mode MODE] [--format FORMAT]

Option	Description
`--mode warn\|redact\|block`	Action on findings (default: `warn`)
`--format json\|text`	Output format (default: `text`)
`--verbose`	Show matched substrings

$ sfs dlp scan ses_abc123
2 findings in ses_abc123:
  [HIGH] AWS access key in messages.jsonl:142
  [MEDIUM] Email address in messages.jsonl:89

`sfs dlp policy`

View or update the organization DLP policy. Applies server-side to all org members on sync.

sfs dlp policy [--get|--set-mode MODE|--enable|--disable]

Option	Description
`--get`	Show current policy
`--set-mode warn\|redact\|block`	Update the policy mode
`--enable`	Enable DLP scanning
`--disable`	Disable DLP scanning

When set to block, uploads containing detected secrets/PHI are rejected. When set to redact, findings are automatically redacted before storage.

`sfs security scan`

Run local security checks: config file permissions, API key exposure in shell configs, dependency vulnerabilities (via pip-audit), and stale sessions.

sfs security scan

Example:

$ sfs security scan

Security Scan Results
────────────────────────────────────────
✓ Config permissions: OK (0o600)
✓ API key exposure: No keys found in shell configs
✓ Dependencies: No vulnerabilities found
✓ Stale sessions: No stale sessions

All checks passed.

`sfs security fix`

Auto-fix security issues where safe to do so. Fixes config permissions, upgrades vulnerable packages (with confirmation), and warns about issues requiring manual action.

sfs security fix [OPTIONS]

Option	Type	Default	Description
`--yes`, `-y`	flag	`false`	Skip confirmation prompts

Example:

$ sfs security fix

Security Fix
────────────────────────────────────────
✓ Fixed config permissions: 0o644 -> 0o600

Vulnerable packages with available fixes:
  - cryptography>=44.0.0

Upgrade these packages? [y/N]: y
✓ Upgraded 1 packages

Fixed 2 issue(s).

`sfs admin reindex`

Re-extract metadata for all cloud sessions (admin only).

sfs admin reindex

CLI Reference

Global Options

sfs list

sfs show

sfs resume

sfs checkpoint

sfs fork

sfs export

sfs import

sfs daemon start

sfs daemon stop

sfs daemon status

sfs daemon logs

sfs config show

sfs config set

sfs alias

sfs search

sfs summary

sfs audit

sfs delete

sfs trash

sfs restore

sfs push

sfs pull

sfs pull-handoff

sfs list-remote

sfs handoff

sfs sync

sfs sync (default)

sfs sync auto

sfs sync watch

sfs sync unwatch

sfs sync watchlist

sfs sync status

sfs project

sfs project init

sfs project show

sfs project edit

sfs project set-context

sfs project get-context

sfs project compile

sfs project rebuild

sfs project entries

sfs project ask

sfs project pages

sfs project page

sfs project health

sfs project regenerate

sfs project set

sfs project dismiss

sfs rules

sfs rules init

sfs rules edit

sfs rules show

sfs rules compile

sfs rules push

sfs rules pull

sfs rules emit

sfs hooks

sfs hooks install

sfs hooks uninstall

sfs hooks status

sfs storage

sfs storage (default)

sfs storage prune

sfs daemon restart

sfs watcher

sfs watcher list

sfs watcher enable

sfs watcher disable

sfs auth

sfs auth login

sfs auth signup

sfs auth status

sfs mcp serve

sfs mcp install

sfs mcp uninstall

sfs mcp index

sfs init

sfs doctor

`sfs list`

`sfs show`

`sfs resume`

`sfs checkpoint`

`sfs fork`

`sfs export`

`sfs import`

`sfs daemon start`

`sfs daemon stop`

`sfs daemon status`

`sfs daemon logs`

`sfs config show`

`sfs config set`

`sfs alias`

`sfs search`

`sfs summary`

`sfs audit`

`sfs delete`

`sfs trash`

`sfs restore`

`sfs push`

`sfs pull`

`sfs pull-handoff`

`sfs list-remote`

`sfs handoff`

`sfs sync`

`sfs sync` (default)

`sfs sync auto`

`sfs sync watch`

`sfs sync unwatch`

`sfs sync watchlist`

`sfs sync status`

`sfs project`

`sfs project init`

`sfs project show`

`sfs project edit`

`sfs project set-context`

`sfs project get-context`

`sfs project compile`

`sfs project rebuild`

`sfs project entries`

`sfs project ask`

`sfs project pages`

`sfs project page`

`sfs project health`

`sfs project regenerate`

`sfs project set`

`sfs project dismiss`

`sfs rules`

`sfs rules init`

`sfs rules edit`

`sfs rules show`

`sfs rules compile`

`sfs rules push`

`sfs rules pull`

`sfs rules emit`

`sfs hooks`

`sfs hooks install`

`sfs hooks uninstall`

`sfs hooks status`

`sfs storage`

`sfs storage` (default)

`sfs storage prune`

`sfs daemon restart`

`sfs watcher`

`sfs watcher list`

`sfs watcher enable`

`sfs watcher disable`

`sfs auth`

`sfs auth login`

`sfs auth signup`

`sfs auth status`

`sfs mcp serve`

`sfs mcp install`

`sfs mcp uninstall`

`sfs mcp index`

`sfs init`

`sfs doctor`

`sfs dlp scan`

`sfs dlp policy`