> ## 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

> 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

```bash theme={null}
# 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:

```bash theme={null}
--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

```bash theme={null}
# 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](/cli/onboard)** - Interactive setup wizard for first-time configuration
* **[config](/cli/config)** - Manage application settings
* **[doctor](/cli/doctor)** - Run diagnostics and health checks
* **[status](/cli/status)** - Show system health and status

### Extensions & Tools

* **[tool](/cli/tool)** - Manage WASM tools (install, list, remove, auth)
* **[registry](/cli/registry)** - Browse and install extensions from the registry
* **[mcp](/cli/mcp)** - Manage MCP servers (hosted tool providers)

### Data & Memory

* **[memory](/cli/memory)** - Query and manage workspace memory

### Channels & Pairing

* **[pairing](/cli/pairing)** - Manage DM pairing requests (Telegram, Slack, etc.)

### System Management

* **[service](/cli/service)** - Manage OS service (launchd/systemd)

## Common Patterns

### First-Time Setup

```bash theme={null}
# Run the onboarding wizard
ironclaw onboard

# Check that everything is configured correctly
ironclaw doctor

# Start the agent
ironclaw
```

### Tool Management Workflow

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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](/configuration/overview) guide for a complete list.

## Shell Completion

Generate shell completion scripts:

```bash theme={null}
# 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:

```bash theme={null}
# 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