Skip to main content

CLI Usage

The web3agent CLI has two main jobs: start the MCP server so AI hosts can connect, and let you call tools directly from the terminal without writing any code.

The CLI is the universal fallback. If your host can't consume MCP natively, or you want to test a tool before wiring it into your app, the CLI gets you there.

Installation

No global install required. Run directly with npx:

npx web3agent

Or install globally if you prefer:

npm install -g web3agent
web3agent --help

Check the version:

npx web3agent --version
# web3agent/0.4.0

Starting the MCP Server

npx web3agent

This starts the MCP proxy server on stdio. AI hosts (Claude Code, Cursor, Windsurf, OpenCode) connect to it via the MCP protocol. The server stays running until you kill it.

Environment variables control which chain and wallet it uses:

CHAIN_ID=8453 PRIVATE_KEY=0x... npx web3agent

Or put them in a .env file and the CLI picks them up automatically.

Initializing a Host Config

npx web3agent init

This auto-detects which AI host you're using and writes the correct MCP config file. For Claude Code, it writes to ~/.claude/claude_desktop_config.json. For Cursor, it writes to .cursor/mcp.json in the current directory.

You can also target a specific host:

npx web3agent init --host claude
npx web3agent init --host cursor
npx web3agent init --host windsurf

After running init, restart your AI host and the web3agent tools will appear.

Scaffolding a New Project

npx web3agent create

Interactive scaffolding that sets up a new project with web3agent pre-configured. Prompts for project name, chain, and which integrations to enable.

Working with Tools

List all tools

npx web3agent tools list

With --json for machine-readable output:

npx web3agent tools list --json

[
  { "name": "resolve_token", "description": "Resolve a token symbol or address", "riskLevel": "safe" },
  { "name": "orbs_swap", "description": "Execute a Liquidity Hub swap", "riskLevel": "financial" },
  ...
]

Describe a tool

npx web3agent tools describe resolve_token

Shows the tool's description, input schema, and risk level. Useful for understanding what parameters a tool expects before calling it.

npx web3agent tools describe resolve_token --json

Call a tool

npx web3agent tool call server_status --input '{}'

The --input flag takes a JSON string matching the tool's input schema. Use --json to get structured output:

npx web3agent tool call resolve_token \
  --input '{"symbol":"USDC","chainId":8453}' \
  --json

{
  "ok": true,
  "data": {
    "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "decimals": 6,
    "symbol": "USDC"
  }
}

Diagnostics

npx web3agent doctor

Runs a health check and reports:

  • Node.js version compatibility
  • Environment variable status (which are set, which are missing)
  • Wallet configuration (address if configured)
  • Integration connectivity (Orbs, LI.FI, Blockscout)
  • Policy engine status
npx web3agent doctor --json

{
  "nodeVersion": "22.4.0",
  "compatible": true,
  "wallet": { "configured": true, "address": "0x..." },
  "integrations": {
    "orbs": "healthy",
    "lifi": "healthy",
    "blockscout": "healthy"
  },
  "policy": { "enabled": false }
}

Run doctor first when something isn't working. It surfaces missing env vars and connectivity issues before you spend time debugging tool calls.

Write Operations and Confirmation

By default, write operations (swaps, bridges, contract calls) require confirmation before executing. This is controlled by the CONFIRM_WRITES environment variable (default: true).

First safe write flow

  1. Call the write tool. It queues the operation and returns a pending ID:
npx web3agent tool call lifi_execute_bridge \
  --input '{
    "fromChainId": 1,
    "toChainId": 8453,
    "fromToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "toToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "fromAmount": "100000000",
    "userAddress": "0x..."
  }' \
  --json

{
  "ok": true,
  "data": {
    "status": "pending_confirmation",
    "id": "conf_abc123",
    "description": "Bridge 100 USDC from Ethereum to Base via LI.FI",
    "estimatedGasUsd": "4.20"
  }
}
  1. Review the details, then confirm:
npx web3agent tool call transaction_confirm \
  --input '{"id":"conf_abc123"}' \
  --json

{
  "ok": true,
  "data": {
    "txHash": "0x...",
    "status": "submitted"
  }
}

To skip confirmation for automated scripts, set CONFIRM_WRITES=false in your environment.

Policy Management

The policy engine enforces per-transaction and daily USD spend limits. Manage it with the policy subcommand.

# Show current policy
npx web3agent policy

# Set a per-transaction limit
npx web3agent policy set --max-single-tx-usd 500

# Set a daily limit
npx web3agent policy set --max-daily-usd 2000

# Enable the policy engine
npx web3agent policy enable

# Disable it
npx web3agent policy disable

# Show today's spend
npx web3agent policy status

Policy state persists across CLI invocations. The limits apply to all write operations, including swaps, bridges, and contract calls.

Practical Examples

Check your wallet balance

PRIVATE_KEY=0x... npx web3agent tool call evm_get_balance \
  --input '{"chainId":8453}' \
  --json

Get a swap quote

npx web3agent tool call orbs_quote \
  --input '{
    "fromToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "toToken": "0x4200000000000000000000000000000000000006",
    "fromAmount": "10000000",
    "chainId": 8453
  }' \
  --json

Look up a transaction

npx web3agent tool call blockscout_get_transaction \
  --input '{
    "txHash": "0x...",
    "chainId": 8453
  }' \
  --json

Check server status

npx web3agent tool call server_status --input '{}' --json

Help

Every command has a --help flag:

npx web3agent --help
npx web3agent tools --help
npx web3agent tool call --help
npx web3agent policy --help

The help output lists all flags and shows example usage.