CLI Reference

ClawDesk ships a single binary, clawdesk, built with clap derive. Every interaction—starting the gateway, sending messages, managing channels—goes through this CLI.

clawdesk [OPTIONS] <COMMAND>

Global Options

Flag	Short	Env Var	Default	Description
`--config <PATH>`	`-c`	`CLAWDESK_CONFIG`	`~/.clawdesk/config.toml`	Path to configuration file
`--log-level <LEVEL>`	`-l`	`CLAWDESK_LOG`	`info`	Log level: `trace`, `debug`, `info`, `warn`, `error`
`--data-dir <PATH>`	`-d`	`CLAWDESK_DATA_DIR`	`~/.clawdesk/data`	Data directory for sessions, memory, and plugins
`--no-color`		`NO_COLOR`	`false`	Disable colored output
`--json`	`-j`		`false`	Output in JSON format
`--quiet`	`-q`		`false`	Suppress non-essential output
`--verbose`	`-v`		`false`	Enable verbose logging (same as `--log-level debug`)

Commands Overview

`gateway`

Start the ClawDesk gateway server.

clawdesk gateway [OPTIONS]

Options

Flag	Short	Default	Description
`--host <ADDR>`	`-H`	`0.0.0.0`	Bind address
`--port <PORT>`	`-p`	`1420`	HTTP port
`--ws-port <PORT>`		`1421`	WebSocket port (0 = same as HTTP)
`--tls-cert <PATH>`			TLS certificate file
`--tls-key <PATH>`			TLS private key file
`--workers <N>`	`-w`	CPU count	Number of async worker threads
`--max-sessions <N>`		`1000`	Maximum concurrent sessions
`--cors-origin <ORIGIN>`		`*`	CORS allowed origins (comma-separated)
`--no-discovery`		`false`	Disable mDNS service discovery
`--pid-file <PATH>`			Write PID to file
`--daemon`		`false`	Run in background (Unix only)

Examples

# Start with defaults
clawdesk gateway

# Production setup
clawdesk gateway \
  --host 0.0.0.0 \
  --port 8443 \
  --tls-cert /etc/clawdesk/cert.pem \
  --tls-key /etc/clawdesk/key.pem \
  --workers 8 \
  --max-sessions 5000

# Development with verbose logging
clawdesk gateway -p 3000 -l debug

tip

Use --daemon and --pid-file together for systemd-free deployments:

clawdesk gateway --daemon --pid-file /var/run/clawdesk.pid

`message`

Send a one-shot message through the agent pipeline without starting a persistent gateway.

clawdesk message [OPTIONS] <TEXT>

Options

Flag	Short	Default	Description
`--provider <NAME>`	`-P`	config default	Provider to use (`anthropic`, `openai`, `ollama`, etc.)
`--model <MODEL>`	`-m`	provider default	Model identifier
`--session <ID>`	`-s`	new session	Resume an existing session
`--system <PROMPT>`		config default	System prompt override
`--temperature <F>`	`-t`	`0.7`	Sampling temperature
`--max-tokens <N>`		`4096`	Maximum response tokens
`--tools <LIST>`		all enabled	Comma-separated tool allowlist
`--no-stream`		`false`	Wait for complete response (no streaming)
`--output <FILE>`	`-o`	stdout	Write response to file
`--attach <FILE>`	`-a`		Attach file(s) to the message

Examples

# Simple question
clawdesk message "What is the capital of France?"

# Use a specific provider and model
clawdesk message -P anthropic -m claude-sonnet-4-20250514 "Explain monads"

# Continue a conversation
clawdesk message -s sess_abc123 "Tell me more about that"

# Pipe input
echo "Summarize this" | clawdesk message -

# Attach files
clawdesk message -a report.pdf "Summarize the attached document"

# Save response
clawdesk message -o response.md "Write a project plan"

info

When stdin is not a TTY and no TEXT argument is given, clawdesk message reads from stdin automatically.

`channels`

Manage messaging channel connections.

clawdesk channels <SUBCOMMAND>

Subcommands

Subcommand	Description
`list`	Show all configured channels and their status
`add <TYPE>`	Add a new channel interactively
`remove <ID>`	Remove a channel by ID
`start <ID>`	Start a specific channel
`stop <ID>`	Stop a specific channel
`restart <ID>`	Restart a specific channel
`status <ID>`	Show detailed status for a channel
`test <ID>`	Send a test message through the channel
`logs <ID>`	Tail channel-specific logs

`channels list`

clawdesk channels list [--format table|json|csv]

Example output:

┌────────────┬──────────┬─────────┬───────────┬──────────────┐
│ ID         │ Type     │ Status  │ Messages  │ Last Active  │
├────────────┼──────────┼─────────┼───────────┼──────────────┤
│ tg_main    │ Telegram │ Running │ 14,302    │ 2 min ago    │
│ dc_server  │ Discord  │ Running │ 8,451     │ 5 min ago    │
│ sl_work    │ Slack    │ Stopped │ 0         │ 3 days ago   │
│ wc_public  │ WebChat  │ Running │ 231       │ 1 min ago    │
└────────────┴──────────┴─────────┴───────────┴──────────────┘

`channels add`

clawdesk channels add telegram --token "BOT_TOKEN" --name "My Bot"
clawdesk channels add discord --token "BOT_TOKEN" --guild-id 123456
clawdesk channels add slack --app-token "xapp-..." --bot-token "xoxb-..."
clawdesk channels add webchat --port 8080 --allowed-origins "https://example.com"

warning

Channel tokens are stored encrypted in the data directory. Never pass tokens via command-line in shared environments—use environment variables or interactive mode:

clawdesk channels add telegram  # Prompts for token interactively

`plugins`

Manage the plugin ecosystem.

clawdesk plugins <SUBCOMMAND>

Subcommands

Subcommand	Description
`list`	List installed plugins
`install <SOURCE>`	Install a plugin from path, URL, or registry
`uninstall <NAME>`	Remove a plugin
`enable <NAME>`	Enable a disabled plugin
`disable <NAME>`	Disable a plugin without removing
`update [NAME]`	Update one or all plugins
`inspect <NAME>`	Show plugin metadata and capabilities
`create <NAME>`	Scaffold a new plugin project

Examples

# Install from the plugin registry
clawdesk plugins install clawdesk-plugin-weather

# Install from a local path
clawdesk plugins install ./my-plugin/

# Install from a git URL
clawdesk plugins install https://github.com/user/clawdesk-plugin-rag.git

# Create a new plugin scaffold
clawdesk plugins create my-awesome-plugin --lang rust

# Inspect plugin details
clawdesk plugins inspect weather

`cron`

Manage scheduled tasks.

clawdesk cron <SUBCOMMAND>

Subcommands

Subcommand	Description
`list`	Show all scheduled tasks
`add`	Create a new scheduled task
`remove <ID>`	Remove a task
`enable <ID>`	Enable a paused task
`disable <ID>`	Pause a task
`run <ID>`	Trigger immediate execution
`history <ID>`	Show execution history

Examples

# Add a daily summary task
clawdesk cron add \
  --name "daily-summary" \
  --schedule "0 9 * * *" \
  --channel tg_main \
  --message "Generate a summary of yesterday's conversations"

# List all tasks
clawdesk cron list

# View execution history
clawdesk cron history daily-summary --limit 20

# Trigger a task now
clawdesk cron run daily-summary

`agent`

Configure and manage agent behavior.

clawdesk agent <SUBCOMMAND>

Subcommands

Subcommand	Description
`show`	Display current agent configuration
`set <KEY> <VALUE>`	Set an agent configuration value
`reset`	Reset to default configuration
`tools`	List available tools and their status
`tools enable <NAME>`	Enable a tool
`tools disable <NAME>`	Disable a tool
`pipeline show`	Display the current pipeline stage order
`pipeline set <STAGES>`	Set custom pipeline stage order

Examples

# Show current config
clawdesk agent show

# Set default provider
clawdesk agent set provider anthropic
clawdesk agent set model claude-sonnet-4-20250514

# Manage tools
clawdesk agent tools
clawdesk agent tools enable web_search
clawdesk agent tools disable code_execution

# View pipeline
clawdesk agent pipeline show

`config`

Manage ClawDesk configuration.

clawdesk config <SUBCOMMAND>

Subcommands

Subcommand	Description
`show`	Display the full resolved configuration
`get <KEY>`	Get a specific configuration value
`set <KEY> <VALUE>`	Set a configuration value
`edit`	Open config in `$EDITOR`
`validate`	Validate the configuration file
`reset`	Reset to defaults
`path`	Print the config file path
`export`	Export config (redacting secrets)
`import <FILE>`	Import a configuration file

Examples

# Show full config
clawdesk config show

# Set values
clawdesk config set gateway.port 8443
clawdesk config set providers.anthropic.api_key "sk-ant-..."
clawdesk config set memory.embedding_provider ollama

# Validate
clawdesk config validate

# Export (safe to share)
clawdesk config export > my-config.toml

`login`

Authenticate with provider APIs.

clawdesk login [OPTIONS] [PROVIDER]

Options

Flag	Description
`--api-key <KEY>`	Set API key directly
`--browser`	Open browser for OAuth flow
`--check`	Verify existing credentials
`--revoke`	Remove stored credentials

Examples

# Interactive login
clawdesk login anthropic

# Set API key directly
clawdesk login openai --api-key "sk-..."

# Verify all credentials
clawdesk login --check

# Revoke a provider
clawdesk login anthropic --revoke

`doctor`

Diagnose system health and configuration issues.

clawdesk doctor [OPTIONS]

Options

Flag	Description
`--fix`	Attempt to automatically fix issues
`--verbose`	Show detailed diagnostic information
`--check <NAME>`	Run a specific check only

Checks Performed

Check	Description
`config`	Configuration file syntax and schema
`providers`	API key validity and connectivity
`channels`	Channel token validity
`memory`	Embedding model availability
`plugins`	Plugin integrity and dependencies
`network`	Network connectivity and DNS
`storage`	Data directory permissions and disk space
`version`	Version compatibility

Example Output

$ clawdesk doctor
🔍 Running diagnostics...

  ✅ Configuration        valid config at ~/.clawdesk/config.toml
  ✅ Anthropic provider    API key valid, claude-sonnet-4-20250514 available
  ⚠️  OpenAI provider      API key set but rate-limited
  ✅ Telegram channel      bot token valid, webhook configured
  ❌ Slack channel         app token expired — run `clawdesk login slack`
  ✅ Memory system         embedding model loaded (384 dims)
  ✅ Plugins               3 plugins loaded, 0 errors
  ✅ Network               all endpoints reachable
  ✅ Storage               14.2 GB free

Found 1 error and 1 warning.
Run `clawdesk doctor --fix` to attempt automatic fixes.

`init`

Initialize a new ClawDesk configuration.

clawdesk init [OPTIONS] [PATH]

Options

Flag	Description
`--template <NAME>`	Use a predefined template (`minimal`, `standard`, `full`)
`--non-interactive`	Skip prompts, use defaults
`--force`	Overwrite existing configuration

Example

# Interactive setup
clawdesk init

# Minimal config in a custom directory
clawdesk init --template minimal /path/to/project

# CI/CD setup
clawdesk init --template standard --non-interactive

The init wizard walks through:

Provider selection and API key entry
Default model selection
Channel setup
Memory configuration
Security defaults

`completions`

Generate shell completions.

clawdesk completions <SHELL>

Supported shells: bash, zsh, fish, elvish, powershell.

Setup

# Zsh
clawdesk completions zsh > ~/.zfunc/_clawdesk
echo 'fpath=(~/.zfunc $fpath)' >> ~/.zshrc

# Bash
clawdesk completions bash > /usr/local/etc/bash_completion.d/clawdesk

# Fish
clawdesk completions fish > ~/.config/fish/completions/clawdesk.fish

`security`

Manage security policies and audit logs.

clawdesk security <SUBCOMMAND>

Subcommands

Subcommand	Description
`allowlist show`	Display the current allowlist
`allowlist add <PATTERN>`	Add an allowlist entry
`allowlist remove <PATTERN>`	Remove an allowlist entry
`acl show`	Show access control rules
`acl grant <USER> <ROLE>`	Grant a role to a user
`acl revoke <USER> <ROLE>`	Revoke a role from a user
`audit tail`	Tail the audit log
`audit export`	Export audit log
`audit verify`	Verify hash-chain integrity
`scan <TEXT>`	Test content against scanning rules
`token create`	Create a scoped API token
`token revoke <ID>`	Revoke an API token
`token list`	List active API tokens

Examples

# Manage allowlist
clawdesk security allowlist add "user:12345"
clawdesk security allowlist show

# Check audit integrity
clawdesk security audit verify

# Create a scoped token
clawdesk security token create \
  --scope "read:sessions,write:messages" \
  --expires "30d" \
  --name "ci-bot"

# Test content scanning
echo "DROP TABLE users;" | clawdesk security scan

Environment Variables

All CLI flags can be set via environment variables with the CLAWDESK_ prefix:

Variable	Description
`CLAWDESK_CONFIG`	Config file path
`CLAWDESK_DATA_DIR`	Data directory path
`CLAWDESK_LOG`	Log level
`CLAWDESK_GATEWAY_HOST`	Gateway bind address
`CLAWDESK_GATEWAY_PORT`	Gateway port
`CLAWDESK_ANTHROPIC_API_KEY`	Anthropic API key
`CLAWDESK_OPENAI_API_KEY`	OpenAI API key
`CLAWDESK_OLLAMA_URL`	Ollama server URL
`CLAWDESK_GEMINI_API_KEY`	Gemini API key
`CLAWDESK_AWS_REGION`	AWS region for Bedrock
`CLAWDESK_TELEGRAM_TOKEN`	Telegram bot token
`CLAWDESK_DISCORD_TOKEN`	Discord bot token
`CLAWDESK_SLACK_APP_TOKEN`	Slack app token
`CLAWDESK_SLACK_BOT_TOKEN`	Slack bot token

tip

Environment variables take precedence over config file values but are overridden by explicit CLI flags. The precedence order is:

CLI flags > Environment variables > Config file > Defaults

Exit Codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Invalid arguments or usage
`3`	Configuration error
`4`	Authentication error
`5`	Network/connectivity error
`10`	Provider error
`11`	Channel error
`12`	Plugin error
`130`	Interrupted (Ctrl+C)

Global Options​

Commands Overview​

gateway​

Options​

Examples​

message​

Options​

Examples​

channels​

Subcommands​

channels list​

channels add​

plugins​

Subcommands​

Examples​

cron​

Subcommands​

Examples​

agent​

Subcommands​

Examples​

config​

Subcommands​

Examples​

login​

Options​

Examples​

doctor​

Options​

Checks Performed​

Example Output​

init​

Options​

Example​

completions​

Setup​

security​

Subcommands​

Examples​

Environment Variables​

Exit Codes​

Global Options

Commands Overview

`gateway`

Options

Examples

`message`

Options

Examples

`channels`

Subcommands

`channels list`

`channels add`

`plugins`

Subcommands

Examples

`cron`

Subcommands

Examples

`agent`

Subcommands

Examples

`config`

Subcommands

Examples

`login`

Options

Examples

`doctor`

Options

Checks Performed

Example Output

`init`

Options

Example

`completions`

Setup

`security`

Subcommands

Examples

Environment Variables

Exit Codes