CLI reference

~/
└── .specstory/
    ├── sessions.db     # SQLite index of all sessions across projects and agents
    └── cli/
        ├── config.toml  # User level configuration
        └── auth.json    # SpecStory Cloud login state
<project>/
└── .specstory/
    ├── cli/
    │   └── config.toml  # Project level configuration
    ├── history/         # Markdown session transcripts
    ├── debug/           # Debug logs (if `log` enabled)
    │   └── debug.log
    └── .project.json    # Project state

# SpecStory CLI Configuration
#
# Uncomment (remove the #) the line and edit any setting below to change the default behavior.
# For more information, see: https://specstory.com/docs/integrations/terminal-coding-agents/usage

[local_sync]
# Write markdown files locally. (default: true)
# enabled = false # equivalent to --only-cloud-sync

# Custom output directory for markdown files.
# Default: ./.specstory/history (relative to the project directory)
# output_dir = "~/.specstory/history" # equivalent to --output-dir "~/.specstory/history"

# Use local timezone for file name and content timestamps (default: false, UTC)
# local_time_zone = true # equivalent to --local-time-zone

[cloud_sync]
# Sync session data to SpecStory Cloud. (default: true, when logged in to SpecStory Cloud)
# enabled = false # equivalent to --no-cloud-sync

[logging]
# Write logs to .specstory/debug/debug.log (default: false)
# log = true # equivalent to --log

# Debug-level output, requires console or log (default: false)
# debug = true # equivalent to --debug

# Custom output directory for debug data.
# Default: ./.specstory/debug (relative to the project directory)
# debug_dir = "~/.specstory/debug" # equivalent to --debug-dir "~/.specstory/debug"

# Error/warn/info output to stdout (default: false)
# console = true # equivalent to --console

# Suppress all non-error output (default: false)
# silent = true # equivalent to --silent

[version_check]
# Check for new versions of the CLI on startup.
# Default: true
# enabled = false # equivalent to --no-version-check

[analytics]
# Send anonymous product usage analytics to help improve SpecStory.
# Default: true
# enabled = false # equivalent to --no-usage-analytics

[telemetry]
# OTLP gRPC collector endpoint (e.g., "localhost:4317" or "http://localhost:4317")
# endpoint = "localhost:4317"

# Override the default service name (default: "specstory-cli")
# service_name = "my-service-name"

# Include user prompt text in telemetry spans (default: true)
# prompts = false

[redaction]
# Redact secrets and API keys from saved markdown history. (default: true)
# Detection uses the betterleaks ruleset, covering API keys, tokens, private
# keys, and other credentials for many providers.
# enabled = false # equivalent to --no-redact-secrets

[providers]
# Agent execution commands by provider (used by specstory run)
# Pass custom flags (e.g. claude_cmd = "claude --allow-dangerously-skip-permissions")
# Use of these is equivalent to -c "custom command"

# Claude Code command
# claude_cmd = "claude"

# Codex CLI command
# codex_cmd = "codex"

# Cursor CLI command
# cursor_cmd = "cursor-agent"

# Cursor IDE command (used by specstory run cursoride to open the IDE)
# cursoride_cmd = "cursor"

# Droid CLI command
# droid_cmd = "droid"

# Gemini CLI command
# gemini_cmd = "gemini"

# Antigravity CLI command
# antigravity_cmd = "agy"

# Muse Code command
# muse_cmd = "muse"

# Pi command
# pi_cmd = "pi"

# Qwen Code command (SpecStory 2.12.0+)
# qwen_cmd = "qwen"

# DeepSeek TUI command
# deepseek_cmd = "deepseek"

# 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