setup / doctor / reset / uninstall

snippbot setup

Launch the Snippbot installation wizard.

snippbot setup                         # Browser-based wizard (default)
snippbot setup --headless              # CLI-only interactive setup
snippbot setup --resume                # Resume from last completed step
snippbot setup --step api-key          # Jump to a specific step
snippbot setup --force                 # Re-run even if already complete

Option	Default	Description
--mode	self-hosted	self-hosted or cloud
--headless	off	CLI-only setup (no browser)
--port	18781	Backend API port
--host	127.0.0.1	Host to bind
--resume	off	Resume from last completed step
--step	—	Jump to step: genesis, identity, api-key, ignition, awakening
--force	off	Re-run setup even if already complete

Browser mode (default): Opens http://127.0.0.1:18781/setup in your browser. The 8-step wizard walks through system checks, OS permissions, identity, authentication, voice, model selection, an optional starter-packages bundle, and final verification.

Headless mode: Prompts for display name, email, and API key directly in the terminal. Useful for server environments without a browser.

---

snippbot doctor

Run a full health check on your Snippbot installation.

snippbot doctor                   # Show all diagnostics
snippbot doctor --fix             # Auto-fix detected issues
snippbot doctor --json            # JSON output

Option	Description
--fix	Attempt to automatically fix detected issues
--json	Output as JSON

Checks performed:

Check	What it verifies
Python Version	Python 3.11+ is installed
Disk Space	Sufficient free space in home directory
Port Availability	The backend port (18781 by default, or whatever you passed to setup --port) and the gateway port (8787) are free
Config Directory	~/.snippbot/ exists and is writable
Config File	~/.snippbot/config.toml is valid TOML
Database	~/.snippbot/snippbot.db integrity check passes. The Genesis wizard step additionally runs a DatabaseSchemaCheck over auth.db, profile_settings.db, and snippbot.db — missing files are reported as a warning (created on first use), corruption as a hard failure.
API Key	At least one AI provider API key is configured (warns if none)
Claude CLI	Claude CLI is installed and logged in (informational)
Network	api.anthropic.com is reachable
Permissions	Data-directory files have secure permissions
Dependencies	Required Python packages are installed
Agents	At least one agent profile is present (informational)

Example output:

✓  Python Version: Python 3.12.2
✓  Disk Space: 45.2 GB free
✓  Port Availability: Ports 18781, 8787 available
✓  Config Directory: ~/.snippbot exists
✓  Config File: config.toml valid
✓  Database: snippbot.db (124 KB, integrity OK)
⚠  API Key: Not configured (will be set during setup)
✓  Network: api.anthropic.com reachable (87ms)

---

snippbot reset

Reset your Snippbot installation. Always creates a backup first.

snippbot reset                         # Full reset (keeps agent workspaces)
snippbot reset --soft                  # Reset setup wizard state only
snippbot reset --keep-config           # Keep config.toml
snippbot reset --keep-data             # Keep databases
snippbot reset --keep-agents           # Keep agent workspaces
snippbot reset --force                 # Skip confirmation prompt

snippbot reset --list-backups          # List available backups
snippbot reset --restore               # Restore from most recent backup

Option	Description
--soft	Reset setup state only — fastest way to re-run the wizard
--keep-agents	Preserve agent workspaces
--keep-config	Preserve config.toml
--keep-data	Preserve all databases
--force	Skip confirmation prompt
--restore	Restore from most recent backup
--list-backups	List all available backups

Reset levels (least to most destructive):

Level	Command	What’s wiped
Soft	reset --soft	Setup state only
Partial	reset --keep-agents	Config + databases
Full	reset	Config + databases + workspaces

All destructive resets — including --soft — create a timestamped backup in ~/.snippbot/backups/ before proceeding.

# List available backups
snippbot reset --list-backups
# • 2026-03-01T12-00-00 (snippbot.db, auth.db, config.toml, agents/)

# Restore from the most recent backup
snippbot reset --restore

# Or restore from a specific backup by name
snippbot reset --restore 2026-03-01T12-00-00

snippbot uninstall

Remove Snippbot. Stops the daemon (its agent gateway child stops with it), removes the systemd service if one was installed, and prints the final package-removal command. Your data is kept unless you pass --purge.

snippbot uninstall                     # stop daemon + remove service; keep data
snippbot uninstall --purge             # also delete ALL data (prompts first)
snippbot uninstall --purge --yes       # ...without the confirmation prompt

Flag	Effect
--purge	Also delete ~/.snippbot (agents, chat history, memory, config) and any legacy ~/.snippai. Irreversible.
--yes / -y	Skip the --purge confirmation prompt.

Why a final manual step? A running process can’t reliably delete the virtual environment it’s executing from (and on Windows the live interpreter’s files are locked), so the command prints the exact pipx uninstall snippbot (or pip uninstall) line to finish removal.

If a systemd service was installed by install-vps.sh --service, removing the unit needs root — when not run as root, uninstall prints the sudo commands to run.