Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt

Use this file to discover all available pages before exploring further.

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us