SpecStory
Integrations›Cursor CLI

Terminal Coding Agents

Cursor CLI

Cursor CLI mirrors the Cursor editor agent inside your terminal. Wrap it with SpecStory so the full discussion stays searchable and reviewable.

Install SpecStory CLI

Grab the CLI or keep it current before launching Cursor CLI through SpecStory.

brew tap specstoryai/tap
brew update
brew install specstory
specstory version
specstory check

Info

Need Linux or WSL binaries or installing manually? Download the archive that matches your OS and architecture (for example SpecStoryCLI_Linux_x86_64.tar.gz or SpecStoryCLI_Darwin_arm64.zip) from the latest release, make them executable, and move them into your PATH.

tar -xzf SpecStoryCLI_Linux_x86_64.tar.gz   # unzip the Darwin archive on macOS
sudo mv specstory /usr/local/bin/
sudo chmod +x /usr/local/bin/specstory
specstory version

Swap the archive name for the asset you downloaded and repeat when upgrading.

Run Cursor CLI with auto-save

Capture a session by running Cursor CLI through the SpecStory wrapper.

specstory run cursor

SpecStory stores transcripts, tool invocations, and shell output in .specstory/history/. You keep the normal Cursor CLI flow while gaining reviewable context.

Sync existing Cursor CLI sessions

Cursor CLI captures prior chats locally. Convert them into Markdown after the fact with specstory sync.

# Export every Cursor CLI session
specstory sync cursor

# Only export one session (replace with its UUID)
specstory sync cursor -s <session-uuid>

# Watch log output during sync
specstory sync cursor --console

Each export creates a Markdown file named with the session timestamp. Share them in PRs or hand them to teammates as design history.

Best practices

  • Scope conversations: Use /clear or start fresh sessions per task to simplify review.
  • Pair with Editor history: Combine Cursor CLI transcripts with .specstory/history/ from the editor UI for an end-to-end record.
  • Include transcripts in reviews: Point code reviewers at the relevant Markdown when opening a PR.

Troubleshooting

  • cursor-agent not in PATH: Install the Cursor CLI and verify with cursor-agent --help.
  • No .specstory/history/ files: Ensure you launched from inside a project folder with write permissions.
  • Sync returns zero sessions: Cursor CLI must have local session files in the working directory.
  • Still stuck? Email support@specstory.com or open an issue on GitHub.