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, Kilo 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 config default-org

Set or clear the server-canonical default organization used when capturing sessions and creating projects. Available starting v0.10.0.

sfs config default-org [ORG_ID | --clear]

| Argument | Required | Description | |----------|----------|-------------| | ORG_ID | no | Org ID to use as default. Pass --clear to drop the preference. |

The value is persisted on the server (users.default_org_id) and returned in GET /auth/me. Membership is validated — non-members cannot set an org as default.

Example:

$ sfs config default-org acme_eng

Default organization set to acme_eng.

---

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 [--org ORG_ID | --personal]

| Option | Type | Default | Description | |--------|------|---------|-------------| | --org | string | — | Create the project scoped to the given organization (caller must be a member) | | --personal | flag | default | Create the project under the caller's personal scope |

When --org is supplied, the project inherits the org's knowledge base creation defaults at create time. If neither flag is supplied, the project is personal-scope (pre-v0.10.0 behavior).

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 | |--------|------|-------------| | --name | string | Rename the project (project-admin only). Available starting v0.12.1. | | --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 set --name "Acme Platform"

name = Acme Platform

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 project transfer

Initiate, accept, reject, or cancel a project transfer between scopes (personal ↔ org, or org ↔ org). Available starting v0.10.0.

sfs project transfer (--to TARGET | --accept ID | --reject ID | --cancel ID)

| Option | Type | Description | |--------|------|-------------| | --to | string | Initiate a transfer to the given target. Use personal for personal scope, or an org ID for an org you belong to. | | --accept | string | Accept an incoming pending transfer by ID. | | --reject | string | Reject an incoming pending transfer by ID. | | --cancel | string | Cancel an outgoing pending transfer you initiated. |

The transfer is auto-accepted when the initiator and target are the same user/org (e.g. moving a personal project into your own org). Standing is re-validated on accept/reject, so a member demoted between initiate and accept loses the right to act on the transfer.

Example:

$ sfs project transfer --to acme_eng
Transfer initiated. Awaiting target acceptance: xfer_a1b2c3

sfs project transfers

List project transfers involving the caller.

sfs project transfers [--direction incoming|outgoing] [--state pending|accepted|rejected|cancelled]

| Option | Type | Default | Description | |--------|------|---------|-------------| | --direction | string | both | Filter by incoming or outgoing transfers | | --state | string | all | Filter by transfer state |

---

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.10.1 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.10.1) | | --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.10.1) | | --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, kilo-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, kilo-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, Kilo 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 19 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

sfs admin trusted-reviewers

Register, list, or revoke an organization's trusted reviewers (org-admin only). A trusted reviewer is authorized to post review verdicts that the autonomous work queue's stop oracle will trust — typically a dedicated automated reviewer key. Tightly gated and fully audited. Available starting v0.12.1.

sfs admin trusted-reviewers (list | register | revoke) [OPTIONS]

---

sfs persona

Manage portable AI personas per project. Each persona has an ASCII name (^[A-Za-z0-9_-]{1,50}$) and a markdown body. Tier: Pro+. Available starting v0.10.1.

Commands

| Command | Description | |---------|-------------| | sfs persona list | List personas defined for the current project | | sfs persona show <name> [--raw] | Show a persona's full content (--raw skips markdown render) | | sfs persona create <name> [--content TEXT \| --file PATH] | Create a persona inline, from a file, or via $EDITOR | | sfs persona edit <name> | Open the persona content in $EDITOR | | sfs persona delete <name> [--force] | Delete a persona; refuses 409 if non-terminal tickets reference it (use --force to override) | | sfs persona assume <name> | Tag subsequent captured sessions with this persona (persona-only bundle) | | sfs persona forget | Clear the active persona bundle (refuses while a ticket bundle is in effect) |

---

sfs ticket

Manage tickets with a server-enforced FSM (suggested → open → in_progress → blocked → review → done | cancelled), dependency graph, comments, and an active-ticket provenance bundle that tags every captured session with persona_name + ticket_id. Tier: Team+. Available starting v0.10.1.

Commands

| Command | Description | |---------|-------------| | sfs ticket list [--status STATE] | List tickets, optionally filtered by FSM state | | sfs ticket show <id> | Show ticket detail + dependencies + recent comments | | sfs ticket create --title T --description D [--accept "..." --depends-on tkt_…] | Open a ticket (agent source requires ≥1 acceptance criterion + ≥20-char description) | | sfs ticket start <id> [--tool T] [--force] [--no-print-context] | Atomic claim; writes the active-ticket bundle and prints compiled persona + ticket context with tool-aware token budget | | sfs ticket complete <id> | Move from in_progress to review; clears owned bundle | | sfs ticket comment <id> "body" [--as PERSONA] | Slack-like comment (non-idempotent) | | sfs ticket status | Render the active-ticket bundle (Rich panel) | | sfs ticket block <id> --reason "..." / sfs ticket unblock <id> | Toggle blocked state | | sfs ticket reopen <id> | Move a terminal ticket back to open | | sfs ticket approve <id> / sfs ticket dismiss <id> | Decide on suggested tickets | | sfs ticket assign <id> --persona NAME | Attach a persona to a ticket | | sfs ticket resolve <id> | Move from review to done (atomic with rowcount guard) | | sfs ticket escalate <id> --reason "..." | Raise priority + append audit comment |

The active-ticket bundle is stored locally and read by all 9 daemon watchers (claude_code, codex, copilot, cursor, gemini, amp, cline, roo_code, kilo_code). Captured sessions carry the bundle in their manifest.json and the server populates sessions.persona_name + sessions.ticket_id on upload.