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. In a monorepo, the CLI uses the nearest `.vercel/project.json` before the repository's `.vercel/repo.json`.

Whichever way they are resolved, the CLI ends up building a Vercel World from an auth token plus a project ID, team ID, and environment — the same four values any external client needs. Set them explicitly when there is no interactive `vercel login` to infer from, or when writing your own script instead of using the CLI; see [Connecting from outside a deployment](/worlds/vercel#connecting-from-outside-a-deployment).

## 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 or slug for `--backend vercel`.
- Takes precedence over the project in the `.vercel` link. When `--project` names a different project, pass `--team` too, or the CLI uses the linked team and logs a warning.

### `--team`

- Environment variable: `WORKFLOW_VERCEL_TEAM`
- Default: inferred when possible
- Vercel team ID for `--backend vercel`.
- Takes precedence over the team in the `.vercel` link.

### `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`; any other value, including one set through `WORKFLOW_VERCEL_ENV`, is rejected. To reach a custom environment, configure the World programmatically with the environment's slug instead; see [Connecting from outside a deployment](/worlds/vercel#connecting-from-outside-a-deployment).

## 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. A `workflow inspect` listing that stops with more rows prints the next page's cursor: in its `--json` page object for `runs`, `hooks`, and `attributes`, and on stderr for `steps`, `events`, and `sleeps`, whose `--json` output is an array.

### `--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.
- Also required to read one step, event, or stream, as in `workflow inspect step <step-id> --runId=<run-id>`: their IDs and names are scoped to their run.

### `--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`, `--all` to read every page, or `--interactive` to walk them.

### `--all`

- Command: `workflow inspect steps`, `workflow inspect events`, `workflow inspect sleeps`
- Default: disabled
- Follows cursors to the last page and prints every row: one table, or with `--json` one array. `--limit` sets the size of each page it fetches and `--cursor` where it starts.
- Cannot be combined with `--interactive`, an ID, or `--url`/`--web`. The `runs`, `hooks`, and `attributes` listings take `--cursor` instead: their `--json` output carries it.

### `--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 --json`, not the short function name.
- Also filters `workflow inspect runs` and `workflow inspect attributes`. These also accept the short name the runs table shows, such as `processOrder`: it is looked up among the workflows of the 500 most recent runs (in the `--since` window when given) and replaced by the full name. A short name that more than one of those workflows share is rejected with the candidates, and one that none of them has is used as given.

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

### `--base-path`

- Command: `workflow health`
- Environment variable: none
- Default: unset, so the check targets `/.well-known/workflow/v1/flow` at the server root
- Path the workflow routes are served under on the local server: Next.js' `basePath` followed by [`workflows.experimentalRoutePrefix`](/docs/api-reference/workflow-next/with-workflow#workflow-route-prefix). For example, `--base-path /v2/dashboard` checks `/v2/dashboard/.well-known/workflow/v1/flow`.
- Appended to the URL from `--port`, `WORKFLOW_LOCAL_BASE_URL` or `PORT`.

## 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.
- Inferred from `app/`, `src/app/` and `.well-known/` at the project root first, then from a manifest generated below a [route prefix](/docs/api-reference/workflow-next/with-workflow#workflow-route-prefix), such as `app/dashboard/.well-known/workflow/v1/manifest.json`. Set it when more than one prefixed manifest exists.