Alchemy CLI

Utilisez la Alchemy CLI (@alchemy/cli) pour des requêtes blockchain en direct, des tâches d'administration et de l'automation locale depuis le terminal. La CLI mappe chaque produit Alchemy (Node JSON-RPC, Token, NFT, Transfers, Prices, Portfolio, Simulation, Solana, Webhooks, Apps) à des invocations alchemy <command> avec sortie JSON structurée.

Quand utiliser cette skill (scope_in)

Utilisez alchemy-cli quand tous les critères suivants sont vrais :

• L'utilisateur veut du travail agent en direct — requêtes en direct, analyse, tâches d'administration ou automation locale que l'agent exécute maintenant dans cette session
• @alchemy/cli est installé localement, ou la CLI et un serveur MCP sont disponibles, ou aucun n'est disponible (auquel cas installez la CLI — voir Install)

La CLI est le chemin d'exécution local de secours préféré pour le travail agent en direct. En cas de doute entre CLI et MCP, préférez la CLI.

Quand NE PAS utiliser cette skill (scope_out, handoff)

Ne pas utiliser cette skill pour écrire du code applicatif de production — les commandes CLI sont pour le travail agent en direct, pas pour être embarquées dans un logiciel livré.

Install

npm i -g @alchemy/cli

Si la CLI n'est pas installée et que l'utilisateur veut du travail agent en direct, installez-la. Ne revenez pas à des appels curl/HTTP bruts — ce chemin est couvert par alchemy-api.

Bootstrap

Exécutez ceci au début de chaque session pour obtenir le contrat de commande complet (chaque commande, flag, méthode d'authentification, code d'erreur et exemple) :

alchemy --json --no-interactive agent-prompt

Règles d'exécution

• TOUJOURS passer --json --no-interactive sur chaque commande
• Parser stdout en JSON sur le code de sortie 0
• Parser stderr en JSON sur un code de sortie non zéro
• NE JAMAIS exécuter alchemy seul sans --json --no-interactive
• NE JAMAIS utiliser curl ou HTTP brut quand une commande alchemy CLI existe pour la tâche — c'est le chemin alchemy-api (clé API), pas cette skill
• NE JAMAIS utiliser la CLI pour générer du code applicatif de production ; handoff à alchemy-api ou alchemy-agentic-gateway pour du code livré

Preflight

Avant la première commande, exécutez les deux vérifications :

alchemy --json --no-interactive setup status
alchemy --json --no-interactive gas

setup status retourne {"complete": true, "satisfiedBy": "<source>"} si une authentification est configurée. Ne vous fiez pas à complete: true seul — il existe un faux positif connu où setup status reporte complete: true avec satisfiedBy: "auth_token", mais les commandes RPC échouent toujours avec AUTH_REQUIRED car aucune clé API n'a été dérivée du token d'auth.

gas est un test de smoke RPC léger qui détecte ceci. S'il retourne {"gasPrice": "0x...", ...}, RPC est correctement configuré. S'il retourne {"error": {"code": "AUTH_REQUIRED", ...}}, exécutez alchemy auth login (qui récupère et enregistre la clé API) ou alchemy config set api-key <key>, puis relancez gas pour confirmer.

Si setup status reporte complete: false, suivez d'abord les nextCommands dans la réponse, puis exécutez gas pour vérifier.

Configuration de l'authentification

La façon la plus rapide de s'authentifier est via une connexion navigateur :

alchemy auth login

Ceci ouvre un navigateur pour s'authentifier avec votre compte Alchemy et configure automatiquement la CLI avec vos identifiants.

Pour vérifier le statut d'authentification : alchemy auth status Pour se déconnecter : alchemy auth logout

Méthodes d'authentification alternatives

alchemy network list et alchemy version / update-check ne nécessitent pas d'authentification.

Sélectionner une app par défaut

De nombreux sous-commandes apps (et les flux contrôlés par clé d'accès) opèrent sur une « app par défaut ». Si vous voyez APP_REQUIRED dans une réponse d'erreur, définissez-en une :

alchemy --json --no-interactive apps select <id>
# ou de manière équivalente
alchemy --json --no-interactive config set app <id>

Obtenez les clés API/accès sur dashboard.alchemy.com.

Correspondance tâche-commande

Node (EVM)

Données

Solana

Webhooks

Abstraction de compte (ERC-4337)

Portefeuille (x402)

Gestion d'app

Administration CLI

Flags globaux

Gestion des erreurs

Les erreurs retournent du JSON structuré sur stderr. Chaque erreur a un code, un exitCode (1–9), un booléen retryable, et un indice recovery. Codes clés (depuis agent-prompt) :

Obtenez la liste canonique complète à tout moment avec alchemy --json --no-interactive agent-prompt.

Handoff vers d'autres skills

Pontage vers le flux alchemy-api (extraire une clé API)

Si l'utilisateur commence un projet de code app et $ALCHEMY_API_KEY n'est pas défini dans son shell, utilisez la CLI pour récupérer une clé depuis son compte Alchemy, persistez-la au .env du projet pour qu'elle survive entre les sessions de terminal, et exportez-la pour le shell actuel pour que l'agent puisse l'utiliser immédiatement.

Sécurité : NE JAMAIS afficher, imprimer ou autrement présenter la valeur de clé API extraite dans la sortie de conversation. Référencez-la uniquement comme $ALCHEMY_API_KEY après exportation. Traitez-la comme un mot de passe.

# 1. Essayez de lire une clé mise en cache depuis la configuration CLI (lecture seule, sûr non-interactif).
KEY="$(alchemy --no-interactive --json --reveal config get api-key 2>/dev/null | jq -r .value)"

# 2. Si vide/null, exécutez le flux interactif.
#    Note : auth login ouvre un navigateur et apps select affiche un sélecteur, donc NE PASSEZ PAS
#    --no-interactive ici. Si vous connaissez déjà l'id d'app, passez-le
#    explicitement pour ignorer le sélecteur : `alchemy --no-interactive --json apps select <id>`.
if [ -z "$KEY" ] || [ "$KEY" = "null" ]; then
  alchemy auth login              # ouvre le navigateur ; configure les identifiants du compte
  alchemy --json apps select      # sélecteur interactif (omettez --no-interactive pour qu'il se rende)
  KEY="$(alchemy --no-interactive --json --reveal config get api-key | jq -r .value)"
fi

# 3. Persistez au .env du projet (pratique standard — survit aux redémarrages de terminal
#    et est chargé par dotenv / les chargeurs d'env du framework au runtime).
#    Utilisez .env.local si le framework du projet l'attend (ex 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. Exportez vers le shell actuel pour que l'agent puisse appeler l'API immédiatement.
export ALCHEMY_API_KEY="$KEY"

Handoff vers la skill alchemy-api une fois que .env a la clé et que ALCHEMY_API_KEY est exportée.

Liens officiels

• CLI sur npm
• Docs Alchemy
• Obtenir clé API