workflow/docs/configuration/cli-and-web-ui.mdx

Workflow SDK - Build durable, resilient, and observable workflows

---
title: CLI and Web UI
description: CLI flags and environment variables for inspecting local, Postgres, and Vercel Workflow runs.
type: reference
summary: Configure workflow inspect, workflow cancel, workflow web, workflow health, and observability tooling.
related:
  - /docs/observability
  - /docs/configuration/worlds
---

The Workflow CLI uses flags first, then environment variables, then defaults or local inference.

Vercel project and auth settings can often be inferred from `.vercel/project.json` and your Vercel CLI login.

## Target backend

### `--backend` / `-b`

- Environment variable: `WORKFLOW_TARGET_WORLD`
- Default: `local`
- Backend to inspect: `local`, `vercel`, or a World package.

### `--authToken` / `-a`

- Environment variable: `WORKFLOW_VERCEL_AUTH_TOKEN`
- Default: Vercel CLI login
- Vercel token for `--backend vercel`.

### `--project`

- Environment variable: `WORKFLOW_VERCEL_PROJECT`
- Default: inferred when possible
- Vercel project ID for `--backend vercel`.

### `--team`

- Environment variable: `WORKFLOW_VERCEL_TEAM`
- Default: inferred when possible
- Vercel team ID for `--backend vercel`.

### `WORKFLOW_VERCEL_PROJECT_NAME`

- CLI flag: none
- Default: inferred when possible
- Vercel project slug used for dashboard links.

### `--env` / `-e`

- Environment variable: `WORKFLOW_VERCEL_ENV`
- Default: `production`
- Vercel environment for `--backend vercel`.
- Accepts `production` or `preview`.

## Web UI

### `--web` / `-w`

- Environment variable: none
- Default: disabled
- Opens the relevant dashboard or web user interface (UI) instead of printing terminal output.

### `--webPort`

- Environment variable: `WORKFLOW_WEB_PORT`
- Default: `3456`
- Port for the local web UI server.

### `--noBrowser`

- Environment variable: `WORKFLOW_DISABLE_BROWSER_OPEN`
- Default: browser opens
- Prevents the CLI from opening a browser for web UI commands.

### `--localUi`

- Environment variable: `WORKFLOW_LOCAL_UI`
- Default: disabled
- Uses the local web UI instead of the Vercel dashboard when inspecting Vercel.

### `--url`

- Environment variable: none
- Default: disabled
- Prints the dashboard or run deep-link URL instead of opening a browser or starting a local server.

## Output and filtering

### `--json` / `-j`

- Environment variable: none
- Default: disabled
- Prints machine-readable JSON where the command supports it.

### `--sort`

- Environment variable: none
- Default: `desc` for time-ordered listings; `workflow inspect attributes` orders keys alphabetically unless you pass this flag
- Sort order for list commands. Accepts `asc` or `desc`.

### `--limit`

- Environment variable: none
- Default: `20`
- Number of items returned per page for list commands. `workflow cancel` bounds it separately; see [`--limit` (cancel)](#--limit-cancel).

### `--cursor`

- Environment variable: none
- Default: unset
- Pagination cursor for list commands.

### `--interactive` / `-i`

- Environment variable: none
- Default: disabled
- Enables keyboard-controlled pagination for supported list commands.

## Inspect filtering

Flags for `workflow inspect`. Each list view accepts a different subset, noted
per flag.

### `--runId` / `-r`

- Command: `workflow inspect`
- Default: unset
- Scopes the listing to one run. Required for `steps`, `events`, and `sleeps`; optional for `hooks`. Must be a run ID: `wrun_` followed by a 26-character ULID.

### `--limit` (inspect)

- Command: `workflow inspect`
- Default: `20`
- Must be an integer between 1 and 100, the smallest page any inspect listing accepts. Larger pages are reachable by paging: pass `--cursor`, or `--interactive` to walk them.

### `--stepId` / `-s`

- Command: `workflow inspect events`
- Default: unset
- Filters events to one step.

### `--hookId`

- Command: `workflow inspect events`
- Default: unset
- Filters events to one hook.

### `--attribute`

- Command: `workflow inspect runs`
- Default: unset
- Filters runs to those whose [attributes](/docs/observability/attributes) match every `key=value` pair given. Repeatable up to 8 times, and splits on the first `=` so a value may contain one.
- Requires a backend with the analytics read path; ignored with a warning otherwise.
- Cannot be combined with `--url` or `--web`, which hand off to the dashboard, or with `--withData`, which reads payloads from storage. Storage carries no attribute index.
- Use `workflow inspect attributes` to discover which keys exist.

### `--since` / `--until`

- Command: `workflow inspect runs`, `workflow inspect attributes`
- Default: the backend's own window
- Bounds the listing to a window. `--since` opens the window and accepts a relative duration (`30m`, `12h`, `7d`, `2w`) or a timestamp. `--until` is optional and defaults to now, so `--until` on its own is rejected.
- Requires a backend with the analytics read path; ignored with a warning otherwise.

### `--withData` / `-d`

- Command: `workflow inspect`
- Default: disabled
- Includes full input and output payloads in list views. Deprecated for list views — use `workflow inspect <resource> <id>` to read one item's payloads. Setting it also moves the read off the analytics path, which carries metadata only.

### `--decrypt`

- Command: `workflow inspect`
- Default: disabled
- Decrypts encrypted values. Triggers an audit-logged key retrieval.

## Bulk cancel

`workflow cancel <run-id>` cancels one run. Given a filter instead, it bulk-cancels a batch; bulk mode requires `--status` or `--workflowName`.

### `--status`

- Command: `workflow cancel`
- Default: unset
- Restricts the batch to this status. Only `pending` and `running` are accepted; terminal runs cannot be canceled.
- Also filters `workflow inspect runs`, which accepts any run status. It does not narrow `workflow inspect attributes`, which indexes keys per tenant rather than per run; passing it there warns and lists every key.

### `--workflowName` / `-n`

- Command: `workflow cancel`
- Default: unset
- Restricts the batch to one workflow. Expects the generated workflow ID from `workflow inspect runs`, not the short function name.
- Also filters `workflow inspect runs` and `workflow inspect attributes`.

### `--limit` (cancel)

- Command: `workflow cancel`
- Default: `50`
- Maximum runs to cancel in one batch (1–100), the largest page the run listing serves. Only one batch is canceled per invocation; run the command again to cancel the next batch.

### `--confirm` / `-y`

- Command: `workflow cancel`
- Default: disabled
- Skips the interactive confirmation prompt.

## Health checks

### `--port` / `-p`

- Command: `workflow health`
- Environment variable: `WORKFLOW_LOCAL_BASE_URL`, then `PORT`
- Default: `3000` when neither env var is set
- Local server port for health checks.
- The flag writes `WORKFLOW_LOCAL_BASE_URL`.

## Verbose logging and updates

### `--verbose` / `-v`

- Environment variable: `DEBUG`
- Default: disabled
- Enables verbose CLI output.

### `WORKFLOW_NO_UPDATE_CHECK`

- CLI flag: none
- Default: update check enabled
- Set `1` to disable the CLI update check.

## Observability paths

### `WORKFLOW_OBSERVABILITY_CWD`

- CLI flag: none
- Default: `process.cwd()`
- Working directory used by observability tooling to find `.vercel`, `.workflow-data`, and manifests.

### `WORKFLOW_MANIFEST_PATH`

- CLI flag: none
- Default: inferred
- Explicit path to the workflow manifest for the web UI.