Install the CLI

macOS and Linux

Paste this into your terminal to install the latest release:

curl -fsSL https://specstory.com/install.sh | sh

The installer detects Intel/AMD or ARM, downloads the matching binary from GitHub releases, and verifies its SHA-256 checksum. It installs to ~/.local/bin without administrator access. If that directory is not in your PATH, follow the command printed by the installer before running specstory.

You can read the installer before running it. It does not edit your shell profile. To keep the CLI available in new terminals, add the printed export PATH line to ~/.zshrc (Zsh) or ~/.bashrc (Bash), or use the printed fish_add_path command in Fish.

Then check your installation:

specstory version
specstory check

Rerun the installer to update. To remove a default curl installation, delete ~/.local/bin/specstory. Your saved conversations remain in your projects.

Homebrew

If you use Homebrew on macOS or Linux:

brew install specstoryai/tap/specstory
specstory version
specstory check

To update, run brew upgrade specstory.

Use Homebrew to update an existing Homebrew installation, so you keep one installation managed by the same tool.

Windows

In PowerShell or Windows Command Prompt, run:

powershell -c "irm https://specstory.com/install.ps1 | iex"

The PowerShell installer selects the native x64 or ARM64 binary, verifies its SHA-256 checksum, and installs to %LOCALAPPDATA%\SpecStory\bin. It adds that directory to your user PATH without administrator access. Close and reopen your terminal to pick up the change.

Then run specstory version and specstory check. Rerun the same command to update; close any running SpecStory process first. Windows PowerShell 5.1 and PowerShell 7 are supported. Set $env:SPECSTORY_NO_MODIFY_PATH = '1' before installation if you manage your own PATH.

To uninstall, remove %LOCALAPPDATA%\SpecStory\bin\specstory.exe and that directory's entry from your user PATH in Windows Settings. Your saved conversations remain in your projects.

Manual downloads

Download the matching operating-system and architecture archive from GitHub releases. Native Windows builds are available for x86_64 and ARM64: extract the ZIP and put the folder containing specstory.exe in your user PATH. On macOS or Linux, extract the archive, make specstory executable, and put it in your PATH. The curl installer also works inside WSL using the Linux build.

For a custom curl destination or a specific stable release, download the script and set the options when running it:

curl -fsSL https://specstory.com/install.sh -o install-specstory.sh
SPECSTORY_INSTALL_DIR="$HOME/.local/bin" SPECSTORY_VERSION=2.11.0 sh install-specstory.sh

The CLI is free and open source.

From your project folder, launch an installed coding agent:

specstory run claude
# Or: specstory run codex

Use the agent as usual. SpecStory saves the session to .specstory/history/ and can sync it to Cloud when you are logged in. Use --no-cloud-sync to keep capture local.

Choose the integration for your coding agent. Cursor and Copilot work with our editor extensions; terminal agents use the CLI.

Check availability

Pi support was added in CLI 2.11.0. Qwen requires a build that includes its provider and is not included in CLI 2.11.0. Check specstory version and the provider lists in specstory help run and specstory help sync before using an integration.

Run specstory check to see which agents are detected on your machine. The CLI can also capture editor sessions with specstory run cursoride for Cursor or specstory run copilotide for VS Code Copilot.

You do not have to launch an agent through SpecStory to export its existing history. From the project folder:

# List sessions the CLI can find
specstory list

# Export available sessions for this project
specstory sync

# Export one session
specstory sync claude -s <session-id>

sync writes Markdown and can upload to Cloud when authenticated. It does not start a coding agent.

If you launch agents directly, keep specstory watch running to capture new activity. Stop it with Ctrl+C.

specstory watch
# Or watch a single agent:
specstory watch codex

Use specstory search to find a previous session or specstory resume to continue it. See search and resume for the picker and supported handoffs.

For flags, configuration, and storage paths, see the CLI reference.