Quickstart: TypeScript

This quickstart runs a workflow on your own machine: you create a pull app, run a worker that polls EZGH for work, and start a run from a script. Nothing needs a public endpoint. It takes about five minutes.

Before you start

• Node.js 22.18 or later, which runs the TypeScript files below directly. The SDK itself works on Node.js 20 or later, Bun, Deno and Cloudflare Workers.
• The ezgh CLI, version 0.16.0 or later (install it, or run ezgh update), logged in.
• An organization ID and a project ID. Run ezgh whoami for the organization and ezgh projects list for the project, or copy them from the console. The SDKs take IDs, not slugs.
• An API key whose owner has WorkflowsFullAccess on the project, or the root user’s. Create one with ezgh iam api-keys create workflows-quickstart.

Set them in your shell:

export EZGH_API_KEY=ezgh_…
export EZGH_ORG_ID=<org-id>
export EZGH_PROJECT_ID=<project-id>

1. Create a pull app

ezgh workflows apps create quickstart --kind pull --project "$EZGH_PROJECT_ID"

The output shows the app. Keep its ID:

export EZGH_APP_ID=<ID>

2. Install the SDK

The SDK isn’t published to npm yet. Install it from GitHub by tag; npm builds it as it installs, and may warn that the package has an install script.

mkdir workflows-quickstart && cd workflows-quickstart
npm init -y && npm pkg set type=module
npm install github:ezgamehost/workflows-sdk-ts#v0.1.1

It imports as @ezgh/workflows.

3. Write a workflow

hello.ts defines a workflow named hello with three steps: it computes a greeting, sleeps for five seconds, and records the time.

import { workflow } from "@ezgh/workflows"

export const hello = workflow<{ name: string }>("hello", async ({ input, step }) => {
  const greeting = await step.run("greet", () => `Hello, ${input.name}!`)
  await step.sleep("pause", "5s")
  const at = await step.now("finished-at")
  return { greeting, at }
})

4. Run a worker

worker.ts polls the app’s task queue and runs the workflows you give it. Each poll also tells EZGH which workflows this worker serves.

import { worker } from "@ezgh/workflows"
import { hello } from "./hello.ts"

const w = worker({
  apiKey: process.env.EZGH_API_KEY!,
  organizationId: process.env.EZGH_ORG_ID!,
  projectId: process.env.EZGH_PROJECT_ID!,
  app: process.env.EZGH_APP_ID!,
  workflows: [hello],
})
process.on("SIGINT", () => void w.stop())
console.log("Worker polling. Press Ctrl+C to stop.")
await w.run()

node worker.ts

Leave it running.

5. Start a run

In a second terminal with the same environment variables, start.ts starts a run, checks it every second until it ends, and prints its output:

import { Client } from "@ezgh/workflows"

const client = new Client({
  apiKey: process.env.EZGH_API_KEY!,
  organizationId: process.env.EZGH_ORG_ID!,
  projectId: process.env.EZGH_PROJECT_ID!,
})
let run = await client.start(process.env.EZGH_APP_ID!, "hello", { name: "Ada" })
console.log("Started run", run.id)
while (run.status === "running") {
  await new Promise((resolve) => setTimeout(resolve, 1000))
  run = await client.get(run.id)
}
console.log(run.status, run.status === "completed" ? await client.output(run.id) : run.error)

node start.ts

After about five seconds:

Started run 600c5dfd-ab16-8174-aba7-3380eddc2510
completed { greeting: 'Hello, Ada!', at: '2026-10-11T20:27:14.976Z' }

The worker ran the workflow twice: once up to the sleep, and again after it, when the greet step returned its recorded result without running again.

A pull app starts runs only of workflows that one of its workers announced in the last 10 minutes. Starting a run with no worker running answers 409 workflow_not_announced.

6. Clean up

Stop the worker with Ctrl+C, then delete the app and, if you made one for this, the API key:

ezgh workflows apps delete quickstart --project "$EZGH_PROJECT_ID"
unset EZGH_API_KEY
ezgh iam api-keys delete workflows-quickstart

Next

• Concepts: what replay means for your code.
• Push and pull apps: serve workflows from an HTTPS endpoint instead.
• The SDK’s README lists its whole API.