@alchemy/cli 0.1.3 → 0.1.5

package/README.md

@@ -6,18 +6,17 @@ You can use API keys, access keys, or x402 wallet auth depending on the command.
 
 ## Installation
 
-The current repository workflow is source install:
+Install globally from npm:
 
 ```bash
-git clone https://github.com/alchemyplatform/alchemy-cli.git
-cd alchemy-cli
-pnpm install
-pnpm build
-pnpm link --global
+npm i -g @alchemy/cli
 ```
 
-This makes the `alchemy` command available globally.  
-To unlink later: `pnpm unlink --global`.
+Or run without installing globally:
+
+```bash
+npx @alchemy/cli <command>
+```
 
 ## Command Reference
 
@@ -283,9 +282,22 @@ Errors are structured JSON in JSON mode:
 
 Prerequisites:
 
-- [Node.js 18+](https://nodejs.org/)
+- [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
@@ -321,6 +333,50 @@ Coverage:
 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:

package/dist/index.js

@@ -1683,7 +1683,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.3").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.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(
   "-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({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alchemy/cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Alchemy CLI — interact with blockchain data",
   "type": "module",
   "bin": {
@@ -14,7 +14,8 @@
   ],
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "scripts/postinstall.cjs"
   ],
   "repository": {
     "type": "git",
@@ -25,7 +26,7 @@
   },
   "license": "MIT",
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "dependencies": {
     "@alchemy/x402": "^0.4.0",
@@ -34,6 +35,8 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@changesets/changelog-github": "^0.6.0",
+    "@changesets/cli": "^2.30.0",
     "@types/node": "^25.3.0",
     "@vitest/coverage-v8": "^4.0.18",
     "tsup": "^8.5.1",
@@ -44,10 +47,14 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
+    "postinstall": "node ./scripts/postinstall.cjs",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:e2e": "pnpm build && vitest run --config vitest.e2e.config.ts",
     "test:watch": "vitest",
-    "lint": "tsc --noEmit"
+    "lint": "tsc --noEmit",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "pnpm build && changeset publish"
   }
 }

package/scripts/postinstall.cjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+function isGlobalInstall() {
+  return process.env.npm_config_global === "true";
+}
+
+function isCI() {
+  return process.env.CI === "true";
+}
+
+if (isGlobalInstall() && !isCI()) {
+  // Keep this concise so it stays readable in npm install output.
+  console.log("");
+  console.log("◆ Alchemy CLI installed");
+  console.log("  Run `alchemy` to get started.");
+  console.log("");
+}