CLI Overview

IronClaw command-line interface overview and common patterns

CLI Overview

The IronClaw CLI provides comprehensive control over your AI assistant through terminal commands. Use ironclaw <subcommand> --help for detailed information about any command.

Basic Usage

# Start the agent (default behavior)
ironclaw
ironclaw run

# Get help
ironclaw --help
ironclaw <subcommand> --help

# Check version
ironclaw --version

Global Flags

These flags work with any command:

--cli-only          # Run in interactive CLI mode only (disable other channels)
--no-db             # Skip database connection (for testing)
--message, -m       # Single message mode - send one message and exit
--config, -c        # Configuration file path (optional, uses env vars by default)
--no-onboard        # Skip first-run onboarding check

Examples

# Send a single message and exit
ironclaw -m "What's the weather like?"

# Use custom config file
ironclaw --config /path/to/config.toml

# Run without database (useful for testing)
ironclaw --no-db

# CLI-only mode (disable Telegram, Slack, etc.)
ironclaw --cli-only

Command Categories

Setup & Configuration

• onboard - Interactive setup wizard for first-time configuration
• config - Manage application settings
• doctor - Run diagnostics and health checks
• status - Show system health and status

Extensions & Tools

• tool - Manage WASM tools (install, list, remove, auth)
• registry - Browse and install extensions from the registry
• mcp - Manage MCP servers (hosted tool providers)

Data & Memory

• memory - Query and manage workspace memory

Channels & Pairing

• pairing - Manage DM pairing requests (Telegram, Slack, etc.)

System Management

• service - Manage OS service (launchd/systemd)

Common Patterns

First-Time Setup

# Run the onboarding wizard
ironclaw onboard

# Check that everything is configured correctly
ironclaw doctor

# Start the agent
ironclaw

Tool Management Workflow

# Install a WASM tool from source
ironclaw tool install ~/my-tool/ --name mytool

# List installed tools
ironclaw tool list

# Configure authentication for a tool
ironclaw tool auth mytool

# View tool details
ironclaw tool info mytool

MCP Server Workflow

# Add an MCP server
ironclaw mcp add notion https://mcp.notion.com --client-id YOUR_CLIENT_ID

# Authenticate with the server
ironclaw mcp auth notion

# Test the connection
ironclaw mcp test notion

# List all configured servers
ironclaw mcp list

Memory Operations

# Search workspace memory
ironclaw memory search "query"

# Read a file
ironclaw memory read MEMORY.md

# Write to a file
ironclaw memory write notes/idea.md "My brilliant idea"

# View workspace tree
ironclaw memory tree

Configuration Management

# List all settings
ironclaw config list

# Filter settings by prefix
ironclaw config list --filter agent

# Get a specific setting
ironclaw config get agent.name

# Set a setting
ironclaw config set agent.name "my-bot"

# Reset to default
ironclaw config reset agent.name

Exit Codes

• 0 - Success
• 1 - General error
• Non-zero - Command-specific error

Environment Variables

The CLI respects standard environment variables:

• DATABASE_URL - PostgreSQL connection string
• DATABASE_BACKEND - Backend type (postgres, libsql, turso, sqlite)
• LIBSQL_PATH - Path to libSQL database file
• SECRETS_MASTER_KEY - Master key for secrets encryption
• NEARAI_API_KEY - NEAR AI API key
• NEARAI_SESSION - NEAR AI session file path

See the Configuration guide for a complete list.

Shell Completion

Generate shell completion scripts:

# Bash
ironclaw completion --shell bash > ironclaw.bash
source ironclaw.bash

# Zsh
ironclaw completion --shell zsh > _ironclaw
# Place in your $fpath

# Fish
ironclaw completion --shell fish > ironclaw.fish
source ironclaw.fish

Output Formats

Most list commands support both human-readable and JSON output:

# Human-readable (default)
ironclaw mcp list

# Detailed output
ironclaw mcp list --verbose

# JSON output
ironclaw pairing list telegram --json

Tips

• Use --help liberally - every command has detailed help text
• Tab completion makes navigation faster (install shell completions)
• Most commands validate inputs and provide actionable error messages
• Check ironclaw doctor if something isn’t working
• Use --verbose or -v flags for detailed output when debugging