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

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

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)

Data

Solana

Webhooks

Account abstraction (ERC-4337)

Wallet (x402)

App management

CLI admin

Global flags

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):

Get the full canonical list any time with alchemy --json --no-interactive agent-prompt.

Handing off to other skills

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