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, BearClaude) and the CLI (Claude Code) write Markdown histories into .specstory/history/.
  2. Authentication: You run specstory auth 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 (Claude Code or cross-project)

# Authenticate device (run once)
specstory auth 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.