---
title: "Quickstart: TypeScript"
description: "Install the TypeScript SDK from GitHub, run a pull worker on your machine, and start a run."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/cli/install), 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](/iam/api-keys)** 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:

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

## 1. Create a pull app

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

The output shows the app. Keep its ID:

```sh
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.

```sh
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.

```ts title="hello.ts"
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.

```ts title="worker.ts"
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()
```

```sh
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:

```ts title="start.ts"
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)
```

```sh
node start.ts
```

After about five seconds:

```text
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:

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

## Next

- [Concepts](/workflows/concepts): what replay means for your code.
- [Push and pull apps](/workflows/push-and-pull): serve workflows from an HTTPS endpoint instead.
- The [SDK's README](https://github.com/ezgamehost/workflows-sdk-ts#readme) lists its whole API.

Source: https://docs.ezghcloud.com/workflows/quickstart-typescript/index.mdx