How do I install the Blockrun CLI skill?

Run npx skillmds@latest add blockrunai/blockrun-cli in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Blockrun CLI safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Blockrun CLI?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Blockrun CLI free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Blockrun CLI?

BlockRunAI (@blockrunai) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Blockrun CLI by blockrunai — Agent Skill

Name: Blockrun CLI
Author: BlockRunAI

Blockrun CLI

Use the `blockrun` CLI to pay-per-request AI (chat/image/video/music/speech), live data (web/X search, prediction markets, Pyth prices, 40+ chain RPC), and any x402-paid endpoint — all billed from a local USDC wallet, no API keys. Use when the user asks to run a model, generate media, query crypto/prediction/web data, pay a 402 resource, check wallet balance or spend, or manage BlockRun sub-products (route/agent/mcp/codex).

BlockRunAI 6e7c680 3.5 KB Updated Sep 17, 2026

File contents

BlockRun CLI

One entry point for every BlockRun product. Wallet lives at ~/.blockrun/.session; every command bills USDC from it via x402 on Base. No API keys, no accounts.

Contract (parse this, not the prose)

Always pass --json. Every command returns one line:

{"ok":true,"data":...,"meta":{"cost":0.001,"chain":"eip155:8453"}}
{"ok":false,"error":{"type":"payment-cap","code":402,"message":"..."}}

Check ok, not the exit code alone (exit is 0/1 to match). meta.cost is the USD actually paid.

Money safety (important)

--quote on api/pay prices a call WITHOUT paying. Quote first when cost is unknown.
Payments above $1 are refused unless --max <usd> raises the cap. Do not raise it without the user's ask.
blockrun spend shows real ledger totals (today/month/all). blockrun limits shows the user's guardrails — never work around a payment-cap or policy denial; surface it.

Commands

# wallet & status
blockrun --json status | balance | doctor | fund
blockrun wallet import --stdin [--force]  # pipe the key on stdin; never put it in argv
blockrun wallet create|export --yes|recover
blockrun chain base|sol · config list|get|set

# inference
blockrun --json run <model> "<prompt>"          # one-shot; free models: nvidia/*
blockrun --json models --free                   # catalog + pricing
blockrun chat --model <m>                       # interactive REPL

# multimodal (paid; URLs in data.urls; --out saves file)
blockrun --json image "<prompt>" --size 1024x1024 --out img.png
blockrun --json image edit <url> "<prompt>"
blockrun --json video "<prompt>" --duration 5 · music "<prompt>" · speech "<text>" --voice <v>
blockrun --json realface enroll <https-image-url> --name <n>

# data
blockrun --json search "<q>"                    # Grok live web/X
blockrun --json research "<q>" --path answer    # Exa
blockrun --json predict polymarket/events --limit 5
blockrun --json crypto <surf-path> · price BTC · rpc base eth_blockNumber
blockrun --json discover                        # x402 service catalog (free)

# generic x402 (ANY paid endpoint)
blockrun --json api POST v1/chat/completions --data '{...}' --quote   # price it
blockrun --json api POST v1/chat/completions --data '{...}'          # pay ≤$1
blockrun --json pay <url> --method GET --max 2                       # raise cap explicitly

# guardrails & spend
blockrun --json limits set --per-call 0.5 --daily 20
blockrun --json limits allow chat,data · limits deny video
blockrun --json policy show · spend today

# sub-products (independently installed, args forwarded)
blockrun route|agent|mcp|codex|phone|share ...  # missing → blockrun ext install <name>

Recipes

"what would this cost?" → blockrun --json api POST <path> --data '...' --quote → report data.quote.amountUsdc.
cheapest capable chat → blockrun --json run nvidia/deepseek-v4-flash "..." (free) before reaching for paid models.
balance check before a batch of paid calls: blockrun --json balance; if low, blockrun --json fund and show the user data.address.

---name: blockrun-clidescription: Use the `blockrun` CLI to pay-per-request AI (chat/image/video/music/speech), live data (web/X search, prediction markets, Pyth prices, 40+ chain RPC), and any x402-paid endpoint — all billed from a local USDC wallet, no API keys. Use when the user asks to run a model, generate media, query crypto/prediction/web data, pay a 402 resource, check wallet balance or spend, or manage BlockRun sub-products (route/agent/mcp/codex).---# BlockRun CLIOne entry point for every BlockRun product. Wallet lives at `~/.blockrun/.session`; every command bills USDC from it via x402 on Base. No API keys, no accounts.## Contract (parse this, not the prose)Always pass `--json`. Every command returns one line:```json{"ok":true,"data":...,"meta":{"cost":0.001,"chain":"eip155:8453"}}{"ok":false,"error":{"type":"payment-cap","code":402,"message":"..."}}```Check `ok`, not the exit code alone (exit is 0/1 to match). `meta.cost` is the USD actually paid.## Money safety (important)- `--quote` on `api`/`pay` prices a call WITHOUT paying. Quote first when cost is unknown.- Payments above $1 are refused unless `--max <usd>` raises the cap. Do not raise it without the user's ask.- `blockrun spend` shows real ledger totals (today/month/all). `blockrun limits` shows the user's guardrails — never work around a `payment-cap` or policy denial; surface it.## Commands```bash# wallet & statusblockrun --json status | balance | doctor | fundblockrun wallet import --stdin [--force] # pipe the key on stdin; never put it in argvblockrun wallet create|export --yes|recoverblockrun chain base|sol · config list|get|set# inferenceblockrun --json run <model> "<prompt>" # one-shot; free models: nvidia/*blockrun --json models --free # catalog + pricingblockrun chat --model <m> # interactive REPL# multimodal (paid; URLs in data.urls; --out saves file)blockrun --json image "<prompt>" --size 1024x1024 --out img.pngblockrun --json image edit <url> "<prompt>"blockrun --json video "<prompt>" --duration 5 · music "<prompt>" · speech "<text>" --voice <v>blockrun --json realface enroll <https-image-url> --name <n># datablockrun --json search "<q>" # Grok live web/Xblockrun --json research "<q>" --path answer # Exablockrun --json predict polymarket/events --limit 5blockrun --json crypto <surf-path> · price BTC · rpc base eth_blockNumberblockrun --json discover # x402 service catalog (free)# generic x402 (ANY paid endpoint)blockrun --json api POST v1/chat/completions --data '{...}' --quote # price itblockrun --json api POST v1/chat/completions --data '{...}' # pay ≤$1blockrun --json pay <url> --method GET --max 2 # raise cap explicitly# guardrails & spendblockrun --json limits set --per-call 0.5 --daily 20blockrun --json limits allow chat,data · limits deny videoblockrun --json policy show · spend today# sub-products (independently installed, args forwarded)blockrun route|agent|mcp|codex|phone|share ... # missing → blockrun ext install <name>```## Recipes- "what would this cost?" → `blockrun --json api POST <path> --data '...' --quote` → report `data.quote.amountUsdc`.- cheapest capable chat → `blockrun --json run nvidia/deepseek-v4-flash "..."` (free) before reaching for paid models.- balance check before a batch of paid calls: `blockrun --json balance`; if low, `blockrun --json fund` and show the user `data.address`.

Frequently asked questions