@agentutility/cli

Call agentutility's x402 endpoints from a terminal. The CLI creates a local EVM wallet, searches the live catalog, checks prices, and pays in USDC on Base.

Install

Install the agentutility command globally:

npm i -g @agentutility/cli
agentutility --help

Or run it without installing:

npx @agentutility/cli search web

30-second quickstart

# 1. Create a wallet.
agentutility wallet create

# 2. Send USDC on Base to the address it prints. You don't need ETH.
agentutility wallet status

# 3. Find an endpoint and inspect its input.
agentutility search cve security
agentutility price cve

# 4. Make the paid call.
agentutility call cve cve_id=CVE-2021-44228

Prices are per call. The payment uses gasless transferWithAuthorization, so the wallet only needs USDC on Base.

Commands

Create a wallet

agentutility wallet create
agentutility wallet create --force

The second form replaces the current wallet. Save its private key first if it still holds funds.

Check the wallet

agentutility wallet status

This prints the wallet address and its Base USDC balance.

Search the catalog

agentutility search browser screenshot
agentutility search translation

Search matches endpoint names, tags, and descriptions. Results are ranked by match score, then price.

Check a price and schema

agentutility price web-search

The output lists the endpoint's current price plus its required and optional input fields.

Call an endpoint

Pass fields as key=value pairs:

agentutility call web-search query="x402 protocol" limit=5

Numbers, booleans, null, arrays, and objects are parsed as JSON. Other values stay strings. You can also pass a JSON object:

agentutility call web-search --data '{"query":"x402 protocol","limit":5}'

Pairs override matching fields from --data:

agentutility call web-search limit=10 --data '{"query":"x402 protocol","limit":5}'

Use --raw to print the response body without JSON formatting. The default timeout is 120 seconds:

agentutility call image-generate prompt="a paper fox" --timeout 300 --raw

Calls priced above $0.25 require --yes. Confirmed calls use a $1.00 maximum by default, and --max-price lets you set a lower ceiling:

agentutility call image-generate prompt="a paper fox" --yes --max-price 0.50

An endpoint missing from the registry has an unknown price. In that case, you must pass both --yes and an explicit --max-price.

Wallet security

The generated key is stored at ~/.agentutility/wallet.json. The directory is mode 0700 and the file is mode 0600. Treat that file like cash: don't commit it, paste it into chat, or share it.

Set X402_PRIVATE_KEY to use an existing EVM key instead. It takes priority over the wallet file and accepts 64 hex characters with or without the 0x prefix. Load it from a permission-restricted file so the key doesn't land in shell history:

export X402_PRIVATE_KEY="$(< ~/.config/agentutility/private-key)"
agentutility wallet status
unset X402_PRIVATE_KEY

For a separate config location, set AGENTUTILITY_HOME.

Pricing and retries

Catalog prices range from $0.001 to $0.50 per call. The CLI stops before prices above $0.25 unless you pass --yes. A confirmed call has a $1.00 payment ceiling by default, enforced while the payment is signed. Lower it with --max-price:

agentutility call web-search query="x402 protocol" --yes --max-price 0.10

If the registry price is unknown, both flags are required. This includes calls made when the registry cache is more than 24 hours old and the live registry can't be reached:

agentutility call web-search query="x402 protocol" --yes --max-price 0.10

The CLI signs only Base USDC payments using EIP-3009, with a payment timeout of at most 10 minutes. --max-price is always a finite ceiling; it never permits an unlimited payment. Run agentutility price <slug> before spending.

A persistent 402 usually means the wallet is out of USDC. A 4xx after payment usually means the input doesn't match the endpoint schema. Paid POST requests aren't retried by the CLI after a timeout because the remote operation may already have completed.

Read the getting-started guide, the live agent skill, or the full registry.