CLI Reference

Complete command reference for the Stoa CLI, covering every command, flag, and subcommand.

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

Getting Started

# Check version
intent version

# Initialize in a project
intent init

# Show status
intent status

Core Commands

`intent init`

Initialize tracking in a project directory.

intent init [flags]

Flag	Description
`--start`	Start the daemon after initialization
`--no-daemon`	Run in foreground mode
`--git-mode`	Disable materializer (Git stays source of truth)
`--debug`	Enable debug logging

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

`intent status`

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

`intent version`

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

Interactive Interfaces

`intent -i` / `intent tui`

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

`intent shell`

Launch the AI-powered interactive REPL.

intent shell [flags]

Flag	Description
`--theme`	Theme: dark, light, or auto
`--debug`	Enable debug logging

Supports natural language queries, slash commands, @ references, and tab completion.

`intent explore`

Launch the multi-panel explorer TUI with a snapshot-centric view containing timeline, files, changes, and preview panels.

AI & Search

`intent ask [query]`

Natural language search of your decision history.

intent ask "What did we decide about authentication?"

Flag	Description
`-n, --limit`	Maximum results
`--since`	Start date
`--until`	End date
`--agent`	Filter by agent type
`-m, --manual`	Manual search (no AI)
`--tui`	Open results in TUI

Uses five specialized tools: search_decisions, search_code, fetch_decision, get_stats, list_files.

File Operations & History

`intent history [file]`

Browse version history for a file or the entire project.

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

`intent show <file>[@version]`

Display file content at a specific version.

# Latest version
intent show src/api.ts

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

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

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

Compare file versions.

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

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

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

`intent restore <file>@<version>`

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

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

`intent timeline`

View the decision timeline.

Flag	Description
`--limit`	Maximum entries
`-m, --manual`	Manual entries only
`--agent`	Filter by agent

`intent deleted`

List deleted files and optionally restore them.

# List deleted files
intent deleted

# JSON output
intent deleted --json

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

Exchange & Session Management

`intent exchange`

Inspect AI exchanges.

# List exchanges
intent exchange list

# Show specific exchange
intent exchange <exchange-id>

# Interactive mode
intent exchange -i

`intent session`

Manage sessions.

# List sessions
intent session list [--limit N] [--since DATE] [--agent TYPE]

# Show session details
intent session show <session-id>

# Export session
intent session export <session-id> [--format markdown|json] [--output FILE]

Episode Workspaces

`intent episode`

Manage episode workspaces (isolated branches for decisions).

# List episodes
intent episode list [--all]

# Create episode
intent episode create <name> [--from <parent>] [--from-exchange <id>] [--desc TEXT]

# Switch episode
intent episode switch <name>

# Show current
intent episode current

# Archive episode
intent episode archive <name>

# Compare episodes
intent episode diff <source> [--target <episode>] [--file <path>]

# Merge with LLM-guided analysis
intent episode integrate <source>

Episode Integration

intent episode integrate runs a three-phase guided merge:

Analysis: LLM analyzes differences
Interactive Planning: review each change (list, set, show, all, apply, quit, help)
Application: approved changes applied

Snapshots & Digests

`intent snapshot`

Point-in-time snapshot management.

# Create snapshot
intent snapshot create [--title TEXT]

# List snapshots
intent snapshot list [--limit N]

# Show snapshot details
intent snapshot show <id> [--files]

# Compare snapshots
intent snapshot diff <snap1> [snap2] [--stat] [--names] [--files]

`intent digest`

Session digest management.

# Quick create (since last digest)
intent digest "Title"

# Create with options
intent digest create [--title TEXT] [--description TEXT] [--from ID] [--to ID] [--since-last] [--no-analysis]

# List digests
intent digest list [--limit N] [--status draft|finalized|archived]

# Show digest
intent digest show <id> [--files]

# Finalize
intent digest finalize <id> [--record]

# Archive / Reopen
intent digest archive <id>
intent digest reopen <id>

Git Integration

`intent git clone`

Clone a repo with provenance.

intent git clone <git-url> <intent-url> [path] [--materialize]

`intent git commit`

Create a commit from unsynced changes.

intent git commit [--dry-run] [-m MESSAGE]

`intent git push / pull`

Push or pull code and provenance refs.

intent git push [remote] [branch] [--force]
intent git pull [remote] [branch]

`intent blame <file> [line]`

Show which AI exchange authored each line.

intent blame src/api.ts
intent blame src/api.ts 42 --json --verbose

`intent trace <exchange-id>`

Show all files modified by a specific exchange.

intent trace 1ea90095:0 --json --verbose

`intent parse <commit-sha>`

Generate review artifacts from provenance.

intent parse abc123 [--output DIR] [--format markdown|json]

Outputs: summary.md (or .json) and annotations.json.

Collaboration & Remote Sync

`intent stream`

Topic stream management for threaded discussions.

intent stream list
intent stream create <id> [--title TEXT] [--type TYPE] [--description TEXT] [--participant USER] [--link URL]
intent stream message <id> [--author NAME] [--body TEXT]
intent stream delete <id>

`intent clone <url> [directory]`

Clone a remote project.

`intent remote`

Manage remote sync.

intent remote set <url>       # Set remote URL (intent://host:port/project-id)
intent remote unset            # Remove remote
intent remote status           # Show sync status
intent remote list / add / remove / pull / push

`intent proxy serve`

Expose daemon over HTTP for external access.

intent proxy serve [--listen ADDR] [--socket PATH] [--api-key KEY] [--timeout MS]

Endpoints: /healthz, /rpc, /events, /events/stream (SSE).

Authentication & Cloud

`intent login`

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

`intent logout`

Logout and revoke tokens.

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

`intent credits`

intent credits balance          # Show balance and usage
intent credits history [--limit N]  # Usage history
intent credits add              # Add credits (opens browser)

`intent web`

Web platform integration.

intent web register [--org ORG]         # Register project with a team (24-hour token)
intent web projects list        # List projects
intent web projects show <id>   # Show project details
intent web projects delete <id> # Unregister
intent web projects share <id> <org>    # Share with team
intent 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

`intent configure`

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

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

# Shell prompt/completions
intent configure shell

# Actor identity
intent configure actor

`intent ignore`

Manage ignore patterns (.intentignore).

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

Service Management

`intent service`

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

`intent service daemon`

Global daemon management across all projects.

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

Diagnostics & Recovery

`intent journal`

Inspect the event journal.

# List entries with filters
intent journal list [--source SRC] [--type TYPE] [--file PATH] [--exchange ID] [--session ID] [--agent AGENT] [--operation OP] [--matched|--unmatched] [--processed|--unprocessed] [--start DATE] [--end DATE] [--limit N] [--offset N] [--order-by FIELD]

# Show single entry
intent journal show <id> [--payload]

`intent rebuild crdt`

Replay journal to rebuild CRDT storage.

intent rebuild crdt [--dry-run] [--verify] [--file PATH]

`intent reset`

Reset local state. Use with caution.

intent reset [--hard] [--keep-config] [--dry-run]

Shell Completion

intent completion bash
intent completion zsh
intent completion fish
intent 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
`llm`	AI-powered commands (`ask`, decision enrichment)
`git`	Git integration (`git clone`, `git commit`, `git push/pull`, `blame`, `trace`, `parse`)
`config`	Configuration commands (`configure llm`, `configure slack`, `configure shell`)
`diag`	Diagnostics (`journal`, `rebuild crdt`, `reset`)
`advanced`	Advanced version control features

The TUI main menu adapts to show only the commands available in your build. Run intent version to see your build metadata.

Getting Started

Core Commands

intent init

intent status

intent version

Interactive Interfaces

intent -i / intent tui

intent shell

intent explore

AI & Search

intent ask [query]

File Operations & History

intent history [file]

intent show <file>[@version]

intent diff <file>[@v1][@v2]

intent restore <file>@<version>

intent timeline

intent deleted

Exchange & Session Management

intent exchange

intent session

Episode Workspaces

intent episode

Episode Integration

Snapshots & Digests

intent snapshot

intent digest

Git Integration

intent git clone

intent git commit

intent git push / pull

intent blame <file> [line]

intent trace <exchange-id>

intent parse <commit-sha>