Skip to main content
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
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 [email protected] or open an issue on GitHub.