| name | alchemy-cli |
| description | Use the Alchemy CLI (`@alchemy/cli`) for live blockchain data, transaction lookups, NFT/token/portfolio queries, simulation, tracing/debugging, account abstraction (bundler + gas manager), webhook management, Solana RPC/DAS, and Alchemy app administration. Preferred runtime path for live agent work (querying, admin, local automation) when the CLI is installed locally — or when both CLI and MCP are available. If neither is installed, install the CLI with `npm i -g @alchemy/cli`. Use for live agent work in this session, not for building application code that ships to production. For application code, use the `alchemy-api` skill (with API key) or `agentic-gateway` skill (without). |
| license | MIT |
| compatibility | Requires `@alchemy/cli` (`npm i -g @alchemy/cli`) and shell access. Verified against `@alchemy/cli` 0.6.x. Works across Claude Code, Cursor, Codex, and any agent with shell access. |
| metadata | {"author":"alchemyplatform","version":"2.0"} |
Alchemy CLI
Use the 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)
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
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):
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:
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:
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:
alchemy --json --no-interactive apps select <id>
alchemy --json --no-interactive config set app <id>
Get API/access keys at 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) |
--access-key <key> | Override access key per command (env: ALCHEMY_ACCESS_KEY) |
--x402 | Use x402 wallet-based gateway auth for this command |
--wallet-key-file <path> | Path to wallet private key file (for x402) |
--timeout <ms> | Request timeout in milliseconds |
-q, --quiet | Suppress non-essential output |
--verbose | Log request/response details to stderr |
--debug | Enable debug diagnostics |
--no-color | Disable color output |
--reveal | Show secrets in plain text (use with care; intended for explicit reveal flows) |
Error handling
Errors return structured JSON on stderr. Each error has a code, an exitCode (1–9), a retryable boolean, and a recovery hint. Key codes (from agent-prompt):
| Code | Exit | Retryable | Recovery |
|---|
AUTH_REQUIRED | 3 | No | Run alchemy auth login, or set ALCHEMY_API_KEY / alchemy config set api-key <key> |
INVALID_API_KEY | 3 | No | Check the API key; set a valid one with alchemy config set api-key <key> |
ACCESS_KEY_REQUIRED | 3 | No | Set ALCHEMY_ACCESS_KEY or run alchemy config set access-key <key> |
INVALID_ACCESS_KEY | 3 | No | Check the access key at dashboard.alchemy.com |
APP_REQUIRED | 3 | No | Select a default app: alchemy apps select <id> (or alchemy config set app <id>) |
NETWORK_NOT_ENABLED | 3 | No | Enable the target network for your app at dashboard.alchemy.com |
SETUP_REQUIRED | 3 | No | Run alchemy --json setup status and follow nextCommands |
PAYMENT_REQUIRED | 9 | No | Fund x402 wallet or switch to API key auth |
RATE_LIMITED | 5 | Yes | Wait and retry with backoff; consider upgrading your plan |
NETWORK_ERROR | 6 | Yes | Check connection and retry |
RPC_ERROR | 7 | No | Check method, params, and network; verify API key has access |
ADMIN_API_ERROR | 8 | No | Check error message; verify access key permissions |
NOT_FOUND | 4 | No | Verify the resource identifier (address, hash, id) is correct |
INVALID_ARGS | 2 | No | Check command usage via alchemy --json help <command> |
INTERNAL_ERROR | 1 | No | Unexpected error; retry or report a bug |
Get the full canonical list any time with alchemy --json --no-interactive agent-prompt.
Handing off to other skills
| The user wants to... | Hand off to |
|---|
| Wire Alchemy into application code that ships to production, with an API key | alchemy-api |
| Wire Alchemy into application code without an API key, or pay-per-request as an autonomous agent | agentic-gateway |
| Run live work but the CLI isn't installed and they prefer not to install it (MCP is wired in) | alchemy-mcp |
Bridging into the alchemy-api flow (extract an API key)
If the user is starting an app-code project and $ALCHEMY_API_KEY isn't set in their shell, use the CLI to fetch a key from their Alchemy account, persist it to the project's .env so it survives across terminal sessions, and export it for the current shell so the agent can use it immediately.
Security: NEVER echo, print, or otherwise surface the extracted API key value in conversation output. Refer to it only as $ALCHEMY_API_KEY after exporting. Treat it the same as a password.
KEY="$(alchemy --no-interactive --json --reveal config get api-key 2>/dev/null | jq -r .value)"
if [ -z "$KEY" ] || [ "$KEY" = "null" ]; then
alchemy auth login
alchemy --json apps select
KEY="$(alchemy --no-interactive --json --reveal config get api-key | jq -r .value)"
fi
ENV_FILE=".env"
touch "$ENV_FILE"
if grep -q '^ALCHEMY_API_KEY=' "$ENV_FILE"; then
sed -i.bak "s|^ALCHEMY_API_KEY=.*|ALCHEMY_API_KEY=$KEY|" "$ENV_FILE" && rm "$ENV_FILE.bak"
else
echo "ALCHEMY_API_KEY=$KEY" >> "$ENV_FILE"
fi
grep -qxF "$ENV_FILE" .gitignore 2>/dev/null || echo "$ENV_FILE" >> .gitignore
export ALCHEMY_API_KEY="$KEY"
Hand off to the alchemy-api skill once .env has the key and ALCHEMY_API_KEY is exported.
Official links
