workflow 5.0.0-beta.5 → 5.0.0-beta.50

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

@@ -0,0 +1,241 @@
+---
+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.

package/docs/configuration/framework-options.mdx

@@ -0,0 +1,165 @@
+---
+title: Framework Options
+description: Build-time and dev-server configuration for Workflow framework integrations.
+type: reference
+summary: Configure Workflow through framework plugins and module options.
+related:
+  - /docs/api-reference/workflow-next/with-workflow
+  - /docs/configuration/build-and-diagnostics
+---
+
+Framework options are read at build or dev-server startup. Use them for settings that belong in source control, such as source-map behavior or framework-specific output paths.
+
+## Next.js
+
+`withWorkflow()` accepts an optional second argument.
+
+### `workflows.local.port`
+
+- Environment override: `PORT`
+- Default: auto-detected
+- Local-only. Sets the application port used by the Local World when queue messages call back into the app.
+- The option writes `PORT` for non-Vercel builds.
+
+### `workflows.sourcemap`
+
+- Environment override: `WORKFLOW_SOURCEMAP`
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+- Explicit config wins over `WORKFLOW_SOURCEMAP`.
+
+```typescript title="next.config.ts" lineNumbers
+import { withWorkflow } from "workflow/next";
+
+export default withWorkflow(
+  {},
+  {
+    workflows: {
+      local: {
+        port: 4000,
+      },
+      sourcemap: false,
+    },
+  }
+);
+```
+
+## Nitro and Nuxt
+
+Configure Workflow through the Nitro `workflow` module options.
+
+### `workflow.dirs`
+
+- Environment override: none
+- Default: `["workflows"]`
+- Directories scanned for workflow files.
+
+### `workflow.typescriptPlugin`
+
+- Environment override: none
+- Default: `false` for raw Nitro, `true` through the Nuxt module
+- Enables the Workflow TypeScript language-service plugin in generated `tsconfig.json`.
+- This affects editor diagnostics and completions. Workflow builds do not require it.
+- Raw Nitro leaves it opt-in because it changes TypeScript editor behavior. Nuxt enables it by default because the Nuxt module owns the generated `tsconfig.json` flow.
+
+### `workflow.runtime`
+
+- Environment override: none
+- Default: framework default
+- Node.js runtime emitted for Vercel Functions, such as `nodejs22.x` or `nodejs24.x`.
+
+### `workflow.sourcemap`
+
+- Environment override: `WORKFLOW_SOURCEMAP`
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+
+## NestJS
+
+Configure Workflow through `WorkflowModule.forRoot()`.
+
+### `workingDir`
+
+- Environment override: none
+- Default: `process.cwd()`
+- Application root used for workflow discovery and bundling.
+
+### `dirs`
+
+- Environment override: none
+- Default: `["src"]`
+- Directories scanned for workflow files.
+
+### `outDir`
+
+- Environment override: none
+- Default: `.nestjs/workflow`
+- Directory for generated workflow bundles.
+
+### `watch`
+
+- Environment override: none
+- Default: `false`
+- Rebuilds workflow bundles during development.
+
+### `moduleType`
+
+- Environment override: none
+- Default: `es6`
+- Set to `commonjs` when the Nest app compiles TypeScript to CJS through SWC.
+
+### `distDir`
+
+- Environment override: none
+- Default: `dist`
+- Compiled JavaScript output directory used by the CJS import rewrite.
+
+### `sourcemap`
+
+- Environment override: `WORKFLOW_SOURCEMAP`
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+
+### `skipBuild`
+
+- Environment override: none
+- Default: `false`
+- Skips bundle generation when bundles are already pre-built.
+
+## Astro
+
+### `sourcemap`
+
+- Environment override: `WORKFLOW_SOURCEMAP`
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+
+## SvelteKit
+
+### `sourcemap`
+
+- Environment override: `WORKFLOW_SOURCEMAP`
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+
+## Rollup
+
+### `exclude`
+
+- Environment override: none
+- Default: `[]`
+- Path prefixes skipped by the directive transform.
+
+## Source-map values
+
+`WORKFLOW_SOURCEMAP` accepts these values:
+
+- `true`, `inline`, or `1` - append an inline base64 source map to each generated bundle.
+- `linked` - write a `.map` file and add a `sourceMappingURL` comment.
+- `external` - write a `.map` file without adding the comment.
+- `both` - emit inline and external source maps.
+- `false` or `0` - omit source maps.
+
+<Callout type="info">
+The legacy `WORKFLOW_EMIT_SOURCEMAPS_FOR_DEBUGGING=1` variable still works, but it only affects the final workflow wrapper and webhook bundle. Prefer `WORKFLOW_SOURCEMAP` or a framework `sourcemap` option.
+</Callout>

package/docs/configuration/index.mdx

@@ -0,0 +1,32 @@
+---
+title: Configuration
+description: Reference for Workflow SDK configuration options, environment variables, and CLI overrides.
+type: conceptual
+summary: Configure framework integrations, Worlds, runtime tuning, builds, and CLI observability.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/configuration/framework-options
+  - /docs/configuration/worlds
+  - /docs/configuration/runtime-tuning
+  - /docs/configuration/build-and-diagnostics
+  - /docs/configuration/cli-and-web-ui
+---
+
+Workflow SDK is configured through typed framework options, World factory options, environment variables, and CLI flags.
+
+When more than one surface controls the same setting, the usual precedence is:
+
+```txt
+explicit option or CLI flag > environment variable > built-in default
+```
+
+Invalid environment variable values do not crash the app. They log a warning and fall back to the default, or to the documented clamp range.
+
+## Configuration areas
+
+- [Framework options](/docs/configuration/framework-options) - build-time and dev-server options for Next.js, Nitro, NestJS, Astro, SvelteKit, and Rollup.
+- [Worlds](/docs/configuration/worlds) - `WORKFLOW_TARGET_WORLD`, Local World, Postgres World, and Vercel World configuration.
+- [Runtime tuning](/docs/configuration/runtime-tuning) - replay budgets, inline execution, queue delivery limits, compression, tracing, and advanced runtime escape hatches.
+- [Build and diagnostics](/docs/configuration/build-and-diagnostics) - public manifests, HMR logs, and source-map controls.
+- [CLI and web UI](/docs/configuration/cli-and-web-ui) - `workflow inspect`, `workflow web`, `workflow health`, and observability environment overrides.

package/docs/configuration/meta.json

@@ -0,0 +1,12 @@
+{
+  "title": "Configuration",
+  "pages": [
+    "index",
+    "framework-options",
+    "worlds",
+    "runtime-tuning",
+    "build-and-diagnostics",
+    "cli-and-web-ui"
+  ],
+  "defaultOpen": false
+}