alchemy-cli

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>
# or equivalently
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.

# 1. Try to read a cached key from CLI config (read-only, safe non-interactive).
KEY="$(alchemy --no-interactive --json --reveal config get api-key 2>/dev/null | jq -r .value)"

# 2. If empty/null, run the interactive flow.
#    Note: auth login opens a browser and apps select shows a picker, so do NOT
#    pass --no-interactive here. If you already know the app id, pass it
#    explicitly to skip the picker: `alchemy --no-interactive --json apps select <id>`.
if [ -z "$KEY" ] || [ "$KEY" = "null" ]; then
  alchemy auth login              # opens browser; sets up account credentials
  alchemy --json apps select      # interactive picker (omit --no-interactive so it can render)
  KEY="$(alchemy --no-interactive --json --reveal config get api-key | jq -r .value)"
fi

# 3. Persist to the project's .env (standard practice — survives terminal restarts
#    and gets loaded by dotenv / framework env loaders at runtime).
#    Use .env.local if the project's framework expects that (e.g. Next.js).
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

# 4. Export to the current shell so the agent can call the API immediately.
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

• CLI on npm
• Alchemy docs
• Get API key