alchemy-cli

# Alchemy CLI Use the [Alchemy CLI](https://www.npmjs.com/package/@alchemy/cli) (`@alchemy/cli`) for live blockchain queries, admin work, and local automation from the terminal. The CLI maps every Alchemy product (Node JSON-RPC, Token, NFT, Transfers, Prices, Portfolio, Simulation, Solana, Webhooks, Apps) to `alchemy <command>` invocations with structured JSON output. ## When to use this skill Use `alchemy-cli` when **all** of the following are true: - The user wants **live agent work** — live querying, analysis, admin work, or local automation that the agent runs now in this session - `@alchemy/cli` is installed locally, **or** both the CLI and an MCP server are available, **or** neither is available (in which case install the CLI — see [Install](#install)) The CLI is the **preferred local fallback runtime path** for live agent work. When in doubt about CLI vs MCP, prefer the CLI. ## When to use a different skill | Situation | Use this skill instead | | --- | --- | | MCP is already wired into your client and the CLI is **not** installed locally | `alchemy-mcp` | | Building application code that runs outside this agent session, with an Alchemy API key | `alchemy-api` | | Building application code without an API key, or as an autonomous agent that needs to pay for itself, or you explicitly want x402/MPP | `agentic-gateway` | Do **not** use this skill to write production application code — CLI commands are for live agent work, not for embedding into shipped software. ## Install ```bash npm i -g @alchemy/cli ``` If the CLI is not installed and the user wants live agent work, install it. Do not fall back to raw curl/HTTP calls — those are the API-key path covered by `alchemy-api`. ## Bootstrap Run this at the start of any session to get the full command contract (every command, flag, auth method, error code, and example): ```bash alchemy --json --no-interactive agent-prompt ``` ## Execution rules - ALWAYS pass `--json --no-interactive` on every command - Parse stdout as JSON on exit code 0 - Parse stderr as JSON on nonzero exit code - NEVER run bare `alchemy` without `--json --no-interactive` - NEVER use curl or raw HTTP when an `alchemy` CLI command exists for the task — that's the `alchemy-api` (API-key) path, not this skill - NEVER use the CLI to generate production application code; hand off to `alchemy-api` or `agentic-gateway` for shipped code ## Preflight Before the first command, run **both** of these checks: ```bash alchemy --json --no-interactive setup status alchemy --json --no-interactive gas ``` `setup status` returns `{"complete": true, "satisfiedBy": "<source>"}` if any auth is configured. **Do not rely on `complete: true` alone** — there is a known false positive where `setup status` reports `complete: true` with `satisfiedBy: "auth_token"`, but RPC commands still fail with `AUTH_REQUIRED` because no API key has been derived from the auth token. `gas` is a lightweight RPC smoke test that catches this. If it returns `{"gasPrice": "0x...", ...}`, RPC is wired up correctly. If it returns `{"error": {"code": "AUTH_REQUIRED", ...}}`, run `alchemy auth login` (which fetches and saves the API key) or `alchemy config set api-key <key>`, then re-run `gas` to confirm. If `setup status` reports `complete: false`, follow the `nextCommands` in the response first, then run `gas` to verify. ## Auth setup The fastest way to authenticate is via browser login: ```bash alchemy auth login ``` This opens a browser to authenticate with your Alchemy account and automatically configures the CLI with your credentials. To check auth status: `alchemy auth status` To log out: `alchemy auth logout` ### Alternative auth methods | Method | Config command | Env var | Used by | |--------|---------------|---------|---------| | Browser login | `alchemy auth login` | -- | All commands (derives API key + access key from your account) | | API key | `alchemy config set api-key <key>` | `ALCHEMY_API_KEY` | `balance`, `tx`, `receipt`, `block`, `gas`, `logs`, `rpc`, `trace`, `debug`, `tokens`, `nfts`, `transfers`, `prices`, `portfolio`, `simulate`, `bundler`, `gas-manager`, `solana` | | Access key | `alchemy config set access-key <key>` | `ALCHEMY_ACCESS_KEY` | `apps` (all subcommands incl. `configured-networks`) | | Webhook key | `alchemy config set webhook-api-key <key>` | `ALCHEMY_WEBHOOK_API_KEY` | `webhooks` | | x402 wallet | `alchemy wallet generate` then `alchemy config set x402 true` | `ALCHEMY_WALLET_KEY` | `balance`, `tx`, `block`, `rpc`, `trace`, `debug`, `tokens`, `nfts`, `transfers` | `alchemy network list` and `alchemy version` / `update-check` need no auth. ### Selecting a default app Many `apps` subcommands (and the access-key gated flows) operate on a "default app." If you see `APP_REQUIRED` in an error response, set one: ```bash alchemy --json --no-interactive apps select <id> # or equivalently alchemy --json --no-interactive config set app <id> ``` Get API/access keys at [dashboard.alchemy.com](https://dashboard.alchemy.com/). ## Task-to-command map ### Node (EVM) | Task | Command | |------|---------| | ETH balance | `alchemy balance <address>` | | Transaction details | `alchemy tx <hash>` | | Transaction receipt | `alchemy receipt <hash>` | | Block details | `alchemy block <number\|latest>` | | Gas prices | `alchemy gas` | | Event logs | `alchemy logs --address <addr> --from-block <n> --to-block <n>` | | Raw JSON-RPC | `alchemy rpc <method> [params...]` | | Trace methods | `alchemy trace <method> [params...]` | | Debug methods | `alchemy debug <method> [params...]` | ### Data | Task | Command | |------|---------| | ERC-20 balances | `alchemy tokens balances <address>` | | ERC-20 balances (formatted) | `alchemy tokens balances <address> --metadata` | | Token metadata | `alchemy tokens metadata <contract>` | | Token allowance | `alchemy tokens allowance --owner <addr> --spender <addr> --contract <addr>` | | List owned NFTs | `alchemy nfts <address> [--limit <n>] [--page-key <key>]` | | NFT metadata | `alchemy nfts metadata --contract <addr> --token-id <id>` | | NFT contract metadata | `alchemy nfts contract <address>` | | Transfer history | `alchemy transfers <address> --category erc20,erc721,erc1155,external,internal,specialnft [--from-block <n>] [--to-block <n>] [--max-count <n>] [--page-key <key>]` | | Spot prices by symbol | `alchemy prices symbol ETH,USDC` | | Spot prices by address | `alchemy prices address --addresses '<json>'` | | Historical prices | `alchemy prices historical --body '<json>'` | | Cross-network token portfolio | `alchemy portfolio tokens --body '<json>'` | | Token balances by address/network pairs | `alchemy portfolio token-balances --body '<json>'` | | Cross-network NFT portfolio | `alchemy portfolio nfts --body '<json>'` | | NFT contracts by address/network pairs | `alchemy portfolio nft-contracts --body '<json>'` | | Simulate single tx (asset deltas) | `alchemy simulate asset-changes --tx '<json>' [--block-tag <tag>]` | | Simulate single tx (execution trace) | `alchemy simulate execution --tx '<json>' [--block-tag <tag>]` | | Simulate bundle (asset deltas) | `alchemy simulate asset-changes-bundle --txs '<json-array>' [--block-tag <tag>]` | | Simulate bundle (execution trace) | `alchemy simulate execution-bundle --txs '<json-array>' [--block-tag <tag>]` | ### Solana | Task | Command | |------|---------| | Solana JSON-RPC | `alchemy solana rpc <method> [params...]` | | Solana DAS (NFTs/assets) | `alchemy solana das <method> '<json>'` | ### Webhooks | Task | Command | |------|---------| | List webhooks | `alchemy webhooks list` | | Create webhook | `alchemy webhooks create --body '<json>' [--dry-run]` | | Update webhook | `alchemy webhooks update --body '<json>' [--dry-run]` | | Delete webhook | `alchemy webhooks delete <id> [--yes] [--dry-run]` | | Get address-activity webhook addresses | `alchemy webhooks addresses <id>` | | Get NFT-activity webhook filters | `alchemy webhooks nft-filters <id>` | ### Account abstraction (ERC-4337) | Task | Command | |------|---------| | Send a UserOperation | `alchemy bundler send-user-operation --user-op '<json>' --entry-point <addr>` | | Estimate UserOperation gas | `alchemy bundler estimate-user-operation-gas --user-op '<json>' --entry-point <addr> [--state-override '<json>']` | | Get UserOperation receipt | `alchemy bundler get-user-operation-receipt --user-op-hash <hash>` | | Request gas + paymaster data | `alchemy gas-manager request-gas-and-paymaster --body '<json>'` | | Request paymaster token quote | `alchemy gas-manager request-paymaster-token-quote --body '<json>'` | ### Wallet (x402) | Task | Command | |------|---------| | Generate a new wallet | `alchemy wallet generate` | | Import a wallet from a key file | `alchemy wallet import <path>` | | Show the locally configured wallet address | `alchemy wallet address` | ### App management | Task | Command | |------|---------| | List apps | `alchemy apps list [--cursor <c>] [--limit <n>] [--all] [--search <q>] [--id <appId>]` | | Get app details | `alchemy apps get <id>` | | Create app | `alchemy apps create --name "My App" --networks eth-mainnet [--description <desc>] [--products <ids>] [--dry-run]` | | Update app metadata | `alchemy apps update <id> --name "New Name" [--description <desc>] [--dry-run]` | | Update app network allowlist | `alchemy apps networks <id> --networks eth-mainnet,base-mainnet [--dry-run]` | | Update app address allowlist | `alchemy apps address-allowlist <id> --addresses 0xAA,0xBB [--dry-run]` | | Update app origin allowlist | `alchemy apps origin-allowlist <id> --origins https://a.com,https://b.com [--dry-run]` | | Update app IP allowlist | `alchemy apps ip-allowlist <id> --ips 1.2.3.4,5.6.7.8 [--dry-run]` | | Delete app | `alchemy apps delete <id> [--yes] [--dry-run]` | | Select default app | `alchemy apps select <id>` (equivalent to `alchemy config set app <id>`) | | List networks configured for an app | `alchemy apps configured-networks [--app-id <id>]` | | List Admin API chain identifiers (for `apps create`/`update`) | `alchemy apps chains` | | List all RPC network slugs (for `--network`) | `alchemy network list [--mainnet-only] [--testnet-only] [--search <term>]` | ### CLI admin | Task | Command | |------|---------| | Check for CLI updates | `alchemy update-check` | | View config | `alchemy config list` | | Reset config | `alchemy config reset --yes` | | CLI version | `alchemy version` | ## Global flags | Flag | Description | |------|-------------| | `--json` | Force JSON output (auto-enabled when piped) | | `--no-interactive` | Disable prompts and REPL | | `-n, --network <network>` | Target network (default: `eth-mainnet`, env: `ALCHEMY_NETWORK`) | | `--api-key <key>` | Override API key per command (env: `ALCHEMY_API_KEY`) |