Cursor CLI

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

Run Cursor CLI with SpecStory

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.

List existing Cursor CLI sessions

List all the Cursor CLI sessions SpecStory can see and sync for the current project directory.

specstory list cursor

Sync existing Cursor CLI sessions

Forgot to launch with specstory run cursor? Convert prior sessions 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>

# Inspect sync logs in your terminal
specstory sync cursor --console

• Session sources: Read from ~/.cursor/chats/ (local Cursor CLI session history).

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

Watch for Cursor CLI activity

Prefer to run the Cursor CLI directly or via another tool? Use specstory watch to watch the current project directory for any new agent activity and auto-save it to markdown.

# Watch for only activity from any supported coding agent
specstory watch

# Watch for only new Cursor CLI agent activity
specstory watch cursor

Run specstory watch without an agent name to capture activity from any supported provider.

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.