Configuration

SpecStory CLI Configuration

This page is a quick reference for SpecStory CLI commands, flags, and the files created in your repo.

Note

Most users start with specstory run <agent>, then use sync for past sessions and watch for background capture.

Commands

Command	Description	Examples
`version`	Display the current SpecStory version	`specstory version`
`check`	Verify if terminal agents are installed and accessible to SpecStory	`specstory check`
`run`	Launch an agent and auto-save sessions to Markdown (and Cloud if logged in)	`specstory run claude` `specstory run cursor` `specstory run codex` `specstory run droid` `specstory run gemini`
`sync`	Convert past sessions to Markdown and optionally sync them to SpecStory Cloud	`specstory sync` `specstory sync -s <sessionId>`
`watch`	Watch for new agent activity and auto-save to Markdown	`specstory watch` `specstory watch cursor` `specstory watch codex` `specstory watch droid` `specstory watch gemini`
`login`	Authenticate with SpecStory Cloud	`specstory login`
`logout`	Sign out of SpecStory Cloud	`specstory logout`
`help`	Show help information	`specstory help` `specstory help run`

Note

specstory sync shows parsing progress and supports multiple session IDs: specstory sync -s <id1> -s <id2>.

Project scaffolding

The first run inside a project creates:

.specstory/ for state and configuration.
.specstory/history/ for exported Markdown.
.specstory/.project.json for project bookkeeping.

<project>/
└── .specstory/
    ├── history/           # Markdown session transcripts
    ├── debug/             # Debug logs (if --log enabled)
    │   └── debug.log
    └── .project.json      # Project bookkeeping

Note

History files are written to .specstory/history/ in the repo you run from.

Default behavior

Session storage: .specstory/history/ in the working directory.
Cloud sync: Enabled when logged in with specstory login unless --no-cloud-sync is provided.
Session sources: Reads from ~/.claude/projects/, ~/.cursor/chats/, ~/.factory/, ~/.codex/history, and ~/.gemini/tmp/<project_hash>/chats.
Output format: Markdown files stamped with the session timestamp.
Timezones: Use --local-time-zone to stamp file names and content in local time.

Flags

Flag	Description	Usage
`-c, --command`	Use a custom terminal-agent command or args	`specstory run claude -c "claude --dangerously-skip-permissions"`
`-s, --session`	Convert a specific session to Markdown	`specstory sync claude -s <sessionId>`
`--console`	Stream log output to stdout	`specstory sync --console`
`--log`	Write logs to `./specstory/debug/debug.log`	`specstory sync --log`
`--debug`	Include debug-level output (requires `--console` or `--log`)	`specstory sync --log --debug`
`--silent`	Suppress non-error output	`specstory sync --silent`
`--local-time-zone`	Use local timezone for file name and content timestamps	`specstory sync --local-time-zone`
`--no-cloud-sync`	Disable cloud sync even when authenticated	`specstory run --no-cloud-sync`
`--only-cloud-sync`	Disable local markdown writing and only sync to cloud	`specstory watch --only-cloud-sync`
`--no-usage-analytics`	Opt out of usage analytics	`specstory sync --no-usage-analytics`
`--no-version-check`	Skip the version check	`specstory run codex --no-version-check`
`--output-dir`	Write Markdown exports to a custom directory	`specstory watch --output-dir ~/my-agent-sessions`
`-h, --help`	Show help information for a command	`specstory -h`
`-v, --version`	Show the current SpecStory version	`specstory -v`

Info

The CLI wrapper favors convention over configuration. Most projects will never need to modify defaults.

Debugging

Use console streaming (--console) or log files (--log) to inspect details (--debug) on processing.

# Run interactively with verbose output
specstory run claude --console --debug

# Capture logs without console noise
specstory sync cursor --log

# Capture detailed logs
specstory watch --log --debug

Log output highlights:

--log output written to ./.specstory/debug/debug.log
Which session files are being parsed.
Where Markdown exports are written.
Errors encountered during capture or sync.