workflow/docs/observability/index.mdx

Workflow SDK - Build durable, resilient, and observable workflows

---
title: Observability
description: Inspect, monitor, and debug workflows through the CLI and web UI.
type: overview
summary: Inspect and debug workflow runs using the CLI and web UI.
prerequisites:
  - /docs/foundations
related:
  - /docs/how-it-works/event-sourcing
  - /docs/how-it-works/encryption
---

Workflow SDK provides a Workflow CLI and web UI to inspect, monitor, and debug workflows. You can inspect workflow runs, steps, webhooks, [events](/docs/how-it-works/event-sourcing), and stream output.

## Quick start

```bash
npx workflow
```

The CLI comes pre-installed with the Workflow SDK and registers the `workflow` command. If the `workflow` package is not already installed, `npx workflow` will download and run the CLI temporarily, or use the locally installed version if available.

Get started inspecting your local workflows:

```bash
# See all available commands
npx workflow inspect --help

# List recent workflow runs
npx workflow inspect runs
```

## Web UI

Workflow SDK ships with a local web UI for inspecting your workflows. The CLI
serves the web UI locally when you use the `--web` flag.

```bash
# Launch the web UI for visual exploration
npx workflow inspect runs --web
```

![Workflow SDK Web UI](/o11y-ui.png)

On [Nitro](/docs/getting-started/nitro), the dev server has the web UI built
in: open `/_workflow` while `nitro dev` is running. No separate command is required.

In the runs table, select one or more runs and choose **Cancel** to cancel the batch in a single request. Runs that fail with a retryable error stay selected so you can retry them.

To share a link to a specific run without opening a browser, use the `--url`
flag. It prints the dashboard deep link to stdout and exits (no browser, no
local server), which is useful for scripts, PR comments, or automation. Add `--json` to
get `{ "url": "..." }`.

```bash
# Print the deep-link URL for a run (no browser, no server)
npx workflow inspect run <run_id> --url

# Vercel runs: add the backend (and --env preview for preview deployments)
npx workflow inspect run <run_id> --backend vercel --url
```

## Backends

The Workflow SDK CLI can inspect data from any [World](/docs/deploying). By default, it inspects data in your local development environment. For example, if you are using Next.js to develop workflows locally, the
CLI will find the data in your `.next/workflow-data/` directory.

On the Local World, the CLI and web UI also read the app's queue key from that directory and send it with every delivery to the app, for example when they start or recreate a run. Run them from the app's project directory (or set `WORKFLOW_LOCAL_DATA_DIR` to the app's data directory), and keep them on the same release as the app's `@workflow/world-local`. See [`WORKFLOW_QUEUE_AUTH`](/worlds/local#workflow_queue_auth).

If you're deploying workflows to a production environment, but want to inspect the data by using the CLI, you can specify the world you are using by setting the `--backend` flag to your world's name or package name, e.g. `vercel`.

<Callout>
Backends might require additional configuration. If you're missing environment variables, the World package should provide instructions on how to configure it.
</Callout>

### Vercel backend

To inspect workflows running on Vercel, ensure you're logged in to the Vercel CLI and have linked your project. See [Vercel CLI authentication and project linking docs](https://vercel.com/docs/cli/project-linking) for more information. Then, specify the backend as `vercel`.

```bash
# Inspect workflows running on Vercel
npx workflow inspect runs --backend vercel
```

Without an interactive `vercel login`, such as in CI, pass the auth token, project ID, team ID, and environment explicitly. See [Connecting from outside a deployment](/worlds/vercel#connecting-from-outside-a-deployment).

When deployed to Vercel, workflow data is [encrypted end-to-end](/docs/how-it-works/encryption). Encrypted fields display as locked placeholders until you choose to decrypt them using the **Decrypt** button in the web UI or the `--decrypt` flag in the CLI.

## More observability features

<AutoCards />