CLI Reference

Use seshtk to inspect local session history from a terminal or script. Install Session Toolkit, then run seshtk <command> --help for the options supported by your installed version.

Choose a command

Replace SESSION_ID in examples with a native ID from a selected result. The prefix is one of claude-code, codex, or cursor.

seshtk self-identify --cwd /path/to/project --json
seshtk list --cwd /path/to/project --since 7d --json
seshtk search -p 'deployment failed' --literal --json
seshtk search estimate -p 'deployment failed' --literal --json
seshtk read --session 'codex:SESSION_ID' --max-records 100 --json
seshtk parse /path/to/transcript.jsonl --runtime cursor --max-bytes 4000000 --json
seshtk read --session 'codex:SESSION_ID' --evidence --json
seshtk activity --session 'codex:SESSION_ID' --json
seshtk activity --session 'claude-code:SESSION_ID' --out ./activity.json --json

Export accepts an exact session, a visible conversation marker, or a bounded batch. These selection modes have different ambiguity rules; see export safety.

seshtk export --session 'claude-code:SESSION_ID' --out ./conversation.md --json
seshtk export --cwd /path/to/project --match 'visible marker' --out ./match.md
seshtk export --cwd /path/to/project --all --out ./transcripts --json

Capabilities

Before an integration depends on a command or its output format, check the installed version and the capability IDs it requires:

seshtk --version
seshtk capabilities --json

The capability response includes data.version, data.providers, and data.capabilities. A package version alone does not establish that an operation is supported. The currently implemented IDs are:

The reported providers are claude-code, codex, and cursor. Exact evidence cutoffs and expansion support Codex only.

Machine output

Add --json to any command for exactly one newline-terminated response envelope. This includes help and version output. capabilities always uses this format.

{ "ok": true, "schema_version": 1, "data": {} }

Failures replace data with an error object containing code, message, hint, and optional details. Diagnostics go to stderr, leaving stdout for the single response.

Without --json, read and parse print conversation text; other operations print structured JSON. Running seshtk without arguments prints help. Commands never prompt or emit color. JSON and unattended invocations perform no update lookup.

Exit codes and errors

A successful exit means the result can be interpreted; inspect its coverage to learn whether it is complete.

self-identify succeeds only for authoritative identity. Other identity statuses produce an error whose details preserves the structured evidence. Library identity calls return the status for the caller to interpret.

Update notices

Successful interactive operations can check npm for a newer stable release. Both stdin and stderr must be TTYs. A notice goes to stderr and includes an explicit-version installation command; no automatic upgrade runs.

The cache is $XDG_CACHE_HOME/session-toolkit/update.json, falling back to ~/.cache/session-toolkit/update.json. Missing, malformed, or expired caches trigger a fresh lookup. Lookup and cache-write failures never fail the requested session operation; its stdout remains unchanged.