CLI

Overview

The CLI mirrors what you can do in the dashboard for day-to-day workflows: sign in, create webhook endpoints, stream captured traffic to your machine, compile TypeScript handlers, and publish immutable pipeline versions.

• Account: browser sign-in (login) with credentials stored locally for later commands.
• Webhooks: create endpoints (create) and subscribe to the relay in real time (listen), including optional HTTP replay to a local URL.
• Bundles: compile each code entry to .eventpipe/ (build) with size and sha256 output.
• Deploy: publish a new pipeline version (push) using the same authenticated session as the app.
• Tooling: print the installed version (--version), upgrade the CLI (update), and optional npm “newer version” hints on stderr after most commands.

When to use it

Use the CLI for repeatable builds from Git, CI, or fast local iteration. Publishing from Pipe Studio remains fully supported; the CLI keeps eventpipe.json and your handler sources in the repo and fits automation that already runs Node on a runner.

Requirements

• Node.js 20+ is required.
• An eventpipe account (sign up at the app).
• For build and push: an eventpipe.json at the project root with pipelineId and settings.pipe (schema v3).
• For create, listen, and push: run eventpipe login first (unless you already logged in on this machine).

Installation

• Global (recommended): npm install -g @eventpipe/cli — provides the eventpipe and eventpipe-cli commands on your PATH.
• As a dev dependency: npm add -D @eventpipe/cli, then npx eventpipe … or npm scripts.

npm install -g @eventpipe/cli

npm add -D @eventpipe/cli
npx eventpipe --version

Authentication

login opens the browser to authenticate with the same account as the web app. Session tokens are written to disk and reused by create, listen, and push. There is no separate API-key-only path in the CLI—use the saved session from login.

• Default app base URL is https://eventpipe.app. For self-hosted deployments, set EVENTPIPE_BASE_URL to your app origin (no trailing slash) before login.
• Credentials path: ~/.eventpipe/credentials.json on Unix; under your user profile on Windows.
• Required before create, listen, and push (unless a valid session already exists).

export EVENTPIPE_BASE_URL=https://your-app.example
# optional; omit for eventpipe.app
eventpipe login

Quick start

eventpipe create --name my-endpoint
eventpipe listen <webhookId>

eventpipe login
eventpipe build   # optional; push runs build
eventpipe push

Project layout & manifest

The pipeline id in eventpipe.json is the Pipe Studio pipeline UUID, not the webhook endpoint id. In Pipe Studio → Event → IDs for CLI & API, copy Pipeline id into pipelineId. Webhook endpoint id is used in /webhook/… URLs and with listen.

For a single code node, the code node id in settings.pipe must match the node you bundle (default entry file: src/handler.ts). For multiple code nodes, provide a codeNodes map: entry path → node id.

• Optional fields: nodeId and entry (single entry shorthand), or codeNodes (multi-entry map).
• Generated output lives under .eventpipe/ after build or push.
• Production secrets are read from context.env in the handler, configured in the app Event tab—not from process.env inside the bundle.

{
  "pipelineId": "YOUR_PIPELINE_UUID",
  "settings": {
    "pipe": {
      "schemaVersion": 3,
      "nodes": [
        { "id": "code", "type": "code", "config": {} }
      ],
      "edges": []
    }
  }
}

{
  "pipelineId": "YOUR_PIPELINE_UUID",
  "codeNodes": {
    "src/handler.ts": "FIRST_CODE_NODE_ID",
    "src/other.ts": "SECOND_CODE_NODE_ID"
  },
  "settings": {
    "pipe": {
      "schemaVersion": 3,
      "nodes": [
        { "id": "FIRST_CODE_NODE_ID", "type": "code", "config": {} },
        { "id": "SECOND_CODE_NODE_ID", "type": "code", "config": {} }
      ],
      "edges": []
    }
  }
}

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 };
}

build

Reads eventpipe.json from the current directory or from --dir. Bundles each configured entry with esbuild into .eventpipe/ and prints byte size, sha256 prefix, and output paths. Each bundle must stay within the plan size limit (typically 200KB UTF-8), enforced locally and on the server.

• Flags: --dir <path> to point at another project root.
• If multiple code nodes exist and codeNodes is not set, the CLI resolves a single entry when possible; otherwise you must set codeNodes (or nodeId + entry) explicitly.

eventpipe build
eventpipe build --dir ./packages/api

push

Runs the same bundling as build, then POSTs code bundles and settings to create a new immutable pipeline version. Authentication uses only the saved session from login.

• Flags: --dir <path>; --pipeline <uuid> or --flow <uuid> to override pipelineId from eventpipe.json for this run only.
• On success, the CLI prints the pipeline id, new version number, and total bundle size.

eventpipe push
eventpipe push --pipeline 00000000-0000-0000-0000-000000000000
eventpipe push --dir ./my-pipeline

create

Creates a new webhook endpoint under your account. Requires login.

• Optional --name <slug> requests a URL slug; if it is taken, the CLI may assign a different id and warn you.
• Output includes the webhook URL and id—use the id with listen.

eventpipe create
eventpipe create --name my-endpoint

listen

Streams captured webhooks for the given webhook endpoint id through the relay. Requires login. The hosted deployment must expose a compatible relay (default product behavior).

eventpipe listen abc123
eventpipe listen abc123 -v
eventpipe listen abc123 --json | jq .
eventpipe listen abc123 --forward-to http://127.0.0.1:3000/webhook

MCP for AI agents

The CLI includes a built-in MCP (Model Context Protocol) server so AI agents in Cursor, Claude Code, Claude Desktop, or any MCP-compatible client can inspect and debug your pipelines directly. One command creates an API key, saves credentials to ~/.eventpipe/mcp.json, and merges the same server entry into each editor config you choose.

eventpipe login
eventpipe mcp setup
eventpipe mcp setup --client cursor

update

Runs npm install -g @eventpipe/cli@latest (npm on Windows uses npm.cmd). Use this after the CLI suggests a newer version on stderr.

Version, help, and update hints

• eventpipe --version or eventpipe -v prints the installed package version.
• eventpipe, eventpipe help, or eventpipe --help prints usage (banner, commands, environment).
• After most commands, the CLI may query npm for a newer @eventpipe/cli and print a short hint on stderr. Set EVENTPIPE_SKIP_UPDATE_CHECK=1 to disable (recommended for noisy CI logs).

Environment variables

Limits & automation

Each code-node bundle must respect your plan’s size cap (commonly 200KB). Multi-code-node pipelines need every node mapped via codeNodes (or an unambiguous single-node layout); large graphs can also be published from Pipe Studio.

For CI, run login on a secure runner or restore credentials into ~/.eventpipe before push; treat that directory like any other secret material.

• Tier limits for pipelines, timeouts, and HTTP steps are summarized on Pricing.
• The publish contract matches POST /api/account/pipelines/{id}/versions in the API reference.