/Docs

CLI Reference

Complete command reference for the Intent CLI.

The Intent CLI provides commands for initialization, search, history, episodes, and daemon management.

Getting Started

intent init

Initialize Intent versioning in a project.

intent init [flags]

Flags:

  • --git-mode — Use Git Mode (Git owns file content, Intent tracks provenance)
  • --start — Start background service after init (default: true)
  • --no-daemon — Run service in foreground
  • --debug — Enable CRDT debugging

Example:

cd my-project
intent init

# For existing Git repositories
intent init --git-mode

See Git Mode for details on using Intent with existing Git repositories.

intent status

Show daemon status, active episode, and system health.

intent status

Output includes:

  • Daemon state (running/stopped)
  • Active episode
  • File watcher status
  • Outbox queue depth
  • FTS index status

intent version

Display CLI version information.

intent version

Configuration

intent configure llm

Configure the LLM provider for decision enrichment.

intent configure llm

Prompts for your Anthropic API key. Required for automatic decision enrichment.

intent configure slack

Configure Slack integration for session notifications.

intent configure slack

Sets up automatic posting of session enrichments to a Slack channel.

Search and Discovery

intent ask

Conversational search using Claude. Ask natural language questions about your decisions.

intent ask "query"

Example:

intent ask "how did we implement authentication?"
intent ask "what tradeoffs did we consider for the database?"
intent ask "show me decisions about error handling"

The AI agent searches your decision history and provides contextual answers.

intent shell

Launch the interactive shell for exploratory search.

intent shell

Shell features:

  • Natural language queries
  • @ references: @src/auth.ts, @ex_0_abc123, @v5
  • Slash commands: /timeline, /history, /show, /diff
  • Tab completion and command history

Slash commands in shell:

  • /help — Show available commands
  • /timeline — Decision timeline
  • /history [file] — File version history
  • /show [ref] — Display content
  • /diff [ref1] [ref2] — Compare versions
  • /exchanges — List recent exchanges
  • /sessions — List recent sessions

intent timeline

Display the decision timeline with enrichment summaries.

intent timeline [flags]

Flags:

  • --limit N — Number of entries (default: 20)
  • --since DATE — Filter by date
  • --file PATH — Filter by file

History and Versions

intent history

Browse version history for a file.

intent history [file] [flags]

Flags:

  • --limit N — Number of versions
  • --verbose — Show full enrichment details

Example:

intent history src/auth/middleware.ts
intent history --limit 50

intent show

Display content at a specific version.

intent show <file>@<version>

Example:

intent show src/auth.ts@v3
intent show src/auth.ts@latest

intent diff

Compare two versions of a file.

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

Example:

intent diff src/auth.ts@v3 src/auth.ts@v5

intent restore

Restore a file to a previous version.

intent restore <file>@<version>

Example:

intent restore src/auth.ts@v3

Exchanges and Sessions

intent exchange

Inspect a specific exchange with full metadata.

intent exchange <exchange-id>

Example:

intent exchange ex_0_abc123

Output includes:

  • User prompt
  • Agent reply
  • File operations
  • Decision enrichment (title, intent, approach, impact)
  • Related file changes

intent sessions

List recent AI coding sessions.

intent sessions [flags]

Flags:

  • --limit N — Number of sessions
  • --tool NAME — Filter by tool (claude-code, cursor, etc.)

Episodes

intent episode list

List all episodes in the project.

intent episode list

intent episode create

Create a new episode (isolated workspace).

intent episode create <name>

Example:

intent episode create feature-auth

intent episode switch

Switch to a different episode.

intent episode switch <name>

Example:

intent episode switch feature-auth
intent episode switch main

intent episode diff

Compare two episodes.

intent episode diff <episode1> <episode2>

Example:

intent episode diff main feature-auth

intent episode integrate

Integrate changes from one episode into another.

intent episode integrate <source> [flags]

Flags:

  • --into EPISODE — Target episode (default: main)
  • --mode MODE — Integration mode: merge or llm

Example:

intent episode integrate feature-auth --mode llm

The --mode llm option uses semantic merging—an LLM analyzes changes and produces a coherent integration.

Service Management

intent service start

Start the background daemon.

intent service start

intent service stop

Stop the background daemon.

intent service stop

intent service restart

Restart the background daemon.

intent service restart

Cloud and Sync

intent login

Authenticate with Intent Cloud.

intent login

Opens a browser for OAuth authentication, or displays a device code for headless environments.

intent remote set

Configure the remote sync destination.

intent remote set <url>

Example:

intent remote set https://sync.intent.build

intent web register

Register this project with Intent Cloud.

intent web register

intent stream

Monitor real-time sync activity.

intent stream

Journal and Debugging

intent journal list

Query the event journal directly.

intent journal list [flags]

Flags:

  • --type TYPE — Filter by event type
  • --limit N — Number of entries
  • --since DATE — Filter by date

Example:

intent journal list --type decision_enrichment --limit 10
intent journal list --type file_change --since 2024-01-15

intent rebuild

Rebuild CRDT state from the journal.

intent rebuild

Useful if CRDT storage becomes corrupted. The journal is the system of record and can always rebuild state.

Git Mode Commands

These commands are used when running Intent in Git Mode, where Git manages file content and Intent tracks provenance.

intent git clone

Clone a Git repository with Intent provenance tracking.

intent git clone <git-url> <intent-url> [target-dir]

Example:

intent git clone git@github.com:myorg/repo.git intent://sync.intent.build/repo ./repo

Clones the repository, fetches Intent notes, and initializes in Git Mode automatically.

intent git commit

Create a Git commit from unsynced Intent changes.

intent git commit [flags]

Flags:

  • --dry-run — Preview what would be committed without creating the commit
  • -m, --message — Override the auto-generated commit message

Example:

intent git commit
intent git commit --dry-run
intent git commit -m "feat: add authentication"

Auto-generates commit messages from Intent metadata, grouping AI exchanges and manual edits.

intent git push

Push code and Intent provenance refs to a remote.

intent git push [remote] [branch] [flags]

Flags:

  • --force — Force push the branch

Example:

intent git push
intent git push origin main

Pushes both the branch and Intent provenance refs (refs/notes/intent/*).

intent git pull

Pull code and Intent provenance notes from a remote.

intent git pull [remote] [branch]

Example:

intent git pull
intent git pull origin main

Fetches both the branch and Intent notes from the remote.

intent blame

Show which AI exchange authored each line of code.

intent blame <file> [line] [flags]

Flags:

  • --content — Show line content in output
  • --json — Output as JSON
  • -v, --verbose — Show full session transcript

Example:

intent blame src/auth/middleware.ts
intent blame src/auth/middleware.ts 42
intent blame src/auth/middleware.ts --json

Combines Git blame with Intent provenance to show commit info, exchange ID, agent type, and the user prompt that triggered the change.

intent trace

Show all code produced by a specific exchange.

intent trace <exchange-id> [flags]

Flags:

  • --json — Output as JSON
  • -v, --verbose — Show full session transcript

Example:

intent trace 1ea90095:0
intent trace 1ea90095-212a-4020-abcd-1234567890ab:0 --json

The inverse of blame—shows all files and line ranges modified by the exchange, mapped to their current positions.

Shell Completion

intent completion

Install shell completion.

# Bash
intent completion bash > /etc/bash_completion.d/intent

# Zsh
intent completion zsh > ~/.zfunc/_intent

# Fish
intent completion fish > ~/.config/fish/completions/intent.fish