# Sessionr commands — full surface 15 commands. Every one accepts `--output json|jsonl|text` and respects `SESSIONR_OUTPUT` env var. Always use `--output json` for parseable output. ## Discovery ### `sessionr list [source]` ``` sessionr list [source] -n, --limit Max sessions (default 20) --offset Skip first N (pagination) -q, --search Filter by message content (caps at --max-sessions) --max-sessions Cap content scan (default 50, max 200) --cwd auto | current | all | (default: auto) --output json | jsonl | text ``` `source` is optional positional: any of the 11 source names or aliases (`cc`/`cli`/`cx`/`gm`). `--cwd auto` (default): rank `$PWD`-matching entries first, fall back to global if none match. `--cwd current`: strict — only `$PWD` matches. `--cwd all`: disable scoping. `--cwd /abs/path`: explicit path. JSON envelope shape: `references/json-envelope.md` → "list". ### `sessionr search -q ` Deeper search than `list -q`. Returns ranked snippets with `message_index` + `char_offset`. ``` sessionr search -q [-s ] [--top N] [--max-sessions N] [--output json] ``` ### `sessionr doctor` Per-source diagnostic. Reports `data_dir`, `data_dir_exists`, `session_count`, `spawn_bin`, `spawn_bin_resolvable`, `warnings[]`. Use when `list` returns empty. ``` sessionr doctor [--output json] ``` ## Inspection ### `sessionr info ` Cheap metadata — id, source, cwd, model, total_messages, by_role, token_usage, duration. No tool list. ``` sessionr info [-s ] [--output json] ``` ### `sessionr stats ` Full normalization — info + tool frequencies, files modified, message-block breakdown. ``` sessionr stats [-s ] [--output json] ``` ## Reading ### `sessionr read [from] [to]` ``` sessionr read [from] [to] -s, --source Source filter (resolves alias) -p, --preset minimal | standard | verbose | full -d, --detail full | condensed | skeleton | meta --tokens Token budget (default 8000, max ~8000) --anchor head | tail | search (default head) --search Slice around first match (sets anchor=search) --role user, assistant, system, tool_use, tool_result --page Page number (1-based) --before Show messages before this index --after Show messages after this index --if-changed 304-style polling --include-summary Include summary on every page (default: page 1 only) --batch Newline-separated IDs → JSONL stream ``` **Anchor messages** (leading system/user run + last assistant) are never char-truncated regardless of preset (v2.8.1+). `from`/`to` are 1-based message indices when both `--page` and `--before/--after` are absent. `PARTIAL` exit (10) when token budget truncated the slice — `meta.partial=true`, `meta.has_more_*` set, `meta.cursor.next` ready to copy-paste. ### `sessionr context ` Extract handoff-ready context (filtered messages + summary). ``` sessionr context --tokens Token budget (default 8000) --include-system-prompt Include system messages --include-tool-results Include tool results --format messages | summary ``` ### `sessionr diff ` Structural diff at message level. JSON-only. ## Write path (resume / new session) ### `sessionr send [session-id]` ``` sessionr send [session-id] -m, --message Inline prompt -f, --file Prompt from file -s, --source Required with --new --new Create new session instead of resuming --async Return job_id immediately --cwd Working directory for the spawn --tokens Read-back token budget -p, --preset Read-back preset (default standard) --dry-run Print resolved spawn command, exit 0 ``` Sync (default): blocks, returns `{messages, meta:{message_count_before, new_messages, ...}}` with the freshly-added messages. Async (`--async`): returns `{job_id, session_id, source, status:"running", pid, ...}` immediately. Pair with: ### `sessionr job ` Status snapshot. Reads `.exit` sidecar to determine real exit code. ### `sessionr wait ` ``` sessionr wait [--timeout 300] [--interval 2] ``` Block until terminal (`completed` / `failed` / `cancelled`). ### `sessionr cancel ` SIGTERM the child, set status `cancelled` with `exit_code: 130`. ### `sessionr jobs` List all jobs (running + recent). `--status running|completed|failed|cancelled` to filter. ## Maintenance ### `sessionr prune --older-than ` ``` sessionr prune --older-than --dry-run Preview what would be deleted (only working mode) --yes Confirm (currently NOT_IMPLEMENTED — refuses) -s, --source Scope to one source ``` Duration format: `7d`, `24h`, `30m`, `60s`. `0d` is rejected. ⚠ `--yes` returns `{error:{code:"NOT_IMPLEMENTED",...}}` exit non-zero. Use `--dry-run` to inspect the cutoff list; do actual deletion manually until a future release implements adapter-level deletion. ### `sessionr tag --add|--remove ` Idempotent. Tags are session-global (do not depend on `--source`). ## Top-level / global flags Apply before the subcommand: ``` sessionr [--output ] [--api-version ] [--timing] ... ``` - `--api-version 1` (default; 2 reserved for future envelope rework). - `--timing` adds `meta.timing_ms` to every JSON envelope (wall-clock ms). - Env: `SESSIONR_OUTPUT=json|jsonl|table|text` overrides the default. - Env: `SESSIONR_AGENT=1` forces JSON regardless of TTY status. ## Help & version - `sessionr --help` → human help. - `sessionr --output json help` → JSON help schema (`workflow[]`, `primary_commands[]`, `all_commands[]`, `exit_codes`). Exit 0. - `sessionr help ` → per-command help. - `sessionr --version` → reads from package.json at install time. Always matches the installed `sessionr@`. ## Removed / changed flags (version drift) - v2.7.0: `--cwd ` on `list` removed (was a duplicate). Now only `--cwd `. - v2.7.1: `program.version()` reads from package.json (was hardcoded — pre-2.7.1 binaries reported wrong --version). - v2.8.0–v2.8.1: anchor messages (leading system/user run + last assistant) are full-fidelity regardless of preset.