@eventpipe/cli 0.2.1 → 0.2.3

package/README.md

@@ -1,79 +1,179 @@
-# @eventpipe/cli
+# Event Pipe CLI
 
-Build **Event Pipe** code-node bundles with [esbuild](https://esbuild.github.io/), publish with an **API key**, and use **login / create / listen** against the dashboard (Supabase session + relay WebSocket).
+Official command-line tool for **[Event Pipe](https://eventpipe.app)** — bundle code nodes with [esbuild](https://esbuild.github.io/), **publish new pipeline versions**, create webhook endpoints, and stream events to your machine.
 
-## Install
+**Website:** [eventpipe.app](https://eventpipe.app) · **npm:** [`@eventpipe/cli`](https://www.npmjs.com/package/@eventpipe/cli)
+
+---
+
+## What you can do
+
+| Area | What the CLI does |
+|------|-------------------|
+| **Publish** | Run **`eventpipe push`** after **`eventpipe login`** to upload a new pipeline version (same API as Pipe Studio). |
+| **CI** | Set **`EVENTPIPE_API_KEY`** so **`push`** works without a browser. |
+| **Webhooks** | **`create`** endpoints and **`listen`** to the relay (with optional **`--forward-to`** for local replay). |
+| **Tooling** | **`eventpipe update`**, **`--version`**, and optional npm version hints on stderr. |
+
+---
+
+## Requirements
+
+- **Node.js 20 or newer** ([nodejs.org](https://nodejs.org))
+- An Event Pipe account ([sign up](https://eventpipe.app))
+- For **`push`**: a **pipeline** already created in the app, and its **`pipelineId`** (UUID) in **`eventpipe.json`**
+
+---
+
+## Installation
+
+### Global (recommended)
 
 ```bash
-pnpm add -D @eventpipe/cli
-# or: npm i -D @eventpipe/cli
+npm install -g @eventpipe/cli
 ```
 
-Global install (provides `eventpipe` and `eventpipe-cli`):
+This provides **`eventpipe`** and **`eventpipe-cli`** on your `PATH`.
+
+### Per project
 
 ```bash
-npm install -g @eventpipe/cli
+npm add -D @eventpipe/cli
 ```
 
-**macOS / Linux** — from a clone of this repo, installs globally (requires Node 20+ and `npm` on `PATH`):
+Run with **`npx eventpipe …`** or npm scripts.
+
+### Install scripts (from a clone of this repo)
+
+**macOS / Linux:** `bash install/macos.sh`  
+**Windows (PowerShell):** `Set-ExecutionPolicy -Scope Process Bypass; .\install\windows.ps1`
+
+### Develop from source
 
 ```bash
-bash install/macos.sh
+git clone <repo-url> && cd eventpipe-cli
+pnpm install && pnpm run build
+node dist/cli.js --help
 ```
 
-**Windows** — PowerShell:
+---
+
+## Publishing pipeline versions (`build` + `push`)
+
+Publishing creates a **new immutable version** of your pipeline by calling **`POST /api/account/pipelines/{pipelineId}/versions`** with bundled code — the same endpoint the [web app](https://eventpipe.app) uses.
+
+### 1. Get `pipelineId`
+
+In **Pipe Studio**, open your pipeline and copy its **UUID** from the URL or settings.
+
+### 2. Add `eventpipe.json` (minimal single code node)
 
-```powershell
-Set-ExecutionPolicy -Scope Process Bypass; .\install\windows.ps1
+The **`code`** node id in **`settings.pipe`** must match the code node you bundle (default file: **`src/handler.ts`**).
+
+```json
+{
+  "pipelineId": "YOUR_PIPELINE_UUID",
+  "settings": {
+    "pipe": {
+      "schemaVersion": 3,
+      "nodes": [
+        { "id": "code", "type": "code", "config": {} }
+      ],
+      "edges": []
+    }
+  }
+}
+```
+
+### 3. Handler entry (`src/handler.ts`)
+
+```typescript
+type FlowEvent = {
+  method: string;
+  headers: Record<string, string>;
+  body: unknown;
+};
+
+type FlowContext = { env?: Record<string, string> };
+
+export async function handler(event: FlowEvent, _context: FlowContext) {
+  return { ok: true, received: event.body };
+}
 ```
 
-From a git checkout:
+In production, secrets are read from **`context.env`** (set in the app **Event** tab), not from `process.env` inside the bundle.
+
+### 4. Sign in and push
 
 ```bash
-cd eventpipe-cli && pnpm install && pnpm run build
-# binaries: ./dist/cli.js
+eventpipe login
+eventpipe push
 ```
 
-## Project layout
+- **`login`** opens the browser and saves session under **`~/.eventpipe/credentials.json`**. Default app is **`https://eventpipe.app`** (override with **`EVENTPIPE_BASE_URL`** for self-hosted).
+- **`push`** runs **`build`** then uploads bundles. If **`EVENTPIPE_API_KEY`** is set, it is used **instead of** session (typical for **CI**).
 
-| File | Purpose |
-|------|---------|
-| `eventpipe.json` | `pipelineId`, optional `nodeId` / `entry`, and `settings` (must include `pipe` v3) |
-| `src/handler.ts` | Default entry — `export async function handler(event, context)` |
+### CI example
 
-Runtime uses **`context.env`** for secrets (configure values in the app **Event** tab), not `process.env`.
+```bash
+export EVENTPIPE_API_KEY=evp_xxxxxxxx
+# optional for self-hosted: export EVENTPIPE_BASE_URL=https://your-app.example.com
+eventpipe push --dir ./my-flow
+```
 
-## Commands
+### Override pipeline id
 
-### Auth & endpoints
+```bash
+eventpipe push --pipeline <uuid>
+# alias: --flow <uuid>
+```
+
+---
 
-- **`login`** — Opens the browser to complete Supabase login; saves `~/.eventpipe/credentials.json`. Uses `https://eventpipe.app` unless `EVENTPIPE_BASE_URL` is set.
-- **`create [--name <slug>]`** — `POST /api/account/endpoints` (session auth). `--name` sets the URL slug (`/api/webhook/your-slug`) if it’s free; otherwise a random id is used. With no `--name`, the URL and display label are random.
-- **`listen <webhookId> [options]`** — Connects to the relay; prints one line per webhook. **`--verbose` / `-v`** prints the full event JSON (method, headers, query, body). **`--json`** prints one JSON object per line (stdout) for scripts. **`--forward-to http://127.0.0.1:PORT/path`** replays each request to your local server (forward status on stderr).
+## Other commands (summary)
 
-### Bundles
+| Command | Purpose |
+|---------|---------|
+| **`eventpipe login`** | Browser sign-in; stores session. |
+| **`eventpipe create [--name <slug>]`** | New webhook endpoint (requires login). |
+| **`eventpipe listen <id> [--json] [-v] [--forward-to <url>]`** | Stream webhooks from the relay. |
+| **`eventpipe build [--dir <path>]`** | Esbuild → `.eventpipe/`; prints size and hash (max **200KB** per bundle). |
+| **`eventpipe update`** | Runs **`npm install -g @eventpipe/cli@latest`**. |
+| **`eventpipe -v` / `--version`** | Print CLI version. |
+| **`eventpipe help`** | Built-in usage. |
 
-- **`build`** — Writes `.eventpipe/*.bundle.js` and prints size + sha256 (must be ≤ 200KB).
-- **`push`** — Runs `build`, then `POST /api/account/pipelines/:pipelineId/versions` with `codeBundles`.
+---
+
+## Project layout
 
-### Environment
+| File / folder | Role |
+|---------------|------|
+| **`eventpipe.json`** | **`pipelineId`**, **`settings.pipe`** (v3), optional **`nodeId`**, **`entry`**, or **`codeNodes`** for multi-file graphs. |
+| **`src/handler.ts`** | Default entry when **`entry`** is omitted. |
+| **`.eventpipe/`** | Generated bundles (from **`build`** / **`push`**). |
 
-| Variable | Used by | Description |
-|----------|---------|-------------|
-| `EVENTPIPE_BASE_URL` | login, push | Origin of the Next app (default `https://eventpipe.app`; no trailing slash) |
-| `EVENTPIPE_API_KEY` | push | Plaintext key from account API keys (`evp_...`) |
+---
 
-Optional: `--pipeline <uuid>` (or `--flow`) overrides `pipelineId` in `eventpipe.json` for `push`.
+## Update hints
 
-### Server requirements for `listen`
+After most commands, the CLI may check npm for a newer **`@eventpipe/cli`** and print a short message on **stderr** suggesting **`eventpipe update`**. Set **`EVENTPIPE_SKIP_UPDATE_CHECK=1`** to disable (e.g. in CI).
 
-The app needs a deployed **eventpipe-relay** (or compatible) service plus env vars documented in the app `.env.example`: `EVENTPIPE_RELAY_URL`, `EVENTPIPE_RELAY_WS_URL`, `EVENTPIPE_RELAY_INGEST_SECRET`, `EVENTPIPE_LISTEN_JWT_SECRET` (shared with the relay).
+---
 
 ## Example
 
-See `examples/stripe-webhook` (Stripe Balance via REST to stay under the bundle size cap).
+See **`examples/stripe-webhook`** for a fuller project (multi-node **`codeNodes`** example).
+
+---
 
 ## Limits
 
-- One **code node** per project in this CLI version (multi-node flows: publish from the dashboard or extend the CLI).
-- Per-node bundle max **200KB** UTF-8 (same as the server).
+- **Single-code-node** workflows are the simplest; multi-node graphs may need a **`codeNodes`** map or publishing from the [dashboard](https://eventpipe.app).
+- **200KB** UTF-8 per code-node bundle (same as the server).
+
+---
+
+## Getting help
+
+- **Product:** [eventpipe.app](https://eventpipe.app) — platform docs include **CLI** and **API reference**.
+- **This repo:** `eventpipe help`

package/dist/cli.js

@@ -8,6 +8,7 @@ import { publishVersion } from "./publish.js";
 import { applyPublishedStudioSources, codeNodeUsesLibrary } from "./studio-sources.js";
 import { cmdLogin } from "./cmd-login.js";
 import { cmdCreate } from "./cmd-create.js";
+import { loadCredentials } from "./credentials.js";
 import { resolveEventpipeBaseUrl } from "./base-url.js";
 import { fetchLatestPublishedVersion, isPublishedVersionNewer, readInstalledCliVersion, } from "./cli-version.js";
 import { cmdUpdate } from "./cmd-update.js";
@@ -18,7 +19,7 @@ function usage() {
 
 Environment:
   EVENTPIPE_BASE_URL   App origin (default: https://eventpipe.app); override for self-hosted
-  EVENTPIPE_API_KEY    Account API key (x-api-key) for push when not using session
+  EVENTPIPE_API_KEY    Optional; for push in CI/automation (overrides session if set)
   EVENTPIPE_SKIP_UPDATE_CHECK   Set to 1 to disable the npm version hint on stderr
 
 Commands:
@@ -28,7 +29,7 @@ Commands:
                          Stream webhooks; --verbose prints full JSON event; --json one NDJSON line per event;
                          --forward-to replays the request to your local server (status on stderr)
   build [--dir <path>]   Bundle TS into .eventpipe/
-  push [--dir <path>]    build + POST /api/account/pipelines/:id/versions (needs EVENTPIPE_API_KEY)
+  push [--dir <path>]    build + publish (session after login, or EVENTPIPE_API_KEY)
   update                 npm install -g @eventpipe/cli@latest
   help
 
@@ -102,11 +103,19 @@ async function cmdBuild(projectDir) {
     }
 }
 async function cmdPush(projectDir, pipelineOverride) {
-    const base = resolveEventpipeBaseUrl();
     const key = process.env.EVENTPIPE_API_KEY?.trim();
-    if (!key) {
-        throw new Error("EVENTPIPE_API_KEY is required for push");
+    const cred = await loadCredentials();
+    let auth = null;
+    if (key) {
+        auth = { type: "apiKey", apiKey: key };
     }
+    else if (cred) {
+        auth = { type: "session", cred };
+    }
+    if (!auth) {
+        throw new Error("Run eventpipe login first, or set EVENTPIPE_API_KEY for push (e.g. in CI)");
+    }
+    const base = auth.type === "session" ? auth.cred.baseUrl : resolveEventpipeBaseUrl();
     const manifest = await loadManifest(projectDir);
     const pipelineId = pipelineOverride ?? manifest.pipelineId;
     const pipe = manifest.settings.pipe;
@@ -145,7 +154,7 @@ async function cmdPush(projectDir, pipelineOverride) {
         : null;
     const result = await publishVersion({
         baseUrl: base,
-        apiKey: key,
+        auth,
         pipelineId,
         manifest: manifestForPublish,
         bundles,

package/dist/publish.d.ts

@@ -1,4 +1,5 @@
 import type { EventpipeManifest } from "./config.js";
+import type { StoredCredentials } from "./credentials.js";
 export type PublishResult = {
     success?: boolean;
     version?: number;
@@ -6,9 +7,16 @@ export type PublishResult = {
     bundleSizeBytes?: number;
     error?: string;
 };
+export type PublishAuth = {
+    type: "apiKey";
+    apiKey: string;
+} | {
+    type: "session";
+    cred: StoredCredentials;
+};
 export declare function publishVersion(params: {
     baseUrl: string;
-    apiKey: string;
+    auth: PublishAuth;
     pipelineId: string;
     manifest: EventpipeManifest;
     bundles: Array<{

package/dist/publish.js

@@ -1,20 +1,34 @@
+import { fetchWithSession } from "./auth-fetch.js";
 export async function publishVersion(params) {
-    const res = await fetch(`${params.baseUrl}/api/account/pipelines/${params.pipelineId}/versions`, {
-        method: "POST",
-        headers: {
-            "content-type": "application/json",
-            "x-api-key": params.apiKey,
+    const url = `${params.baseUrl}/api/account/pipelines/${params.pipelineId}/versions`;
+    const body = JSON.stringify({
+        sourceCode: params.sourceCode ?? null,
+        buildMeta: {
+            bundler: "eventpipe-cli",
+            generatedAt: new Date().toISOString(),
         },
-        body: JSON.stringify({
-            sourceCode: params.sourceCode ?? null,
-            buildMeta: {
-                bundler: "eventpipe-cli",
-                generatedAt: new Date().toISOString(),
-            },
-            settings: params.manifest.settings,
-            codeBundles: params.bundles,
-        }),
+        settings: params.manifest.settings,
+        codeBundles: params.bundles,
     });
+    let res;
+    if (params.auth.type === "apiKey") {
+        res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "x-api-key": params.auth.apiKey,
+            },
+            body,
+        });
+    }
+    else {
+        const out = await fetchWithSession(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body,
+        }, params.auth.cred);
+        res = out.response;
+    }
     const data = (await res.json());
     if (!res.ok) {
         return { error: data?.error ?? res.statusText };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@eventpipe/cli",
-  "version": "0.2.1",
-  "description": "Build and publish Event Pipe flow bundles (API key auth)",
+  "version": "0.2.3",
+  "description": "Build and publish Event Pipe flow bundles (session or API key)",
   "type": "module",
   "bin": {
     "eventpipe": "./dist/cli.js",