alchemy-cli

Alchemy CLI（@alchemy/cli）是一个面向终端的命令行工具，用于进行实时区块链查询、管理操作和本地自动化。它把 Alchemy 的各类产品映射为 alchemy <command> 形式的命令，并输出结构化 JSON。

用途：适合在会话中直接进行的实时工作，例如链上数据查询、交易分析、管理操作或本地自动化。官方说明指出，CLI 是实时工作的首选本地运行路径；在 CLI 与 MCP 之间不确定时优先使用 CLI。它不用于编写生产应用代码，这类需求应交给 alchemy-api 或 agentic-gateway。

安装与初始化：安装命令为 npm i -g @alchemy/cli。会话开始时运行 alchemy --json --no-interactive agent-prompt，可获取完整的命令约定，包括命令、参数、认证方式和错误码。执行时应始终加上 --json --no-interactive：退出码为 0 时把 stdout 解析为 JSON，非 0 时把 stderr 解析为 JSON。首次执行命令前，运行 setup status 和 gas 两项预检；gas 是轻量 RPC 冒烟测试，可发现 setup status 误报完成但 RPC 仍返回 AUTH_REQUIRED 的情况；若出现该错误，可运行 alchemy auth login 或 alchemy config set api-key <key> 后重新验证。

认证方式：最快的方式是浏览器登录 alchemy auth login，它会自动配置凭据；也可通过 alchemy config set api-key、access-key、webhook-api-key 分别配置 API 密钥、访问密钥和 Webhook 密钥，或使用 x402 钱包认证（alchemy wallet generate 后执行 alchemy config set x402 true）。alchemy network list 与 alchemy version 无需认证。部分 apps 子命令依赖“默认应用”，遇到 APP_REQUIRED 时可执行 alchemy apps select <id>。密钥可在 dashboard.alchemy.com 获取。

主要能力：涵盖 EVM 节点查询（余额、交易、回执、区块、Gas、日志、原始 RPC、trace/debug）、数据查询（ERC-20 余额与元数据、授权额度、NFT 列表与元数据、转账历史、现货与历史价格、跨网络代币与 NFT 组合）、交易模拟（单笔或批量交易的资产变化与执行轨迹）、Solana RPC 与 DAS、Webhook 的增删改查、ERC-4337 账户抽象（发送 UserOperation、估算 Gas、获取回执、请求 Gas 与 Paymaster 数据及代币报价）、x402 钱包管理，以及 App 管理（列表、创建、更新网络、地址、来源和 IP 白名单、删除、选择默认应用）。

错误处理：错误以结构化 JSON 返回在 stderr 中，包含 code、exitCode、retryable 与恢复提示。例如 AUTH_REQUIRED、INVALID_API_KEY、APP_REQUIRED 不可重试，需要修正认证或配置；RATE_LIMITED 与 NETWORK_ERROR 可重试；PAYMENT_REQUIRED 需要为 x402 钱包充值或改用 API 密钥。

限制与注意：不要在不加 --json --no-interactive 的情况下裸跑 alchemy；当已有对应的 CLI 命令时，不要使用 curl 或原始 HTTP 请求；不要用 CLI 生成生产应用代码。如需提取 API 密钥供应用使用，可将密钥写入项目的 .env 并导出为 $ALCHEMY_API_KEY，但不得在对话输出中显示密钥值。