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

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

# 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

# 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

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

# Use pre-built .wasm from target directory
ironclaw tool install ~/my-tool/ --skip-build

Output

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

ironclaw tool list [FLAGS]

Flags

--dir, -d <PATH> Directory to list tools from.

Default: ~/.ironclaw/tools/

--verbose, -v Show detailed information.

Examples

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

Installed tools in /Users/you/.ironclaw/tools/:

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

Verbose output:

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

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

# Remove a tool
ironclaw tool remove mytool

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

Output

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

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

# 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

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

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

# 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

╔════════════════════════════════════════════════════════════════╗
║                    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

╔════════════════════════════════════════════════════════════════╗
║                    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

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

# Set up required secrets
ironclaw tool setup mytool

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

Interactive Flow

╔════════════════════════════════════════════════════════════════╗
║                      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:

{
  "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:

ls ~/my-tool/
# Should contain: Cargo.toml, src/, capabilities.json

“No .wasm artifact found”

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

cd ~/my-tool
cargo build --target wasm32-wasip1 --release

“Tool already exists”

Use --force to overwrite:

ironclaw tool install ~/my-tool/ --force

“Invalid capabilities file”

Validate your JSON:

jq . mytool.capabilities.json

“SECRETS_MASTER_KEY not set”

Run onboarding or set the key manually:

ironclaw onboard
# Or
export SECRETS_MASTER_KEY=<your-key>

mcp - Manage MCP servers (alternative to WASM tools)
onboard - Initial setup including secrets key

​ironclaw tool

​Subcommands

​ironclaw tool install

​Syntax

​Arguments

​Flags

​Examples

​Install from Source Directory

​Install from .wasm File

​Install with Capabilities

​Skip Build (Use Existing)

​Output

​ironclaw tool list

​Syntax

​Flags

​Examples

​Output

​ironclaw tool remove

​Syntax

​Arguments

​Flags

​Examples

​Output

​ironclaw tool info

​Syntax

​Arguments

​Flags

​Examples

​Output

​ironclaw tool auth

​Syntax

​Arguments

​Flags

​Examples

​Interactive Flow

​OAuth Flow

​Manual Token Entry

​Requirements

​ironclaw tool setup

​Syntax

​Arguments

​Flags

​Examples

​Interactive Flow

​Capabilities File Format

​Tool Permissions

​Troubleshooting

​”No Cargo.toml found”

​“No .wasm artifact found”

​“Tool already exists”

​“Invalid capabilities file”

​“SECRETS_MASTER_KEY not set”

​Related Commands

ironclaw tool

Subcommands

ironclaw tool install

Syntax

Arguments

Flags

Examples

Install from Source Directory

Install from .wasm File

Install with Capabilities

Skip Build (Use Existing)

Output

ironclaw tool list

Syntax

Flags

Examples

Output

ironclaw tool remove

Syntax

Arguments

Flags

Examples

Output

ironclaw tool info

Syntax

Arguments

Flags

Examples

Output

ironclaw tool auth

Syntax

Arguments

Flags

Examples

Interactive Flow

OAuth Flow

Manual Token Entry

Requirements

ironclaw tool setup

Syntax

Arguments

Flags

Examples

Interactive Flow

Capabilities File Format

Tool Permissions

Troubleshooting

”No Cargo.toml found”

“No .wasm artifact found”

“Tool already exists”

“Invalid capabilities file”

“SECRETS_MASTER_KEY not set”

Related Commands