CLI Reference

Complete command-line interface documentation for Soothe.

Command Structure

All Soothe commands follow a consistent 2-level nested pattern:

soothe <subcommand> <action> [options]

Benefits:

  • Explicit actions - no ambiguity about what will happen
  • Better discoverability - all actions visible in --help
  • Consistent pattern across all commands
  • Industry standard (matches git, docker, kubectl)

Main Entry Points 

# Interactive TUI mode (default)
soothe

# Headless single-prompt mode
soothe -p "Analyze the data"

# Use custom config
soothe --config custom.yml

# Headless mode with JSONL output
soothe -p "Analyze data" --format jsonl

# Set progress verbosity
soothe -p "Complex task" --verbosity debug

Thread Management

Manage conversation threads with explicit actions.

soothe loop list

List all conversation threads.

Usage: soothe loop list [options]

Options:

  • --status <status> - Filter by status (active, archived)
  • --config <file> - Use custom configuration file

Examples:

# List all threads
soothe loop list

# Filter by status
soothe loop list --status active
soothe loop list --status archived

soothe loop show

Show thread details.

Usage: soothe loop show <thread-id> [options]

Options:

  • --config <file> - Use custom configuration file

Examples:

soothe loop show abc123

soothe loop continue

Continue a conversation thread in the TUI.

Usage: soothe loop continue [thread-id] [options]

Arguments:

  • thread-id - Optional. Thread ID to continue. Omit to continue last active thread.

Options:

  • --new - Create a new thread instead of continuing
  • --config <file> - Use custom configuration file

Requirements:

  • Requires a running daemon. Start daemon with soothed start first.

Examples:

# Start daemon first
soothed start

# Continue specific thread
soothe loop continue abc123

# Start a new thread
soothe loop continue --new

# Continue last active thread
soothe loop continue

soothe loop archive

Archive a thread.

Usage: soothe loop archive <thread-id> [options]

Options:

  • --config <file> - Use custom configuration file

Examples:

soothe loop archive abc123

soothe loop delete

Permanently delete a thread.

Usage: soothe loop delete <thread-id> [options]

Options:

  • --yes, -y - Skip confirmation prompt
  • --config <file> - Use custom configuration file

Examples:

# Delete with confirmation
soothe loop delete abc123

# Delete without confirmation
soothe loop delete abc123 --yes

soothe loop show

Export thread conversation to a file.

Usage: soothe loop show <thread-id> [options]

Options:

  • --output, -o <file> - Output file path
  • --format, -f <fmt> - Export format: jsonl or md (default: jsonl)

Examples:

# Export to JSONL (default)
soothe loop show abc123 --output thread.json

# Export to Markdown
soothe loop show abc123 --output thread.md --format md

soothe loop stats

Show thread execution statistics.

Usage: soothe loop stats <thread-id> [options]

Options:

  • --config <file> - Use custom configuration file

Examples:

soothe loop stats abc123

soothe loop tag

Add or remove tags from a thread.

Usage: soothe loop tag <thread-id> <tags...> [options]

Arguments:

  • thread-id - Thread ID
  • tags - One or more tags to add/remove

Options:

  • --remove - Remove tags instead of adding
  • --config <file> - Use custom configuration file

Examples:

# Add tags
soothe loop tag abc123 research analysis

# Remove tags
soothe loop tag abc123 research --remove

Configuration Management

soothe config reload

Reload configuration from disk without restarting the daemon.

Usage: soothe config reload [options]

Options:

  • --config <file> - Use custom configuration file

Examples:

# Reload default config
soothe config reload

# Reload custom config
soothe config reload --config custom.yml

Agent Management

soothe agent list

List available agents and their status.

Usage: soothe agent list [options]

Options:

  • --enabled - Show only enabled agents
  • --disabled - Show only disabled agents
  • --config <file> - Use custom configuration file

Examples:

# List all agents
soothe agent list

# Filter by status
soothe agent list --enabled
soothe agent list --disabled

soothe agent status

Show detailed agent status.

Usage: soothe agent status [options]

Options:

  • --config <file> - Use custom configuration file

Examples:

soothe agent status

Daemon Management

Manage the Soothe daemon process.

soothed start

Start the Soothe daemon.

Usage: soothed start [options]

Options:

  • --foreground - Run in foreground (don’t daemonize)
  • --config <file> - Use custom configuration file

Examples:

# Start daemon in background
soothed start

# Start in foreground
soothed start --foreground

soothed stop

Stop the running Soothe daemon.

Usage: soothed stop

Examples:

soothed stop

soothed status

Show Soothe daemon status.

Usage: soothed status

Examples:

soothed status

Output:

Daemon Status: running
PID: 12345
Uptime: 2 hours
Transports:
  - WebSocket: ✅ Enabled (ws://127.0.0.1:8765)
Active Threads: 3

soothed restart

Restart the Soothe daemon.

Usage: soothed restart [options]

Options:

  • --config <file> - Use custom configuration file

Examples:

soothed restart

Autopilot Mode

Run tasks in autonomous mode without user interaction.

soothe autopilot run

Run autonomous agent loop for complex tasks.

Usage: soothe autopilot run <prompt> [options]

Arguments:

  • prompt - Task for autonomous execution

Options:

  • --max-iterations <n> - Maximum autonomous iterations (default: 10)
  • --format <fmt> - Output format: text or jsonl (default: text)
  • --config <file> - Use custom configuration file

Examples:

# Basic autonomous execution
soothe autopilot run "Research AI safety and summarize findings"

# Limit iterations for complex tasks
soothe autopilot run "Build a web scraper" --max-iterations 10

# Use custom config with JSON output
soothe autopilot run "Analyze codebase" --config custom.yml --format jsonl

# Long-running research task
soothe autopilot run "Investigate performance bottlenecks" --max-iterations 20

Use Cases:

  • Long-running tasks that don’t need user input
  • Background execution of complex workflows
  • Batch processing or research tasks
  • Automated testing and validation

Global Options

These options apply to all commands:

  • --config <file> - Path to YAML configuration file
  • --help, -h - Show help message
  • --version - Show version information

Common Patterns

Quick Analysis 

soothe -p "Analyze the performance bottlenecks in this codebase"

Autonomous Optimization 

soothe autopilot run "Optimize the database queries" --max-iterations 20

Resume Previous Work 

# List threads
soothe loop list

# Continue specific thread
soothe loop continue abc123

# Continue last active thread
soothe loop continue

Background Processing 

# Start daemon
soothed start

# Run in detached mode
soothe -p "Long running task" &

# Check status later
soothed status

Thread Management 

# List active threads
soothe loop list --status active

# Export thread for backup
soothe loop show abc123 --output backup.json

# Tag thread for organization
soothe loop tag abc123 research important

Migration from Old Syntax

If you were using the old flat command syntax, here’s how to migrate:

Old Command New Command
soothe thread soothe loop list
soothe thread -l soothe loop list
soothe thread <id> soothe loop show <id>
soothe thread -c <id> soothe loop continue <id>
soothe thread -a <id> soothe loop archive <id>
soothe thread -d <id> soothe loop delete <id>
soothe thread -e <id> soothe loop show <id>
soothe config soothe config reload
soothe agent soothe agent list
soothe agent --status soothe agent status
soothe autopilot "task" soothe autopilot run "task"