Alchemy CLI

Alchemy CLI is a command-line tool for querying blockchain data and managing Alchemy apps/configuration. It supports both human-friendly terminal output and JSON output for automation. You can use browser login, API keys, or x402 wallet auth depending on the command.

Capabilities At A Glance

Installation

Install globally from npm:

npm i -g @alchemy/cli

Or run without installing globally:

npx @alchemy/cli <command>

Shell Completions

Enable Tab completion for all commands and subcommands:

# zsh (add to ~/.zshrc)
echo 'eval "$(alchemy completions zsh)"' >> ~/.zshrc
source ~/.zshrc

# bash (add to ~/.bashrc)
echo 'eval "$(alchemy completions bash)"' >> ~/.bashrc
source ~/.bashrc

# fish
alchemy completions fish > ~/.config/fish/completions/alchemy.fish

Getting Started

Authentication Quick Start

Authentication is required before making requests. The recommended path is browser login:

alchemy auth

This opens a browser to link your Alchemy account, then prompts you to select an app. The selected app's API key is saved to your config automatically. Pass -y to skip the confirmation prompt.

If you run alchemy with no command and no auth configured, the CLI will guide you through browser login automatically.

If you have an auth token but haven't selected an app yet, the CLI will prompt you to pick one before running any command that requires an API key. Teams with many apps can type to search by name.

If you use Notify webhooks, add webhook auth on top via alchemy config set webhook-api-key <key>, --webhook-api-key on alchemy webhook commands, or ALCHEMY_WEBHOOK_API_KEY.

Usage By Workflow

After auth is configured, use the CLI differently depending on who is driving it:

• Humans (interactive terminal): start with alchemy and use the terminal UI/setup flow; this is the recommended path for human usage
• Agents/scripts (automation): use --json --no-interactive to guarantee JSON output and disable prompts (JSON is auto-enabled when piped, but --json is a safe default)

Quick usage examples:

# Human recommended entrypoint
alchemy

# Agent/script-friendly command
alchemy evm data balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 -n eth-mainnet --json --no-interactive

# Agent checks whether a newer CLI version is available
alchemy update-check --json --no-interactive

Agent bootstrap

Have your agent run agent-prompt as its first step to get a complete, machine-readable contract describing every command, auth method, error code, and execution rule:

# Agent runs this once to learn everything the CLI can do
alchemy --json --no-interactive agent-prompt

This returns a single JSON document with execution policy, runtime discovery instructions, preflight instructions, auth matrix, the full command tree with all arguments and options, error codes with recovery actions, and example invocations. No external docs required.

Agents can also call alchemy --json --no-interactive update-check to retrieve the current CLI version, latest known version, and install command for upgrades.

Command Reference

Run commands as alchemy <command>. Use alchemy help or alchemy help <command> for generated command help.

EVM

Wallets

alchemy wallet exposes a unified onchain-actions surface. The session wallet (Alchemy/Privy-managed, P-256 delegated signer) is the recommended flow; a local wallet (private key stored on disk) is supported as an alternative.

Per-command override: pass --signer <session\|local> to evm send, evm approve, evm swap, xchain bridge, or evm contract call to override the active signer for a single invocation.

Chains

x402

Non-interactive runs (including --json) require --max-payment, which acts as the payment authorization; payment signatures are verified locally to recover to the wallet address before being sent.

CLI Admin

Feedback

feedback submits product feedback for the authenticated Alchemy user/team. It uses browser-login auth and does not require a selected app or app API key.

alchemy feedback Love the new usage command
printf "Line one\nLine two\n" | alchemy feedback -

Usage API (alpha)

The usage commands are in alpha — the response shape may change, and access is limited to teams enrolled in the Usage API alpha.

Usage time-series ranges are limited by plan:

Hourly queries (--granularity hour) are limited to the last 7 days on every plan.

The CLI fetches the full requested range. The Usage API pages responses in 7-day chunks; the CLI follows those pages automatically.

alchemy --json usage summary
alchemy usage timeseries --start-date 2026-06-01 --granularity day

Flags

Global flags

These apply to all commands.

Auth & network

Output & formatting

Runtime & behavior

Referral

Additional env vars:

Command-specific flags

Authentication Reference

# Interactive login — opens browser to link your Alchemy account
alchemy auth

# Skip the confirmation prompt
alchemy auth -y

# Force re-authentication
alchemy auth login --force

# Check auth status
alchemy auth status

# Log out
alchemy auth logout

After login, the CLI prompts you to select a team, if you belong to more than one, and then an app. The app's API key is saved to config and used for all subsequent commands. If you skip app selection during login, the CLI will prompt you to pick one before running any command that needs an API key.

Notify/webhook commands use a webhook API key with resolution order: --webhook-api-key -> ALCHEMY_WEBHOOK_API_KEY -> ALCHEMY_NOTIFY_AUTH_TOKEN -> config webhook-api-key -> configured app webhook key.

Telemetry

This section describes the CLI's opt-out usage telemetry: what it covers, when you are told about it, and how to turn it off.

Collection is enabled by default. The opt-out controls below apply before any events are collected or sent.

What is collected: commands and setup steps, outcomes and timing, CLI version, Node major version, OS and environment (CI, terminal, JSON or REPL mode), network, flag names, referral source, and the detected AI tool and its version, when known.

Linked to: your Alchemy user and team IDs, your plan, and random install and per-run IDs.

Never collected: prompts, secrets, addresses, file paths, or argument values other than allowlisted network and referral labels.

When the notice appears: the first time telemetry would apply, the CLI shows a one-time notice describing the above.

• In a terminal: before the first command.
• In JSON mode (--json, or whenever stdout is piped): inside the error JSON as error.notice if the first command fails, otherwise as one JSON line on stderr after the result: {"notice": "..."}.
• Pre-parse failures and the --help / --version flags don't show it. Nothing from those runs is collected, and the notice appears on the next command.

Opting out:

alchemy telemetry disable           # persistent opt-out; deletes queued events
alchemy telemetry enable            # opt back in
alchemy telemetry status            # show the current state
export ALCHEMY_TELEMETRY_DISABLED=1 # or DO_NOT_TRACK=1, per shell or CI job

ALCHEMY_TELEMETRY_DISABLED and DO_NOT_TRACK turn telemetry off whenever they're set to a truthy value such as 1, regardless of the saved preference. Empty, 0, false, no and off don't count.

Where state lives: $XDG_CONFIG_HOME/alchemy/telemetry.json (default ~/.config/alchemy/telemetry.json), or next to the file named by ALCHEMY_CONFIG. It holds a random install ID, the on/off preference and the referral source. Whether the notice was shown is recorded separately in telemetry/notice-shown in the same directory.

Referral source: --ref <source> or ALCHEMY_REF is recorded once, when the telemetry state is first created, and ignored afterwards.

REPL Mode

Run alchemy with no command in an interactive terminal:

alchemy
alchemy ◆ evm data balance 0x...
alchemy ◆ evm block latest
alchemy ◆ exit

Use --no-interactive to disable REPL/prompts in automation.

Output Modes

• TTY (terminal): formatted human output (tables, colors, spinners)
• Non-TTY (piped/redirected): JSON output automatically — no flag needed
• --json: forces JSON output even in a terminal
• --verbose or alchemy config set verbose true: logs request/response details (method, URL, status, timing) to stderr

Error Format

Errors are structured JSON in JSON mode:

{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Not authenticated. Run 'alchemy auth' to log in, or set ALCHEMY_API_KEY.",
    "hint": "alchemy auth"
  }
}