CLI Reference

Complete Stoa CLI reference — every command, flag, and subcommand for local development, plugin testing, and workspace sync.

The Stoa CLI (command name: stoa) captures provenance from AI coding sessions, manages version history, and connects to the web platform.

Installation

brew tap specstoryai/tap
brew update
brew install stoa

Verify the installation:

stoa version

To upgrade later:

brew update
brew upgrade stoa

Getting Started

# Check version
stoa version

# Initialize in a project
stoa init

# Show status
stoa status

Core Commands

`stoa init`

Initialize tracking in a project directory.

stoa init [flags]

Flag	Description
`--start`	Start the daemon after initialization
`--no-daemon`	Run in foreground mode
`--debug`	Enable debug logging

Creates .stoa/ directory, journal database, CRDT storage, and a default "main" episode.

`stoa status`

Show current versioning status: daemon state, episode, tracked files, outbox queue, FTS index, and remote sync status.

`stoa version`

Show build metadata: version, git SHA, build date, node bridge hash, and binary path.

Interactive Interface

`stoa -i`

Launch the full interactive TUI with views including File History, Exchanges, Project Tree, Chat, Diff, and more.

File Operations & History

`stoa history [file]`

Browse version history for a file or the entire project.

Flag	Description
`-i, --interactive`	Open in interactive TUI

`stoa show <file>[@version]`

Display file content at a specific version.

# Latest version
stoa show src/api.ts

# Specific version number
stoa show src/api.ts@5

# Specific exchange
stoa show src/api.ts@ex_0_abc123

`stoa diff <file>[@v1][@v2]`

Compare file versions.

# Compare versions 3 and 5
stoa diff src/api.ts@3@5

# Compare version 3 to working copy
stoa diff src/api.ts@3@working

# Compare by exchange ID
stoa diff src/api.ts @ex_0_abc @ex_0_def

`stoa restore <file>@<version>`

Restore a file to a previous version. Creates a backup in .stoa/restore-backups/.

Flag	Description
`--force`	Skip confirmation
`--exchange <id>`	Restore all files from an exchange

`stoa deleted`

List deleted files and optionally restore them.

# List deleted files
stoa deleted

# JSON output
stoa deleted --json

# Restore a deleted file
stoa deleted restore <file> [-o output-path] [-f]

Exchange Management

`stoa exchange`

Inspect AI exchanges.

# List exchanges
stoa exchange list

# Show specific exchange
stoa exchange <exchange-id>

Collaboration & Remote Sync

`stoa clone <url> [directory]`

Clone a remote project.

`stoa remote`

Manage remote sync.

stoa remote set <url>       # Set remote URL (stoa://host:port/project-id)
stoa remote unset            # Remove remote
stoa remote status           # Show sync status

`stoa sharelocalhost [port]`

Put a local port on a public HTTPS URL and collect voice-memo feedback right on the page. Without port, the CLI lists what's listening and lets you pick. See Share localhost for the full walkthrough.

stoa sharelocalhost              # interactive port picker
stoa sharelocalhost 3000         # share localhost:3000
stoa sharelocalhost list         # show active shares
stoa sharelocalhost kill <id>    # tear down a specific share
stoa sharelocalhost kill-all     # tear down everything (use -f to skip prompt)

Authentication & Cloud

`stoa signup`

Create a Stoa account. Opens the browser to finish signup, then provisions your workspace and starter space and lands you back at the terminal ready to share. Use this on a new machine when you don't have an account yet; if you already have one, run stoa login instead.

`stoa login`

Authenticate via device flow. Opens browser, displays a 6-digit code, exchanges for refresh token (10-year expiry).

`stoa logout`

Logout and revoke tokens.

Flag	Description
`-f, --force`	Force logout without confirmation

`stoa web`

Web platform integration.

stoa web register [--org ORG]         # Register project with a team (24-hour token)
stoa web projects list        # List projects
stoa web projects show <id>   # Show project details
stoa web projects delete <id> # Unregister
stoa web projects share <id> <org>    # Share with team
stoa web projects unshare <id>        # Remove sharing

web register is org-first: projects are always created shared with a team. If you belong to multiple teams, specify --org. If you only have one team, it's selected automatically.

Configuration

`stoa configure`

# LLM configuration
stoa configure llm [--api-key KEY] [--model MODEL] [--show] [--from-org]

# Slack integration
stoa configure slack [--oauth-token TOKEN] [--channel CH] [--show] [--enable|--disable] [--scope project|global]

# Shell prompt/completions
stoa configure shell

# Actor identity
stoa configure actor

`stoa ignore`

Manage ignore patterns (.stoaignore).

stoa ignore add <pattern>
stoa ignore remove <pattern>
stoa ignore list
stoa ignore test <file>

Service Management

`stoa service`

stoa service status           # Show daemon status (uptime, PID, socket, etc.)
stoa service start            # Start daemon
stoa service stop             # Stop daemon (graceful, 10s timeout)
stoa service restart          # Restart daemon
stoa service automerge-debug  # Toggle Automerge logging (enable/disable/status)

`stoa service daemon`

Global daemon management across all projects.

stoa service daemon list      # List all daemons
stoa service daemon kill <path>   # Stop specific daemon
stoa service daemon kill-all  # Stop all daemons
stoa service daemon clean-all # Remove dead entries

Diagnostics & Recovery

`stoa reset`

Reset local state. Use with caution.

stoa reset [-f, --force]

Shell Completion

stoa completion bash
stoa completion zsh
stoa completion fish
stoa completion install    # Auto-detect and install

Build Tags

Some CLI commands are only available in certain builds. The CLI uses Go build tags to include or exclude feature sets:

Tag	Commands
`git`	Git integration (`blame`, `trace`, `parse`, `git commit`, `git push`)
`llm`	LLM-powered commands (`ask`, `shell`, `digest`, `configure llm`, `credits`, `episode integrate`)
`advanced`	Episodes, timeline, snapshots, sessions
`config`	Configuration commands (`configure slack`, `configure shell`)
`diag`	Diagnostics (`journal`, `rebuild`, `explore`, `service automerge-debug`)

Run stoa version to see your build metadata.