CLI Reference

Flag	Description
--dev	Isolated dev profile — state under `~/.squidclaw-dev`, port 19001
--profile <name>	Named profile — isolates all state under `~/.squidclaw-<name>`
--log-level <level>	`silent` \| `error` \| `warn` \| `info` \| `debug` \| `trace`
--no-color	Disable ANSI terminal colors
-V, --version	Print installed version
-h, --help	Show help for any command

🚀 Install & Run

How to install SquidClaw and start your agent.

squidclaw

Smart start — no config → launches setup, config exists → starts gateway

⌄

💡 This is the main entry point. Run it with no arguments — it figures out what to do automatically.

Examples

# First run — launches onboarding wizard
squidclaw

# Just run the gateway
squidclaw gateway run

# Dev mode — isolated state, port 19001
squidclaw --dev

onboard

Full interactive wizard — sets up API keys, channels, daemon, and workspace from scratch

⌄

$ squidclaw onboard [options]

Flag	Description
--anthropic-api-key <key>	Set Anthropic (Claude) API key directly
--openai-api-key <key>	Set OpenAI API key directly
--gemini-api-key <key>	Set Google Gemini API key directly
--flow <flow>	`quickstart` \| `advanced` \| `manual`
--mode <mode>	`local` \| `remote`
--gateway-token <token>	Pre-set gateway auth token
--gateway-port <port>	Gateway port 18789
--install-daemon	Auto-install gateway as system service
--skip-channels	Skip channel setup
--skip-skills	Skip skills setup
--skip-daemon	Skip service install
--non-interactive	No prompts — use with `--accept-risk`
--accept-risk	Required for `--non-interactive` mode
--reset	Wipe config before running wizard
--json	Output JSON summary on completion

Examples

# Standard interactive setup
squidclaw onboard

# Headless / scripted setup
squidclaw onboard --non-interactive --accept-risk \
  --anthropic-api-key sk-ant-... \
  --install-daemon --skip-channels

# Fresh start — wipe existing config first
squidclaw onboard --reset

setup

Lightweight init — creates config file and agent workspace only

⌄

$ squidclaw setup [options]

Flag	Description
--workspace <dir>	Agent workspace directory ~/.squidclaw/workspace
--mode <mode>	`local` \| `remote`
--remote-url <url>	Remote Gateway WebSocket URL
--remote-token <token>	Remote Gateway token
--non-interactive	No prompts
--wizard	Launch full onboarding wizard

📝 Use onboard for a full setup. Use setup when you just need to initialize the config/workspace file only.

doctor

Health checks + auto-fix for gateway, channels, and config issues

⌄

$ squidclaw doctor [options]

Flag	Description
--fix, --repair	Apply all recommended repairs automatically
--force	Aggressive repairs — overwrites custom service config
--deep	Scan system services for extra gateway installs
--generate-gateway-token	Regenerate the gateway auth token
--non-interactive	Safe migrations only, no prompts
--yes	Accept all defaults without prompting
--no-workspace-suggestions	Skip workspace memory system suggestions

Examples

# Run health check interactively
squidclaw doctor

# Auto-fix all issues
squidclaw doctor --fix

# Deep scan + aggressive repair
squidclaw doctor --deep --force

configure

Interactive wizard for credentials, channels, gateway, and agent defaults

⌄

$ squidclaw configure

📝 Similar to onboard but focused on reconfiguring an existing install.

🌐 Gateway

Control the WebSocket Gateway that connects your agent to all channels.

gateway *

Run, inspect, and control the WebSocket Gateway

⌄

Subcommand	Description
gateway run	Start gateway in foreground
gateway start	Start as background service
gateway stop	Stop the gateway service
gateway restart	Restart the gateway
gateway status	Show service status and health
gateway install	Install as system service (systemd / launchd)
gateway health	Fetch live health from running gateway
gateway probe	Full reachability + discovery check
gateway token	Manage gateway auth tokens

Examples

# Start gateway on custom port
squidclaw gateway --port 18789

# Kill anything on the port and start fresh
squidclaw gateway --force

# Install as systemd service
squidclaw gateway install

# Check status
squidclaw gateway status

status

Show channel health and recent session recipients

⌄

$ squidclaw status

Shows connected channels, recent active sessions, and gateway connection state.

health

Fetch health JSON from the running gateway

⌄

$ squidclaw health

💡 Useful in scripts — returns exit code 0 if gateway is healthy.

logs

Tail gateway file logs via RPC

⌄

$ squidclaw logs [--level <level>] [--follow]

Examples

squidclaw logs --follow
squidclaw logs --level debug

dashboard

Open the Control UI in your browser with your current token

⌄

$ squidclaw dashboard

tui

Open a terminal chat UI connected to the Gateway

⌄

$ squidclaw tui

💡 Chat with your agent directly from the terminal — no phone or messaging app needed.

💬 Channels & Messaging

Connect and manage Telegram, WhatsApp, Discord, Slack, Signal, and more.

channels *

Manage connected chat channels

⌄

Subcommand	Description
channels list	List all configured channels
channels status	Show live connection status per channel
channels add <type>	Add a new channel (telegram, discord, slack, etc.)
channels login	Link WhatsApp by scanning a QR code
channels login --verbose	QR scan with detailed connection logs
channels remove <id>	Remove a channel by ID
channels reload	Reload channel config without restarting

Examples

# Add Telegram bot
squidclaw channels add telegram

# Link WhatsApp (shows QR to scan)
squidclaw channels login whatsapp --verbose

# Add Discord bot
squidclaw channels add discord

# List all channels
squidclaw channels list

message *

Send, read, and manage messages via any configured channel

⌄

Flag	Description
message send	Send a message
--channel <name>	Target channel: `telegram`, `whatsapp`, `discord`, etc.
--target <id/name>	Recipient: phone number, username, or group ID
--message <text>	Message text
--json	Print result as JSON

Examples

# Send via Telegram
squidclaw message send --channel telegram --target @username --message "Hi"

# Send via WhatsApp
squidclaw message send --target +15555550123 --message "Hello"

directory *

Look up contact and group IDs for your connected channels

⌄

$ squidclaw directory [--channel <name>]

💡 Use this to find the correct IDs to use with --target in message send.

🤖 Agents & Models

Create and manage agents, switch AI models, and inspect sessions.

agents *

Manage isolated agents — each with its own workspace, model, and auth

⌄

Subcommand	Description
agents list	List all configured agents
agents add	Create a new agent
agents delete <id>	Remove an agent
agents info <id>	Show agent details and config

agent

Run a single agent turn via the Gateway and optionally deliver the reply

⌄

$ squidclaw agent --to <target> --message <text> [--deliver]

Flag	Description
--to <target>	Target phone number or user ID
--message <text>	Message to send to the agent
--deliver	Send the agent's reply back via WhatsApp/channel

Example

squidclaw agent --to +15555550123 --message "Run daily summary" --deliver

models *

Discover, scan, and configure AI models

⌄

Subcommand	Description
models list	List available models from configured providers
models scan	Auto-discover models from your API keys
models set <model>	Set the default model
models status	Show current model config
models auth add	Add API key for a provider

Examples

# See all available models
squidclaw models list

# Auto-detect models from your API keys
squidclaw models scan

# Switch to Claude Sonnet
squidclaw models set anthropic/claude-sonnet-4-20250514

sessions *

List and inspect stored conversation sessions

⌄

$ squidclaw sessions [list] [--limit <n>]

🧠 Tools & Memory

Skills, hooks, long-term memory, and scheduled automation.

skills *

List and inspect available skills (50+ built-in)

⌄

Subcommand	Description
skills list	List all installed skills
skills info <name>	Show skill details and SKILL.md
skills install <name>	Install a skill from ClaWHub

hooks *

Manage internal agent hooks (session-memory, bootstrap, etc.)

⌄

Subcommand	Description
hooks list	List all registered hooks and their event bindings
hooks info <name>	Show hook details
hooks enable <name>	Enable a hook
hooks disable <name>	Disable a hook

memory *

Search and reindex memory files (long-term memory system)

⌄

Subcommand	Description
memory search <query>	Search memory files semantically
memory reindex	Rebuild the memory search index
memory stats	Show memory usage stats

cron *

Manage scheduled cron jobs via the Gateway scheduler

⌄

Subcommand	Description
cron list	List all scheduled jobs
cron add	Create a new cron job
cron rm <id>	Remove a cron job
cron run <id>	Trigger a job immediately
cron status	Show scheduler status

Example

squidclaw cron list
squidclaw cron run <job-id>

🔒 Security & System

Audits, secrets, system events, nodes, and plugins.

security *

Security tools and local config audits

⌄

Subcommand	Description
security audit	Run full security audit of config + system
security policy	View or update security policy
security scan	Scan for exposed credentials or risks

secrets *

Hot-reload secrets without restarting the gateway

⌄

$ squidclaw secrets reload

system *

System events, heartbeat, and presence management

⌄

Subcommand	Description
system event <text>	Send a system event into the active session
system heartbeat	Trigger or configure heartbeat
system presence <status>	Set presence: `online`, `idle`, `dnd`

nodes *

Manage paired nodes — remote agents, cameras, screens, and more

⌄

Subcommand	Description
nodes list	List all paired nodes
nodes describe <id>	Show node capabilities
nodes notify <id>	Send notification to a node
nodes run <id> <cmd>	Run a command on a node

plugins *

Manage SquidClaw plugins and extensions

⌄

Subcommand	Description
plugins list	List installed plugins
plugins install <pkg>	Install a plugin by npm package name
plugins remove <name>	Uninstall a plugin

🔧 Maintenance

Update, reset, and manage your SquidClaw install.

update *

Update SquidClaw to the latest version

⌄

$ squidclaw update [--channel <channel>]

Subcommand / Flag	Description
update status	Show current version + available updates
update run	Pull + install latest version, then restart
--channel <name>	Update channel: `stable` \| `next`

reset

Reset local config and state — keeps the CLI installed

⌄

$ squidclaw reset [--scope <scope>]

Flag	Description
--scope config	Reset config only
--scope config+creds+sessions	Reset config, credentials, and sessions
--scope full	Full reset including workspace

⚠️ This cannot be undone. Back up your workspace first.

uninstall

Remove the gateway service and local data — keeps the CLI installed

⌄

$ squidclaw uninstall

⚠️ Removes the service and all state. CLI binary stays; use npm uninstall -g squidclaw to remove it too.

config *

Non-interactive config helpers — read, write, and validate squidclaw.json

⌄

Subcommand	Description
config get <key>	Read a config value by dot-path
config set <key> <val>	Write a config value
config unset <key>	Remove a config key
config file	Print the config file path
config validate	Validate current config against schema

Examples

squidclaw config get agents.defaults.model.primary
squidclaw config set tools.profile full
squidclaw config validate

completion

Generate shell completion script for bash, zsh, or fish

⌄

$ squidclaw completion [--shell bash|zsh|fish]

Example

# Add to ~/.bashrc
squidclaw completion --shell bash >> ~/.bashrc

⚡ Global Flags — available on all commands

🚀 Install & Run

🌐 Gateway

💬 Channels & Messaging

🤖 Agents & Models

🧠 Tools & Memory

🔒 Security & System

🔧 Maintenance