@alchemy/cli 0.1.5 → 0.2.0

package/README.md

@@ -18,6 +18,58 @@ Or run without installing globally:
 npx @alchemy/cli <command>
 ```
 
+## Getting Started
+
+### Authentication Quick Start
+
+Authentication is required before making requests. Configure auth first, then run commands.
+
+If you are using the CLI as a human in an interactive terminal, the easiest path is:
+
+```bash
+alchemy
+```
+
+Then follow the setup flow in the terminal UI to configure auth.
+
+Know which auth method does what:
+
+- **API key** - direct auth for blockchain queries (`balance`, `tx`, `block`, `nfts`, `tokens`, `rpc`)
+- **Access key** - Admin/API app management; app setup/selection can also provide API key auth for blockchain queries
+- **x402 wallet auth** - wallet-authenticated, pay-per-request model for supported blockchain queries
+
+If you use Notify webhooks, add webhook auth on top via `alchemy config set webhook-api-key <key>`, `--webhook-api-key`, or `ALCHEMY_WEBHOOK_API_KEY`.
+
+For setup commands, env vars, and resolution order, see [Authentication Reference](#authentication-reference).
+
+### 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):** always use `--json` and prefer non-interactive execution (`--no-interactive`)
+
+Quick usage examples:
+
+```bash
+# Human recommended entrypoint
+alchemy
+
+# Agent/script-friendly command
+alchemy balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --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:
+
+```bash
+# Agent runs this once to learn everything the CLI can do
+alchemy --json agent-prompt
+```
+
+This returns a single JSON document with execution policy, 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.
+
 ## Command Reference
 
 Run commands as `alchemy <command>`.
@@ -103,6 +155,7 @@ Use `alchemy help` or `alchemy help <command>` for generated command help.
 | `config get <key>` | Gets one config value | `alchemy config get network` |
 | `config list` | Lists all config values | `alchemy config list` |
 | `config reset [key]` | Resets one or all config values | `alchemy config reset --yes` |
+| `agent-prompt` | Emits complete agent/automation usage instructions | `alchemy --json agent-prompt` |
 | `version` | Prints CLI version | `alchemy version` |
 
 ## Flags
@@ -176,13 +229,13 @@ Additional env vars:
 | `network list` | `--configured`, `--app-id <id>` |
 | `config reset` | `-y, --yes` |
 
-## Authentication
+## Authentication Reference
 
 The CLI supports three auth inputs:
 
 - API key for blockchain queries (`balance`, `tx`, `block`, `nfts`, `tokens`, `rpc`)
-- Access key for Admin API operations (`apps`, `chains`, configured network lookups)
-- x402 wallet key for wallet-authenticated blockchain queries
+- Access key for Admin API operations (`apps`, `chains`, configured network lookups`) and app setup/selection, which can also supply the API key used by blockchain query commands
+- x402 wallet key for wallet-authenticated blockchain queries in a pay-per-request model
 
 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.
@@ -221,6 +274,9 @@ Resolution order: `--access-key` -> `ALCHEMY_ACCESS_KEY` -> config file.
 
 #### x402 wallet auth
 
+x402 is a wallet-authenticated, pay-per-request usage model for supported blockchain queries.
+The CLI can generate or import the wallet key used for these requests.
+
 ```bash
 # Generate/import a wallet managed by CLI
 alchemy wallet generate
@@ -277,116 +333,3 @@ Errors are structured JSON in JSON mode:
   }
 }
 ```
-
-## Development
-
-Prerequisites:
-
-- [Node.js 22+](https://nodejs.org/)
-- [pnpm](https://pnpm.io/)
-
-### Local development setup
-
-```bash
-git clone https://github.com/alchemyplatform/alchemy-cli.git
-cd alchemy-cli
-pnpm install
-pnpm build
-pnpm link --global
-```
-
-This makes the local `alchemy` build available globally for testing.
-To unlink later: `pnpm unlink --global`.
-
-Run during development:
-
-```bash
-# Run without building
-npx tsx src/index.ts balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
-
-# Build in watch mode
-pnpm dev
-```
-
-Build:
-
-```bash
-pnpm build
-```
-
-Test:
-
-```bash
-pnpm test
-pnpm test:e2e
-```
-
-Type check:
-
-```bash
-pnpm lint
-```
-
-Coverage:
-
-```bash
-pnpm test:coverage
-```
-
-### Changesets & Releasing
-
-This project uses [Changesets](https://github.com/changesets/changesets) for versioning and release notes.
-
-**When to add a changeset:** Any PR with user-facing changes (new commands, bug fixes, flag changes, output format changes) needs a changeset. Internal changes (CI, refactors with no behavior change, docs) can skip by adding the `no-changeset` label.
-
-**How to add a changeset:**
-
-```bash
-pnpm changeset
-```
-
-You'll be prompted to pick the bump type:
-- **patch** — bug fixes, small tweaks (e.g. fixing `--json` output for a command)
-- **minor** — new commands, new flags, new capabilities
-- **major** — breaking changes (removed commands, changed flag behavior, output format changes)
-
-This creates a file like `.changeset/cool-dogs-fly.md`:
-
-```markdown
----
-"@alchemy/cli": minor
----
-
-Add `alchemy portfolio transactions` command for portfolio transaction history.
-```
-
-Write a 1-2 sentence summary of the change from a user's perspective. Commit this file with your PR.
-
-**How releases work:** When PRs with changesets merge to `main`, the publish workflow automatically:
-1. Verifies the build (typecheck, build, test)
-2. Applies version bumps and updates `CHANGELOG.md` via `changeset version`
-3. Creates a signed release commit via the GitHub Git Database API (using a GitHub App token)
-4. Publishes to npm using OIDC trusted publishing (no long-lived npm token)
-5. Creates a GitHub release/tag with notes extracted from `CHANGELOG.md`
-
-If no changesets are pending, the workflow exits cleanly — no release is created.
-
-**Release infrastructure:**
-- Repository write operations use a GitHub App (`APP_ID` variable + `APP_PRIVATE_KEY` secret)
-- npm publish uses [trusted publishing](https://docs.npmjs.com/generating-provenance-statements) (OIDC) — no `NPM_TOKEN` secret required
-- Required GitHub repo settings: `APP_ID` (variable), `APP_PRIVATE_KEY` (secret)
-- Required npm-side: configure trusted publishing for this repo/workflow at npmjs.com package settings
-
-### Endpoint Override Env Vars (Local Testing Only)
-
-These are for local/mock testing, not normal production usage:
-
-- `ALCHEMY_RPC_BASE_URL`
-- `ALCHEMY_ADMIN_API_BASE_URL`
-- `ALCHEMY_X402_BASE_URL`
-
-Safety constraints:
-
-- Only localhost targets are accepted (`localhost`, `127.0.0.1`, `::1`)
-- Non-HTTPS transport is allowed only for localhost
-- Production defaults are unchanged when unset

package/dist/{chunk-F7KTEZFZ.js → chunk-MAKSV2EA.js}

@@ -2,7 +2,7 @@
 if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   isInteractiveAllowed
-} from "./chunk-QKXQW4OF.js";
+} from "./chunk-VRBWUQHA.js";
 
 // src/lib/networks.ts
 var TESTNET_TOKEN_RE = /(testnet|sepolia|holesky|hoodi|devnet|minato|amoy|fuji|saigon|cardona|aeneid|curtis|chiado|cassiopeia|blaze|ropsten|signet|mocha|fam|bepolia)$/i;

package/dist/{chunk-PH4BPYSY.js → chunk-VD5WQHLQ.js}

@@ -40,7 +40,7 @@ import {
   toMap,
   withSpinner,
   yellow
-} from "./chunk-QKXQW4OF.js";
+} from "./chunk-VRBWUQHA.js";
 
 // src/lib/client-utils.ts
 function isLocalhost(hostname) {

package/dist/{chunk-QKXQW4OF.js → chunk-VRBWUQHA.js}

@@ -1063,6 +1063,7 @@ export {
   debug,
   formatCommanderError,
   ErrorCode,
+  EXIT_CODES,
   CLIError,
   errAuthRequired,
   errAccessKeyRequired,

package/dist/index.js

@@ -14,14 +14,16 @@ import {
   splitCommaList,
   validateAddress,
   validateTxHash
-} from "./chunk-PH4BPYSY.js";
+} from "./chunk-VD5WQHLQ.js";
 import {
   getRPCNetworks,
   getSetupStatus,
   isSetupComplete,
   shouldRunOnboarding
-} from "./chunk-F7KTEZFZ.js";
+} from "./chunk-MAKSV2EA.js";
 import {
+  EXIT_CODES,
+  ErrorCode,
   bold,
   brand,
   brandedHelp,
@@ -60,7 +62,7 @@ import {
   verbose,
   weiToEth,
   withSpinner
-} from "./chunk-QKXQW4OF.js";
+} from "./chunk-VRBWUQHA.js";
 
 // src/index.ts
 import { Command, Help } from "commander";
@@ -1609,6 +1611,195 @@ function registerSolana(program2) {
   });
 }
 
+// src/commands/agent-prompt.ts
+var RETRYABLE_CODES = /* @__PURE__ */ new Set([
+  ErrorCode.RATE_LIMITED,
+  ErrorCode.NETWORK_ERROR
+]);
+var ERROR_RECOVERY = {
+  AUTH_REQUIRED: "Set ALCHEMY_API_KEY env var or run: alchemy config set api-key <key>",
+  INVALID_API_KEY: "Check your API key and set a valid one: alchemy config set api-key <key>",
+  NETWORK_NOT_ENABLED: "Enable the target network for your app at dashboard.alchemy.com",
+  INVALID_ACCESS_KEY: "Check your access key: https://dashboard.alchemy.com/",
+  ACCESS_KEY_REQUIRED: "Set ALCHEMY_ACCESS_KEY env var or run: alchemy config set access-key <key>",
+  APP_REQUIRED: "Select an app: alchemy config set app <app-id>",
+  ADMIN_API_ERROR: "Check the error message for details; verify access key permissions",
+  NETWORK_ERROR: "Check internet connection and retry",
+  RPC_ERROR: "Check RPC method, params, and network; verify API key has access",
+  INVALID_ARGS: "Check command usage via: alchemy --json help <command>",
+  NOT_FOUND: "Verify the resource identifier (address, hash, id) is correct",
+  RATE_LIMITED: "Wait and retry; consider upgrading your Alchemy plan",
+  PAYMENT_REQUIRED: "Fund your x402 wallet or switch to API key auth",
+  SETUP_REQUIRED: "Run preflight: alchemy --json setup status, then follow nextCommands",
+  INTERNAL_ERROR: "Unexpected error; retry or report a bug"
+};
+function buildCommandSchema(cmd) {
+  const schema = {
+    name: cmd.name(),
+    description: cmd.description()
+  };
+  const aliases = cmd.aliases();
+  if (aliases.length > 0) {
+    schema.aliases = aliases;
+  }
+  const args = cmd.registeredArguments;
+  if (args.length > 0) {
+    schema.arguments = args.map((a) => ({
+      name: a.name(),
+      description: a.description,
+      required: a.required
+    }));
+  }
+  const opts = cmd.options;
+  if (opts.length > 0) {
+    schema.options = opts.map((o) => ({
+      flags: o.flags,
+      description: o.description
+    }));
+  }
+  const subs = cmd.commands;
+  if (subs.length > 0) {
+    schema.subcommands = subs.map(buildCommandSchema);
+  }
+  return schema;
+}
+function buildAgentPrompt(program2) {
+  const errors = {};
+  for (const [code, exitCode] of Object.entries(EXIT_CODES)) {
+    errors[code] = {
+      exitCode,
+      retryable: RETRYABLE_CODES.has(code),
+      recovery: ERROR_RECOVERY[code] ?? "Check error message"
+    };
+  }
+  const commands = program2.commands.filter((cmd) => cmd.name() !== "agent-prompt").map(buildCommandSchema);
+  return {
+    executionPolicy: [
+      "Always pass --json --no-interactive",
+      "Parse stdout as JSON on exit code 0",
+      "Parse stderr as JSON on nonzero exit code",
+      "Never run bare 'alchemy' without --json --no-interactive"
+    ],
+    preflight: {
+      command: "alchemy --json setup status",
+      description: "Check auth readiness before first command. If complete is false, follow nextCommands in the response to configure auth."
+    },
+    auth: [
+      {
+        method: "API key",
+        envVar: "ALCHEMY_API_KEY",
+        flag: "--api-key <key>",
+        configKey: "api-key",
+        commandFamilies: [
+          "balance",
+          "tx",
+          "block",
+          "rpc",
+          "trace",
+          "debug",
+          "tokens",
+          "nfts",
+          "transfers",
+          "prices",
+          "portfolio",
+          "simulate",
+          "solana"
+        ]
+      },
+      {
+        method: "Access key",
+        envVar: "ALCHEMY_ACCESS_KEY",
+        flag: "--access-key <key>",
+        configKey: "access-key",
+        commandFamilies: ["apps", "chains", "network list --configured"]
+      },
+      {
+        method: "Webhook API key",
+        envVar: "ALCHEMY_WEBHOOK_API_KEY",
+        flag: "--webhook-api-key <key>",
+        configKey: "webhook-api-key",
+        commandFamilies: ["webhooks"]
+      },
+      {
+        method: "x402 wallet",
+        envVar: "ALCHEMY_WALLET_KEY",
+        flag: "--x402 --wallet-key-file <path>",
+        configKey: "x402",
+        commandFamilies: [
+          "balance",
+          "tx",
+          "block",
+          "rpc",
+          "trace",
+          "debug",
+          "tokens",
+          "nfts",
+          "transfers"
+        ]
+      }
+    ],
+    commands,
+    errors,
+    examples: [
+      "alchemy --json --no-interactive setup status",
+      "alchemy --json --no-interactive balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --api-key $ALCHEMY_API_KEY",
+      "alchemy --json --no-interactive apps list --access-key $ALCHEMY_ACCESS_KEY",
+      "alchemy --json --no-interactive rpc eth_blockNumber --api-key $ALCHEMY_API_KEY",
+      "alchemy --json --no-interactive network list"
+    ],
+    docs: "https://www.alchemy.com/docs"
+  };
+}
+function formatAsSystemPrompt(payload) {
+  const lines = [];
+  lines.push("Alchemy CLI agent instructions");
+  lines.push("==============================");
+  lines.push("");
+  lines.push("Execution policy:");
+  for (const rule of payload.executionPolicy) {
+    lines.push(`  - ${rule}`);
+  }
+  lines.push("");
+  lines.push("Preflight:");
+  lines.push(`  Command: ${payload.preflight.command}`);
+  lines.push(`  ${payload.preflight.description}`);
+  lines.push("");
+  lines.push("Auth methods:");
+  for (const auth of payload.auth) {
+    lines.push(`  ${auth.method}:`);
+    lines.push(`    env:      ${auth.envVar}`);
+    lines.push(`    flag:     ${auth.flag}`);
+    lines.push(`    config:   alchemy config set ${auth.configKey} <value>`);
+    lines.push(`    commands: ${auth.commandFamilies.join(", ")}`);
+  }
+  lines.push("");
+  lines.push("Error codes:");
+  for (const [code, entry] of Object.entries(payload.errors)) {
+    const retry = entry.retryable ? " [retryable]" : "";
+    lines.push(`  ${code} (exit ${entry.exitCode})${retry}: ${entry.recovery}`);
+  }
+  lines.push("");
+  lines.push("Examples:");
+  for (const example of payload.examples) {
+    lines.push(`  ${example}`);
+  }
+  lines.push("");
+  lines.push(`Docs: ${payload.docs}`);
+  lines.push("  For RPC method signatures, parameters, and supported networks.");
+  lines.push("");
+  lines.push(
+    "For full command tree, run: alchemy --json agent-prompt"
+  );
+  lines.push("");
+  return lines.join("\n");
+}
+function registerAgentPrompt(program2) {
+  program2.command("agent-prompt").description("Emit complete agent/automation usage instructions").action(() => {
+    const payload = buildAgentPrompt(program2);
+    printHuman(formatAsSystemPrompt(payload), payload);
+  });
+}
+
 // src/index.ts
 var hBrand = noColor ? identity : (s) => `\x1B[38;2;54;63;249m${s}\x1B[39m`;
 var hBold = esc("1");
@@ -1646,7 +1837,7 @@ var ROOT_COMMAND_PILLARS = [
   },
   {
     label: "Admin",
-    commands: ["apps", "config", "setup", "version", "help"]
+    commands: ["apps", "config", "setup", "agent-prompt", "version", "help"]
   }
 ];
 function formatCommandSignature(sub) {
@@ -1683,7 +1874,7 @@ var findCommandByPath = (root, path) => {
 };
 program.name("alchemy").description(
   "The Alchemy CLI lets you query blockchain data, call JSON-RPC methods, and manage your Alchemy configuration."
-).version("0.1.5").option("--api-key <key>", "Alchemy API key (env: ALCHEMY_API_KEY)").option("--access-key <key>", "Alchemy access key (env: ALCHEMY_ACCESS_KEY)").option(
+).version("0.2.0").option("--api-key <key>", "Alchemy API key (env: ALCHEMY_API_KEY)").option("--access-key <key>", "Alchemy access key (env: ALCHEMY_ACCESS_KEY)").option(
   "-n, --network <network>",
   "Target network (default: eth-mainnet) (env: ALCHEMY_NETWORK)"
 ).option("--x402", "Use x402 wallet-based gateway auth").option("--wallet-key-file <path>", "Path to wallet private key file for x402").option("--json", "Force JSON output").option("-q, --quiet", "Suppress non-essential output").option("-v, --verbose", "Enable verbose output").option("--no-color", "Disable color output").option("--reveal", "Show secrets in plain text (TTY only)").option("--timeout <ms>", "Request timeout in milliseconds", parseInt).option("--debug", "Enable debug diagnostics").option("--no-interactive", "Disable REPL and prompt-driven interactions").addHelpCommand(false).configureOutput({
@@ -1835,13 +2026,13 @@ ${styledLine}`;
   }
   if (isInteractiveAllowed(program)) {
     if (shouldRunOnboarding(program, cfg)) {
-      const { runOnboarding } = await import("./onboarding-3J4EXZMG.js");
+      const { runOnboarding } = await import("./onboarding-IKIXUTY7.js");
       const completed = await runOnboarding(program);
       if (!completed) {
         return;
       }
     }
-    const { startREPL } = await import("./interactive-2ITFWH3B.js");
+    const { startREPL } = await import("./interactive-CP6E23OD.js");
     program.exitOverride();
     program.configureOutput({
       writeErr: () => {
@@ -1874,6 +2065,7 @@ registerApps(program);
 registerSetup(program);
 registerConfig(program);
 registerSolana(program);
+registerAgentPrompt(program);
 registerVersion(program);
 program.command("help [command...]").description("display help for command").action((commandPath) => {
   if (!commandPath || commandPath.length === 0) {

package/dist/{interactive-2ITFWH3B.js → interactive-CP6E23OD.js}

@@ -3,7 +3,7 @@ if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   getRPCNetworkIds,
   getSetupMethod
-} from "./chunk-F7KTEZFZ.js";
+} from "./chunk-MAKSV2EA.js";
 import {
   bgRgb,
   bold,
@@ -18,7 +18,7 @@ import {
   rgb,
   setBrandedHelpSuppressed,
   setReplMode
-} from "./chunk-QKXQW4OF.js";
+} from "./chunk-VRBWUQHA.js";
 
 // src/commands/interactive.ts
 import * as readline from "readline";
@@ -100,6 +100,7 @@ var COMMAND_NAMES = [
   "tokens metadata",
   "tokens allowance",
   "tx",
+  "agent-prompt",
   "version",
   "wallet",
   "wallet generate",

package/dist/{onboarding-3J4EXZMG.js → onboarding-IKIXUTY7.js}

@@ -5,7 +5,7 @@ import {
   generateAndPersistWallet,
   importAndPersistWallet,
   selectOrCreateApp
-} from "./chunk-PH4BPYSY.js";
+} from "./chunk-VD5WQHLQ.js";
 import {
   bold,
   brand,
@@ -18,7 +18,7 @@ import {
   promptSelect,
   promptText,
   save
-} from "./chunk-QKXQW4OF.js";
+} from "./chunk-VRBWUQHA.js";
 
 // src/commands/onboarding.ts
 function printNextSteps(method) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alchemy/cli",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Alchemy CLI — interact with blockchain data",
   "type": "module",
   "bin": {