@alchemy/cli 0.2.2 → 0.3.1

package/README.md

@@ -18,6 +18,23 @@ Or run without installing globally:
 npx @alchemy/cli <command>
 ```
 
+## Shell Completions
+
+Enable Tab completion for all commands and subcommands:
+
+```bash
+# 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
@@ -47,7 +64,7 @@ For setup commands, env vars, and resolution order, see [Authentication Referenc
 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`)
+- **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:
 
@@ -86,7 +103,10 @@ Use `alchemy help` or `alchemy help <command>` for generated command help.
 |---|---|---|
 | `balance [address]` (`bal [address]`) | Gets ETH balance for an address | `alchemy bal 0x...` |
 | `tx [hash]` | Gets transaction + receipt by hash | `alchemy tx 0x...` |
+| `receipt [hash]` | Gets transaction receipt (status, gas, logs) | `alchemy receipt 0x...` |
 | `block <number>` | Gets block details (`latest`, decimal, or hex) | `alchemy block latest` |
+| `gas` | Gets current gas prices (base fee + priority fee) | `alchemy gas -n polygon-mainnet` |
+| `logs` | Queries event logs (`eth_getLogs`) | `alchemy logs --address 0x... --from-block 18000000 --to-block 18000010` |
 | `rpc <method> [params...]` | Makes raw JSON-RPC call | `alchemy rpc eth_blockNumber` |
 | `trace <method> [params...]` | Calls Trace API methods | `alchemy trace call '{"to":"0x..."}' '["trace"]' latest` |
 | `debug <method> [params...]` | Calls Debug API methods | `alchemy debug traceTransaction "0x..."` |
@@ -136,8 +156,7 @@ Use `alchemy help` or `alchemy help <command>` for generated command help.
 
 | Command | What it does | Example |
 |---|---|---|
-| `network list` | Lists supported RPC networks | `alchemy network list --configured` |
-| `chains list` | Lists Admin API chain enums | `alchemy chains list` |
+| `network list` | Lists RPC network IDs for use with `--network` (e.g. `eth-mainnet`) | `alchemy network list --configured` |
 | `solana rpc <method> [params...]` | Calls Solana JSON-RPC methods | `alchemy solana rpc getBalance '"<pubkey>"'` |
 | `solana das <method> [params...]` | Calls Solana DAS methods | `alchemy solana das getAssetsByOwner '{"ownerAddress":"<pubkey>"}'` |
 
@@ -147,6 +166,7 @@ Use `alchemy help` or `alchemy help <command>` for generated command help.
 |---|---|---|
 | `(no command)` | Starts interactive REPL mode (TTY only) | `alchemy` |
 | `apps list` | Lists apps (supports pagination/filtering) | `alchemy apps list --all` |
+| `apps chains` | Lists Admin API chain identifiers (e.g. `ETH_MAINNET`) | `alchemy apps chains` |
 | `apps get <id>` | Gets app details | `alchemy apps get <app-id>` |
 | `apps create` | Creates app | `alchemy apps create --name "My App" --networks eth-mainnet` |
 | `apps update <id>` | Updates app name/description | `alchemy apps update <app-id> --name "New Name"` |
@@ -161,6 +181,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` |
+| `completions <shell>` | Generates shell completion scripts (bash/zsh/fish) | `eval "$(alchemy completions zsh)"` |
 | `agent-prompt` | Emits complete agent/automation usage instructions | `alchemy --json agent-prompt` |
 | `version` | Prints CLI version | `alchemy version` |
 
@@ -184,7 +205,7 @@ These apply to all commands.
 
 | Flag | Env var | Description |
 |---|---|---|
-| `--json` | — | Force JSON output |
+| `--json` | — | Force JSON output (auto-enabled when piped) |
 | `-q, --quiet` | — | Suppress non-essential output |
 | `--verbose` | — | Enable verbose output |
 | `--no-color` | `NO_COLOR` | Disable color output |
@@ -321,11 +342,10 @@ Use `--no-interactive` to disable REPL/prompts in automation.
 
 ## Output Modes
 
-- TTY: formatted human output
-- Non-TTY: JSON output (script-friendly)
-- `-v`, `--version`: prints the CLI version
-- `--json`: forces JSON output in any context
-- `--verbose` or `alchemy config set verbose true`: includes richer payload output on supported commands
+- **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
 

package/dist/{chunk-2WI4JODY.js → chunk-6XTLILDF.js}

@@ -4,10 +4,13 @@ if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 // src/lib/colors.ts
 var forceColor = "FORCE_COLOR" in process.env && process.env.FORCE_COLOR !== "0";
 var noColor = !forceColor && ("NO_COLOR" in process.env || process.env.TERM === "dumb");
+function setNoColor(value) {
+  noColor = value;
+}
 var identity = (s) => s;
-var esc = (code) => noColor ? identity : (s) => `\x1B[${code}m${s}\x1B[0m`;
-var rgb = (r, g, b) => noColor ? identity : (s) => `\x1B[38;2;${r};${g};${b}m${s}\x1B[39m`;
-var bgRgb = (r, g, b) => noColor ? identity : (s) => `\x1B[48;2;${r};${g};${b}m${s}\x1B[49m`;
+var esc = (code) => (s) => noColor ? s : `\x1B[${code}m${s}\x1B[0m`;
+var rgb = (r, g, b) => (s) => noColor ? s : `\x1B[38;2;${r};${g};${b}m${s}\x1B[39m`;
+var bgRgb = (r, g, b) => (s) => noColor ? s : `\x1B[48;2;${r};${g};${b}m${s}\x1B[49m`;
 
 // src/lib/redact.ts
 var SENSITIVE_ERROR_CODES = /* @__PURE__ */ new Set([
@@ -475,7 +478,8 @@ function getHome() {
 }
 function configPath() {
   if (process.env.ALCHEMY_CONFIG) return process.env.ALCHEMY_CONFIG;
-  return join(getHome(), ".config", "alchemy", "config.json");
+  const configHome = process.env.XDG_CONFIG_HOME || join(getHome(), ".config");
+  return join(configHome, "alchemy", "config.json");
 }
 function configDir() {
   return dirname(configPath());
@@ -647,8 +651,9 @@ async function runListPrompt(opts) {
     stdin.setRawMode(previousRawMode);
     stdin.removeListener("keypress", onKeypress);
     restoreKeypressListeners();
-    stdin.pause();
-    stdin.unref?.();
+    if (!previousRawMode) {
+      stdin.pause();
+    }
   };
   const commitSingleLine = (text) => {
     if (opts.commitLabel === null) return;
@@ -1109,7 +1114,7 @@ function semverLT(a, b) {
   return false;
 }
 function currentVersion() {
-  return true ? "0.2.2" : "0.0.0";
+  return true ? "0.3.1" : "0.0.0";
 }
 function toUpdateStatus(latestVersion, checkedAt) {
   const current = currentVersion();
@@ -1168,10 +1173,12 @@ ${getUpdateNoticeLines(latest).join("\n")}
 
 export {
   noColor,
+  setNoColor,
   identity,
   esc,
   rgb,
   bgRgb,
+  redactSensitiveText,
   quiet,
   verbose,
   timeout,
@@ -1214,6 +1221,7 @@ export {
   promptAutocomplete,
   promptMultiselect,
   green,
+  red,
   dim,
   bold,
   yellow,

package/dist/{chunk-6KOJKH6N.js → chunk-J6RZM4CJ.js}

@@ -36,12 +36,14 @@ import {
   promptMultiselect,
   promptSelect,
   promptText,
+  redactSensitiveText,
   save,
   timeout,
   toMap,
+  verbose,
   withSpinner,
   yellow
-} from "./chunk-2WI4JODY.js";
+} from "./chunk-6XTLILDF.js";
 
 // src/lib/client-utils.ts
 function isLocalhost(hostname) {
@@ -73,10 +75,15 @@ function parseBaseURLOverride(envVarName) {
   }
   return parsed;
 }
+var BREADCRUMB_HEADER = "alchemy-cli";
 async function fetchWithTimeout(url, init) {
   try {
     return await fetch(url, {
       ...init,
+      headers: {
+        ...init.headers,
+        "x-alchemy-client-breadcrumb": BREADCRUMB_HEADER
+      },
       ...timeout && { signal: AbortSignal.timeout(timeout) }
     });
   } catch (err) {
@@ -269,6 +276,92 @@ var AdminClient = class _AdminClient {
   }
 };
 
+// src/lib/ens.ts
+import { keccak_256 } from "@noble/hashes/sha3.js";
+var UNIVERSAL_RESOLVER = "0xeEeEEEeE14D718C2B47D9923Deab1335E144EeEe";
+var RESOLVE_SELECTOR = "9061b923";
+var ADDR_SELECTOR = "3b3b57de";
+function bytesToHex(bytes) {
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function pad32(hex) {
+  return hex.padStart(64, "0");
+}
+function namehash(name) {
+  let node = new Uint8Array(32);
+  if (!name) return node;
+  const labels = name.split(".");
+  for (let i = labels.length - 1; i >= 0; i--) {
+    const labelHash = keccak_256(new TextEncoder().encode(labels[i]));
+    const combined = new Uint8Array(64);
+    combined.set(node, 0);
+    combined.set(labelHash, 32);
+    node = keccak_256(combined);
+  }
+  return node;
+}
+function dnsEncode(name) {
+  const labels = name.split(".");
+  const parts = [];
+  for (const label of labels) {
+    const encoded = new TextEncoder().encode(label);
+    parts.push(encoded.length);
+    parts.push(...encoded);
+  }
+  parts.push(0);
+  return new Uint8Array(parts);
+}
+function buildResolveCalldata(name) {
+  const dnsName = dnsEncode(name);
+  const node = namehash(name);
+  const innerHex = ADDR_SELECTOR + bytesToHex(node);
+  const innerLen = 36;
+  const dnsHex = bytesToHex(dnsName);
+  const nameLen = dnsName.length;
+  const namePad = Math.ceil(nameLen / 32) * 32;
+  const innerPad = Math.ceil(innerLen / 32) * 32;
+  const nameOffset = 64;
+  const dataOffset = nameOffset + 32 + namePad;
+  let hex = RESOLVE_SELECTOR;
+  hex += pad32(nameOffset.toString(16));
+  hex += pad32(dataOffset.toString(16));
+  hex += pad32(nameLen.toString(16));
+  hex += dnsHex.padEnd(namePad * 2, "0");
+  hex += pad32(innerLen.toString(16));
+  hex += innerHex.padEnd(innerPad * 2, "0");
+  return "0x" + hex;
+}
+function isENSName(value) {
+  return value.endsWith(".eth") && value.length > 4 && !value.startsWith("0x");
+}
+async function resolveENS(name, client) {
+  if (!client.network.startsWith("eth-")) {
+    throw errInvalidArgs(
+      `ENS resolution is only supported on Ethereum networks. Current network: ${client.network}`
+    );
+  }
+  const calldata = buildResolveCalldata(name.toLowerCase());
+  const result = await client.call("eth_call", [
+    { to: UNIVERSAL_RESOLVER, data: calldata },
+    "latest"
+  ]);
+  if (!result || result === "0x" || result.length < 130) {
+    throw errInvalidArgs(`ENS name "${name}" could not be resolved.`);
+  }
+  const raw = result.slice(2);
+  const dataOffset = parseInt(raw.slice(0, 64), 16) * 2;
+  const dataLen = parseInt(raw.slice(dataOffset, dataOffset + 64), 16);
+  const dataHex = raw.slice(dataOffset + 64, dataOffset + 64 + dataLen * 2);
+  if (dataHex.length < 64) {
+    throw errInvalidArgs(`ENS name "${name}" could not be resolved.`);
+  }
+  const address = "0x" + dataHex.slice(24, 64);
+  if (address === "0x0000000000000000000000000000000000000000") {
+    throw errInvalidArgs(`ENS name "${name}" is not registered or has no address set.`);
+  }
+  return address;
+}
+
 // src/lib/validators.ts
 function splitCommaList(input) {
   return input.split(",").map((s) => s.trim()).filter(Boolean);
@@ -297,6 +390,13 @@ function validateAddress(address) {
     );
   }
 }
+async function resolveAddress(input, client) {
+  if (isENSName(input)) {
+    return resolveENS(input, client);
+  }
+  validateAddress(input);
+  return input;
+}
 function validateTxHash(hash) {
   if (!TX_HASH_RE.test(hash)) {
     throw errInvalidArgs(
@@ -551,13 +651,13 @@ function registerConfig(program) {
       if (normalized !== "true" && normalized !== "false") {
         throw errInvalidArgs("verbose must be 'true' or 'false'");
       }
-      const verbose = normalized === "true";
+      const verbose2 = normalized === "true";
       const cfg = load();
-      save({ ...cfg, verbose });
+      save({ ...cfg, verbose: verbose2 });
       printHuman(
-        `${green("\u2713")} Set verbose default to ${verbose}
+        `${green("\u2713")} Set verbose default to ${verbose2}
 `,
-        { key: "verbose", value: String(verbose), status: "set" }
+        { key: "verbose", value: String(verbose2), status: "set" }
       );
     } catch (err) {
       exitWithError(err);
@@ -593,13 +693,28 @@ function registerConfig(program) {
   });
   cmd.command("get <key>").description("Get a config value (api-key, access-key, app, network, verbose, wallet-key-file, x402)").action((key) => {
     const cfg = load();
-    const value = get(cfg, key);
+    let value = get(cfg, key);
+    let isDefault = false;
+    if (value === void 0) {
+      const defaults = {
+        network: "eth-mainnet",
+        verbose: "false",
+        x402: "false"
+      };
+      const normalizedKey = KEY_MAP[key] ?? key;
+      const defaultValue = defaults[normalizedKey] ?? defaults[key];
+      if (defaultValue !== void 0) {
+        value = defaultValue;
+        isDefault = true;
+      }
+    }
     if (value === void 0) {
       exitWithError(errNotFound(`config key '${key}'`));
     }
     const isSecret = key === "api-key" || key === "api_key" || key === "access-key" || key === "access_key";
     const display = isSecret ? maskIf(value) : value;
-    printHuman(display + "\n", { key, value: display });
+    const humanDisplay = isDefault ? `${display} ${dim("(default)")}` : display;
+    printHuman(humanDisplay + "\n", { key, value: display, ...isDefault && { default: true } });
   });
   cmd.command("list").description("List all config values").action(() => {
     const cfg = load();
@@ -761,6 +876,12 @@ var Client = class _Client {
     }
     return null;
   }
+  verboseLog(message) {
+    if (verbose) {
+      process.stderr.write(`[verbose] ${message}
+`);
+    }
+  }
   async doFetch(url, init) {
     return fetchWithTimeout(url, init);
   }
@@ -771,6 +892,14 @@ var Client = class _Client {
       params,
       id: 1
     };
+    const redactedURL = redactSensitiveText(this.rpcURL());
+    this.verboseLog(`\u2192 POST ${redactedURL}`);
+    this.verboseLog(`  method: ${method}`);
+    const hasParams = Array.isArray(params) ? params.length > 0 : Object.keys(params).length > 0;
+    if (hasParams) {
+      this.verboseLog(`  params: ${JSON.stringify(params)}`);
+    }
+    const startTime = Date.now();
     const resp = await this.doFetch(this.rpcURL(), {
       method: "POST",
       headers: {
@@ -779,6 +908,7 @@ var Client = class _Client {
       },
       body: JSON.stringify(body)
     });
+    this.verboseLog(`\u2190 ${resp.status} ${resp.statusText} (${Date.now() - startTime}ms)`);
     if (resp.status === 429) throw errRateLimited();
     if (resp.status === 401 || resp.status === 403) {
       const detail = await resp.text().catch(() => "");
@@ -801,9 +931,13 @@ var Client = class _Client {
     for (const [k, v] of Object.entries(params)) {
       url.searchParams.set(k, v);
     }
+    const redactedURL = redactSensitiveText(url.toString());
+    this.verboseLog(`\u2192 GET ${redactedURL}`);
+    const startTime = Date.now();
     const resp = await this.doFetch(url.toString(), {
       headers: { Accept: "application/json" }
     });
+    this.verboseLog(`\u2190 ${resp.status} ${resp.statusText} (${Date.now() - startTime}ms)`);
     if (resp.status === 429) throw errRateLimited();
     if (resp.status === 401 || resp.status === 403) {
       const detail = await resp.text().catch(() => "");
@@ -1008,13 +1142,13 @@ function resolveAccessKey(program, cfg) {
   if (config.access_key) return config.access_key;
   return void 0;
 }
-function resolveNetwork(program, cfg) {
+function resolveNetwork(program, cfg, defaultNetwork) {
   const opts = program.opts();
   if (opts.network) return opts.network;
   if (process.env.ALCHEMY_NETWORK) return process.env.ALCHEMY_NETWORK;
   const config = cfg ?? load();
   if (config.network) return config.network;
-  return "eth-mainnet";
+  return defaultNetwork ?? "eth-mainnet";
 }
 function resolveAppId(program, cfg) {
   const opts = program.opts();
@@ -1048,10 +1182,16 @@ function resolveWalletKey(program, cfg) {
   }
   return void 0;
 }
-function clientFromFlags(program) {
+function clientFromFlags(program, opts) {
   const cfg = load();
-  const network = resolveNetwork(program, cfg);
+  const network = resolveNetwork(program, cfg, opts?.defaultNetwork);
   debug(`using network=${network}`);
+  const programOpts = program.opts();
+  if (programOpts.accessKey) {
+    throw errInvalidArgs(
+      "--access-key is for admin commands (apps, chains, webhooks). Use --api-key for RPC commands."
+    );
+  }
   if (resolveX402(program, cfg)) {
     const walletKey = resolveWalletKey(program, cfg);
     if (!walletKey) throw errWalletKeyRequired();
@@ -1139,7 +1279,7 @@ function registerWallet(program) {
       exitWithError(err);
     }
   });
-  cmd.command("import <path>").description("Import a wallet from a private key file").action((path) => {
+  cmd.command("import").argument("<path>", "Path to private key file").description("Import a wallet from a private key file").action((path) => {
     try {
       const wallet = importAndPersistWallet(path);
       if (isJSONMode()) {
@@ -1177,6 +1317,7 @@ export {
   splitCommaList,
   readStdinArg,
   validateAddress,
+  resolveAddress,
   validateTxHash,
   selectOrCreateApp,
   registerConfig,

package/dist/{chunk-NA7MQB7X.js → chunk-QDDJ3OYO.js}

@@ -2,7 +2,7 @@
 if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   isInteractiveAllowed
-} from "./chunk-2WI4JODY.js";
+} from "./chunk-6XTLILDF.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;
@@ -227,6 +227,42 @@ function getRPCNetworks() {
 function getRPCNetworkIds() {
   return [...RPC_NETWORK_IDS];
 }
+var NATIVE_TOKEN_SYMBOLS = {
+  eth: "ETH",
+  arb: "ETH",
+  arbnova: "ETH",
+  opt: "ETH",
+  base: "ETH",
+  zksync: "ETH",
+  scroll: "ETH",
+  blast: "ETH",
+  linea: "ETH",
+  zora: "ETH",
+  shape: "ETH",
+  polygon: "POL",
+  polygonzkevm: "ETH",
+  bnb: "BNB",
+  opbnb: "BNB",
+  avax: "AVAX",
+  solana: "SOL",
+  starknet: "ETH",
+  fantom: "FTM",
+  metis: "METIS",
+  mantle: "MNT",
+  celo: "CELO",
+  gnosis: "xDAI",
+  frax: "frxETH",
+  worldchain: "ETH",
+  berachain: "BERA",
+  flow: "FLOW",
+  rootstock: "RBTC",
+  zetachain: "ZETA",
+  sui: "SUI"
+};
+function nativeTokenSymbol(networkId) {
+  const prefix = networkId.replace(/-(mainnet|testnet|sepolia|holesky|hoodi|devnet|amoy|fuji|cardona|saigon|chiado|signet|mocha|blaze|curtis|bepolia).*$/, "");
+  return NATIVE_TOKEN_SYMBOLS[prefix] ?? "ETH";
+}
 
 // src/lib/onboarding.ts
 function hasAPIKey(cfg) {
@@ -275,6 +311,7 @@ function shouldRunOnboarding(program, cfg) {
 export {
   getRPCNetworks,
   getRPCNetworkIds,
+  nativeTokenSymbol,
   getSetupMethod,
   isSetupComplete,
   getSetupStatus,