CLI Reference

PocketPaw ships with a full set of CLI commands for managing your local AI agent without the web dashboard. Every command supports --json for scripting and automation.

Starting PocketPaw

# Web dashboard (default, opens browser)
pocketpaw

# API-only server (no dashboard UI)
pocketpaw serve

# Development mode (auto-reload on file changes)
pocketpaw --dev

# Custom host and port
pocketpaw --host 0.0.0.0 --port 9000

Headless Channel Modes

Run PocketPaw as a headless bot on one or more channels:

pocketpaw --telegram          # Telegram-only mode
pocketpaw --discord           # Discord bot
pocketpaw --slack             # Slack bot (Socket Mode)
pocketpaw --whatsapp          # WhatsApp webhook server
pocketpaw --discord --slack   # Multiple channels simultaneously

Agent Status

# Show current agent status
pocketpaw status

# JSON output for scripting
pocketpaw status --json

# Live monitoring (refresh every 2 seconds)
pocketpaw status --watch

# Custom refresh interval
pocketpaw status --watch 5

Health and Diagnostics

# Quick health check (startup checks only, no network calls)
pocketpaw health

# Full diagnostics (config + connectivity + version check)
pocketpaw doctor

# JSON output
pocketpaw health --json
pocketpaw doctor --json

health runs fast, offline checks (config exists, API key format, disk space, etc.). doctor additionally tests network connectivity to your configured LLM provider.

Channels

# List all channels with configured/autostart status
pocketpaw channels

# Start a channel adapter (requires a running PocketPaw instance)
pocketpaw channels start discord

# Stop a channel adapter
pocketpaw channels stop slack

# JSON output
pocketpaw channels --json

Info

channels start and channels stop communicate with a running PocketPaw instance via its REST API. The dashboard or pocketpaw serve must be running first.

Skills

# List all available skills
pocketpaw skills

# JSON output
pocketpaw skills --json

Skills are loaded from three directories (in priority order):

~/.agents/skills/ (AgentSkills ecosystem)
~/.claude/skills/ (Claude Code / SDK standard)
~/.pocketpaw/skills/ (PocketPaw-specific)

Sessions

# List recent chat sessions
pocketpaw sessions

# Search session content
pocketpaw sessions search "deployment script"

# Delete a session
pocketpaw sessions delete <session-key>

# Limit results
pocketpaw sessions --limit 50

# JSON output
pocketpaw sessions --json

Memory

# Show memory stats (long-term entries, daily notes, session count)
pocketpaw memory

# Search long-term memories
pocketpaw memory search "API integration"

# Limit search results
pocketpaw memory search "project" --limit 20

# JSON output
pocketpaw memory --json

Configuration

# Show current config (sensitive values masked)
pocketpaw config

# Set a config value
pocketpaw config set agent_backend openai_agents
pocketpaw config set web_port 9000

# Validate API keys and settings
pocketpaw config validate

# Print config file path
pocketpaw config path

# JSON output
pocketpaw config --json
pocketpaw config validate --json

Config values are automatically coerced to the correct type (boolean, integer, list, etc.).

Errors

# Show last 20 errors
pocketpaw errors

# Show more errors
pocketpaw errors --limit 50

# Filter errors
pocketpaw errors --search "timeout"

# JSON output
pocketpaw errors --json

Errors are sourced from the health engine’s persistent error store.

Audit Logs

# Show last 50 audit log entries
pocketpaw logs

# Tail the audit log in real time
pocketpaw logs --follow

# Show fewer entries
pocketpaw logs --limit 10

# JSON output
pocketpaw logs --json

The audit log is stored at ~/.pocketpaw/audit.jsonl.

Provider Diagnostics

# Test Ollama connectivity, model availability, and tool calling
pocketpaw --check-ollama

# Test OpenAI-compatible endpoint
pocketpaw --check-openai-compatible

Security

# Run security audit
pocketpaw --security-audit

# Auto-fix issues found by audit
pocketpaw --security-audit --fix

# Scan memory files for PII
pocketpaw --pii-scan

Update

# Check for updates and install via uv
pocketpaw update

Global Flags

Flag	Description
`--json`	Output as JSON (works with most subcommands)
`--limit N`	Limit number of results
`--follow`	Tail mode (for `logs`)
`--watch [N]`	Live refresh every N seconds (for `status`, default: 2)
`--host HOST`	Bind web server to specific host
`--port PORT`	Web server port (default: 8888)
`--dev`	Development mode with auto-reload
`--version`	Show version

Last updated: April 29, 2026

3 min read

Edit this page

Was this page helpful?