Sync & Store

Sync lets you move those conversation histories into the Cloud for centralized indexing and search.

How Sync Works

1. Local Capture: Editors (Cursor, VS Code + Copilot) and the CLI (Claude Code, Cursor CLI, Codex CLI, Gemini CLI) write Markdown histories into .specstory/history/.
2. Authentication: You run specstory login once per machine to link your device with Cloud.
3. Manual Sync: Sync is always explicit - run via the CLI or extension command.
4. Session Upload: The CLI or extension uploads sessions one by one. For full-project sync, the CLI scans .specstory/history/ and calls the API for each session file.
5. Storage: Sessions are stored in Cloud as:
   • Markdown (clean, readable capture)
   • Raw JSON (original conversation data)
   • Both are preserved exactly as generated

SpecStory Cloud never runs background uploads. Every sync requires explicit action from you.

Configuring Sync

From Cursor or VS Code extensions

• Open your project folder (must contain .specstory/history/).
• Open the Command Palette (Ctrl/Cmd+Shift+P).
• Run SpecStory: Sync with Cloud.
• The extension authenticates, uploads session files, and shows a completion toast.

From the CLI (Terminal agents)

# Authenticate device (run once)
specstory login

# Sync all local sessions in the current repo/project
specstory sync

# Sync a single session by ID
specstory sync -u <session-uuid>

Full-project sync happens because the CLI loops through all Markdown files and uploads them one by one. The Cloud API itself handles sessions individually.

Verifying Your AI-conversations Sync

After running sync:

• Check the CLI output (or toast in extensions) for success.
• Refresh cloud.specstory.com.
• You should see your project and sessions listed.
• Open a session to confirm content matches your local Markdown.

Next

Search & Organization

Learn how to filter and explore your synced sessions.