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 detailed loop information including status, branches, and checkpoint anchors.

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

Options:

  • --verbose, -v - Show detailed branch analysis

Examples:

soothe loop show loop_abc123
soothe loop show loop_abc123 --verbose

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 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

Status Commands

Client-side status checks that query the running daemon over WebSocket and render a unified table. (For the fast local soothed status check that does no RPC, see Daemon Management.)

soothe status

Show overall daemon and connection status (the default when no subcommand is given).

Usage: soothe status [options]

Options:

  • --json - Output as JSON.
  • --config <file> - Use custom configuration file.

Examples:

# Default: unified table
soothe status

# JSON output
soothe status --json

Output (running daemon):

                          Soothe Status
┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Section   ┃ Setting           ┃ Value                       ┃
┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Connection│ WebSocket URL      │ ws://127.0.0.1:8765         │
│           │ Soothe Home        │ /home/user/.soothe          │
│ Daemon    │ Status             │ Running                     │
│           │ PID                │ 12345                       │
│           │ Started            │ 2026-07-28T08:46:22+00:00   │
│           │ Active Threads     │ 3                           │
│           │ Daemon Version     │ 0.7.0                       │
│           │ Core Version        │ 0.7.0                       │
│           │ Readiness          │ ready                       │
└───────────┴────────────────────┴──────────────────────────────┘

The Started row is the daemon process start time (ISO-8601 UTC timestamp, captured when the daemon enters the running state). In JSON output it is the started_at field under daemon; it is null until the daemon has started successfully and is omitted from the table when the daemon is not live.

soothe status daemon

Check daemon status from the client side. Validates that the daemon is running and responsive over WebSocket.

Usage: soothe status daemon [options]

Options:

  • --json - Output as JSON.
  • --config <file> - Use custom configuration file.

Examples:

soothe status daemon
soothe status daemon --json

JSON output includes: status, websocket_url, running, port_live, active_threads, daemon_pid, started_at, daemon_version, core_version, readiness_state, and readiness_message (when present).

soothe status connection

Check client-daemon connection settings (WebSocket URL, Soothe Home). Does not require the daemon to be running.

Usage: soothe status connection [options]

Options:

  • --json - Output as JSON.

Examples:

soothe status connection
soothe status connection --json

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

Cron Management

Manage scheduled cron jobs via natural language. Requires a running daemon (soothed start). Cron jobs are daemon-side; the CLI sends commands over WebSocket.

soothe cron add

Add a scheduled cron job via natural language.

Usage: soothe cron add <text> [options]

Arguments:

  • text - Natural language schedule and task (e.g. “every day at 9am check for updates”)

Options:

  • --priority, -p <n> - Job priority (0–100)

Examples:

soothe cron add "every weekday at 8am summarize overnight logs"
soothe cron add "daily standup at 9am" --priority 80

soothe cron list

List all scheduled cron jobs.

Usage: soothe cron list

soothe cron show

Show details for a specific cron job.

Usage: soothe cron show <job-id>

soothe cron cancel

Cancel a scheduled cron job.

Usage: soothe cron cancel <job-id>

Daemon Management

Manage the Soothe daemon process.

soothed setup

Scaffold nano.yml / soothe.yml / daemon.yml from packaged templates and configure an LLM provider (endpoint, API key, default model).

Usage: soothed setup [options]

Options:

  • --config-dir <path> - Target config directory (default: $SOOTHE_HOME/config)
  • --yes / -y - Non-interactive: scaffold only; merge provider from env keys if present
  • --force - Overwrite existing YAML files with packaged templates
  • --skip-provider - Skip the interactive provider wizard
  • --skip-doctor - Skip the post-setup provider health check

Examples:

# Interactive first-time setup
soothed setup

# CI / scripts
export OPENAI_API_KEY=sk-...
soothed setup --yes

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

Output (background):

Starting daemon...
Daemon started successfully (PID: 12345, ws://127.0.0.1:8765)

soothed stop

Stop the running Soothe daemon.

Usage: soothed stop

Examples:

soothed stop

soothed status

Fast local daemon status check (no daemon imports, no RPC). Reads the PID file and probes the WebSocket port directly.

Usage: soothed status

Examples:

soothed status

Output (running):

Daemon status: running
PID: 12345
WebSocket: ws://127.0.0.1:8765

When the daemon is not running it prints Daemon status: stopped; if the PID file is missing but the port is live it prints Daemon status: running (orphan — PID file missing).

For a richer status view (PID, start time, active threads, versions, readiness), use soothe status — see Status commands.

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. Submit tasks to the daemon’s autopilot scheduler and manage goals/jobs. Requires a running daemon (soothed start). Alias: soothe ap ....

soothe autopilot submit

Submit a task for asynchronous autonomous execution.

Usage: soothe autopilot submit [task] [options]

Arguments:

  • task - Task description (omit to use --file or GOAL.md in cwd; - for stdin)

Options:

  • --file, -f <path> - Read task from a file (default: GOAL.md when task omitted)
  • --priority, -p <n> - Goal priority (0–100, default: 50)
  • --workspace, -w <dir> - Workspace directory (default: cwd)
  • --rail <id> - LoopRail id (e.g. feature-dev, greenfield-system, spike)
  • --wait - Wait until the goal completes (synchronous)

Examples:

soothe autopilot submit "Refactor the auth module and add tests"
soothe ap submit --file goal.md --rail feature-dev
soothe autopilot submit "Run benchmarks" --wait

soothe autopilot status

Show autopilot state and job summary.

Usage: soothe autopilot status

soothe autopilot jobs

List all autopilot jobs.

Usage: soothe autopilot jobs

soothe autopilot goals

List all autopilot goals.

Usage: soothe autopilot goals

soothe autopilot job

Show job details and goal DAG for a specific job.

Usage: soothe autopilot job <job-id>

soothe autopilot goal

Show details for a specific goal.

Usage: soothe autopilot goal <goal-id>

soothe autopilot stop

Stop a goal, a job subtree, or all open goals. Specify exactly one of: goal-id, --all, or --job <id>.

Usage: soothe autopilot stop [goal-id] [options]

Options:

  • --all - Stop all open goals
  • --job <job-id> - Stop a job and its descendants

soothe autopilot resume

Resume a suspended or blocked goal.

Usage: soothe autopilot resume <goal-id>

soothe autopilot guide

Absorb operator guidance into ContextEngine for the next dispatch. Does not create or inject goals.

Usage: soothe autopilot guide <job-id> <text> [options]

Options:

  • --goal, -g <goal-id> - Optional goal under the job (default: job-wide scope)

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 submit "Optimize the database queries"

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 autopilot "task" soothe autopilot submit "task"