Configuration

CLI and Web UI

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.

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.

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

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).

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

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.
PreviousBuild and DiagnosticsNextAPI Reference