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

# ironclaw tool

> Manage WASM tools for extending IronClaw capabilities

# ironclaw tool

Manage WASM-based tools that extend IronClaw's capabilities. Tools are WebAssembly components that provide functions the agent can use during conversations.

## Subcommands

* `install` - Install a WASM tool from source or .wasm file
* `list` - List installed tools
* `remove` - Remove an installed tool
* `info` - Show information about a tool
* `auth` - Configure OAuth authentication for a tool
* `setup` - Configure required secrets for a tool

***

## ironclaw tool install

Install a WASM tool from a source directory or compiled .wasm file.

### Syntax

```bash theme={null}
ironclaw tool install <PATH> [FLAGS]
```

### Arguments

**`<PATH>`**

Path to:

* Tool source directory (containing `Cargo.toml`), or
* Compiled `.wasm` file

### Flags

**`--name, -n <NAME>`**

Tool name (defaults to directory/file name).

**`--capabilities <PATH>`**

Path to capabilities JSON file. Auto-detected if not specified:

* `<name>.capabilities.json`
* `capabilities.json`

**`--target, -t <DIR>`**

Target installation directory.

* Default: `~/.ironclaw/tools/`

**`--release`**

Build in release mode (default: `true`).

**`--skip-build`**

Skip compilation, use existing .wasm file.

**`--force, -f`**

Force overwrite if tool already exists.

### Examples

#### Install from Source Directory

```bash theme={null}
# Install from source, auto-detect name
ironclaw tool install ~/projects/my-tool/

# Install with custom name
ironclaw tool install ~/projects/my-tool/ --name mytool

# Install to custom location
ironclaw tool install ~/projects/my-tool/ --target /opt/ironclaw/tools/
```

#### Install from .wasm File

```bash theme={null}
# Install compiled .wasm file
ironclaw tool install ~/downloads/notion-tool.wasm

# Install with custom name
ironclaw tool install ~/downloads/tool.wasm --name notion
```

#### Install with Capabilities

```bash theme={null}
# Auto-detected capabilities file
ironclaw tool install ~/my-tool/  # Looks for capabilities.json

# Specify capabilities file
ironclaw tool install ~/my-tool/ --capabilities ~/my-tool/custom-caps.json
```

#### Skip Build (Use Existing)

```bash theme={null}
# Use pre-built .wasm from target directory
ironclaw tool install ~/my-tool/ --skip-build
```

### Output

```bash theme={null}
Installing mytool to /Users/you/.ironclaw/tools/mytool.wasm
  Copying capabilities from /Users/you/my-tool/capabilities.json

Installed successfully:
  Name: mytool
  WASM: /Users/you/.ironclaw/tools/mytool.wasm
  Size: 245760 bytes
  Hash: a3f2e1d4c5b6a7f8
  Caps: /Users/you/.ironclaw/tools/mytool.capabilities.json
```

***

## ironclaw tool list

List all installed tools.

### Syntax

```bash theme={null}
ironclaw tool list [FLAGS]
```

### Flags

**`--dir, -d <PATH>`**

Directory to list tools from.

* Default: `~/.ironclaw/tools/`

**`--verbose, -v`**

Show detailed information.

### Examples

```bash theme={null}
# List installed tools
ironclaw tool list

# List with details
ironclaw tool list --verbose

# List from custom directory
ironclaw tool list --dir /opt/ironclaw/tools/
```

### Output

**Default output:**

```bash theme={null}
Installed tools in /Users/you/.ironclaw/tools/:

  notion (240.0 KB, caps: ✓)
  github (180.5 KB, caps: ✓)
  weather (95.2 KB, caps: ✗)
```

**Verbose output:**

```bash theme={null}
Installed tools in /Users/you/.ironclaw/tools/:

  notion (240.0 KB)
    Path: /Users/you/.ironclaw/tools/notion.wasm
    Hash: a3f2e1d4c5b6a7f8
    Caps: yes
    Perms: http: api.notion.com, secrets: 1

  github (180.5 KB)
    Path: /Users/you/.ironclaw/tools/github.wasm
    Hash: b4e3d2c1a9f8e7d6
    Caps: yes
    Perms: http: api.github.com, secrets: 1

  weather (95.2 KB)
    Path: /Users/you/.ironclaw/tools/weather.wasm
    Hash: c5d4e3f2b1a0e9f8
    Caps: no
```

***

## ironclaw tool remove

Remove an installed tool.

### Syntax

```bash theme={null}
ironclaw tool remove <NAME> [FLAGS]
```

### Arguments

**`<NAME>`**

Name of the tool to remove.

### Flags

**`--dir, -d <PATH>`**

Directory to remove tool from.

* Default: `~/.ironclaw/tools/`

### Examples

```bash theme={null}
# Remove a tool
ironclaw tool remove mytool

# Remove from custom directory
ironclaw tool remove mytool --dir /opt/ironclaw/tools/
```

### Output

```bash theme={null}
Removed /Users/you/.ironclaw/tools/mytool.wasm
Removed /Users/you/.ironclaw/tools/mytool.capabilities.json

Tool 'mytool' removed.
```

***

## ironclaw tool info

Show detailed information about a tool.

### Syntax

```bash theme={null}
ironclaw tool info <NAME_OR_PATH> [FLAGS]
```

### Arguments

**`<NAME_OR_PATH>`**

Tool name or path to .wasm file.

### Flags

**`--dir, -d <PATH>`**

Directory to look for tool.

* Default: `~/.ironclaw/tools/`

### Examples

```bash theme={null}
# Show info by name
ironclaw tool info notion

# Show info for .wasm file
ironclaw tool info ~/downloads/tool.wasm

# Look in custom directory
ironclaw tool info mytool --dir /opt/ironclaw/tools/
```

### Output

```bash theme={null}
Tool: notion
Path: /Users/you/.ironclaw/tools/notion.wasm
Size: 245760 bytes (240.0 KB)
Hash: a3f2e1d4c5b6a7f8e9d0c1b2a3f4e5d6c7b8a9f0e1d2c3b4a5f6e7d8c9b0a1f2

Capabilities (/Users/you/.ironclaw/tools/notion.capabilities.json):
  HTTP:
    GET, POST api.notion.com /v1/*
  Credentials:
    notion_auth: notion_oauth_token -> Bearer header
  Rate limit: 60/min, 1000/hour
  Secrets (existence check only):
    notion_oauth_token
```

***

## ironclaw tool auth

Configure OAuth authentication for a tool.

### Syntax

```bash theme={null}
ironclaw tool auth <NAME> [FLAGS]
```

### Arguments

**`<NAME>`**

Name of the tool to authenticate.

### Flags

**`--dir, -d <PATH>`**

Directory containing the tool.

* Default: `~/.ironclaw/tools/`

**`--user, -u <USER_ID>`**

User ID for storing the secret.

* Default: `default`

### Examples

```bash theme={null}
# Authenticate with a tool
ironclaw tool auth notion

# Authenticate for specific user
ironclaw tool auth notion --user alice

# Tool in custom directory
ironclaw tool auth mytool --dir /opt/ironclaw/tools/
```

### Interactive Flow

The command checks for authentication configuration in the tool's capabilities file and initiates the appropriate flow:

#### OAuth Flow

```bash theme={null}
╔════════════════════════════════════════════════════════════════╗
║                    Notion Authentication                       ║
╚════════════════════════════════════════════════════════════════╝

  Starting OAuth authentication...

  Opening browser for Notion login...

  Waiting for authorization...

  Exchanging code for token...

  ✓ Notion connected!
    Workspace: My Workspace

  The tool can now access the API.
```

#### Manual Token Entry

```bash theme={null}
╔════════════════════════════════════════════════════════════════╗
║                    GitHub Authentication                       ║
╚════════════════════════════════════════════════════════════════╝

  Setup instructions:

    1. Go to https://github.com/settings/tokens
    2. Click "Generate new token (classic)"
    3. Select scopes: repo, read:org
    4. Copy the generated token

  Press Enter to open setup page (or 's' to skip): 

  Token format: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

  Paste your token: ****************************************

  Validating token... ✓

  ✓ GitHub connected!

  The tool can now access the API.
```

### Requirements

* Tool must have an `auth` section in its capabilities file
* Database must be available for storing secrets
* `SECRETS_MASTER_KEY` must be set

***

## ironclaw tool setup

Configure required secrets for a tool (from `setup.required_secrets` in capabilities).

### Syntax

```bash theme={null}
ironclaw tool setup <NAME> [FLAGS]
```

### Arguments

**`<NAME>`**

Name of the tool to set up.

### Flags

**`--dir, -d <PATH>`**

Directory containing the tool.

* Default: `~/.ironclaw/tools/`

**`--user, -u <USER_ID>`**

User ID for storing secrets.

* Default: `default`

### Examples

```bash theme={null}
# Set up required secrets
ironclaw tool setup mytool

# Setup for specific user
ironclaw tool setup mytool --user alice
```

### Interactive Flow

```bash theme={null}
╔════════════════════════════════════════════════════════════════╗
║                      MyTool Setup                              ║
╚════════════════════════════════════════════════════════════════╝

  API Key: ****************************************

    ✓ Saved.

  API Secret (optional, Enter to skip): 

    Skipped.

  ✓ MyTool setup complete!
```

## Capabilities File Format

Tools require a capabilities file defining their permissions:

```json theme={null}
{
  "http": {
    "allowlist": [
      {
        "host": "api.notion.com",
        "path_prefix": "/v1/",
        "methods": ["GET", "POST", "PATCH"]
      }
    ],
    "credentials": {
      "notion_auth": {
        "secret_name": "notion_oauth_token",
        "location": "bearer"
      }
    },
    "rate_limit": {
      "requests_per_minute": 60,
      "requests_per_hour": 1000
    }
  },
  "secrets": {
    "allowed_names": ["notion_oauth_token"]
  },
  "auth": {
    "secret_name": "notion_oauth_token",
    "display_name": "Notion",
    "provider": "notion",
    "oauth": {
      "client_id": "your-client-id",
      "authorization_url": "https://api.notion.com/v1/oauth/authorize",
      "token_url": "https://api.notion.com/v1/oauth/token",
      "scopes": [],
      "use_pkce": true
    }
  }
}
```

## Tool Permissions

Tools have zero permissions by default. The capabilities file grants:

* **HTTP access** - Specific hosts, paths, and methods
* **Secrets access** - Which secrets the tool can check existence of
* **Workspace access** - Read access to specific path prefixes
* **Tool invocation** - Call other tools (with aliases)

## Troubleshooting

### "No Cargo.toml found"

The path must point to a Rust WASM tool source directory:

```bash theme={null}
ls ~/my-tool/
# Should contain: Cargo.toml, src/, capabilities.json
```

### "No .wasm artifact found"

Build the tool first or remove `--skip-build`:

```bash theme={null}
cd ~/my-tool
cargo build --target wasm32-wasip1 --release
```

### "Tool already exists"

Use `--force` to overwrite:

```bash theme={null}
ironclaw tool install ~/my-tool/ --force
```

### "Invalid capabilities file"

Validate your JSON:

```bash theme={null}
jq . mytool.capabilities.json
```

### "SECRETS\_MASTER\_KEY not set"

Run onboarding or set the key manually:

```bash theme={null}
ironclaw onboard
# Or
export SECRETS_MASTER_KEY=<your-key>
```

## Related Commands

* [mcp](/cli/mcp) - Manage MCP servers (alternative to WASM tools)
* [onboard](/cli/onboard) - Initial setup including secrets key