run & resume

Execute a workflow file and resume paused workflows.

run

The run command executes the default export from a TypeScript workflow file against a live browser. Use it to verify a workflow after creating or editing it.

npx libretto run ./integration.ts
npx libretto run ./integration.ts --headless

Syntax

npx libretto run <file> [flags]

<file>: path to the TypeScript workflow file. The file must have a default-exported workflow().

Flags

--headless

boolean

Run the browser in headless mode. Use this for the normal fix-and-verify loop.

--headed

boolean

Run the browser in headed (visible) mode. This is the default when neither flag is passed.

--session

string

Name for this run session. Auto-generated if omitted. Use an explicit name to target the session with exec, snapshot, or resume after a failure or pause.

--params

string

Inline JSON input for the workflow, passed as a quoted string. When the workflow uses Zod schemas, Libretto validates this input against schemas.input before the handler runs. Example: --params '{"status":"open"}'.

--params-file

string

Path to a JSON file to use as workflow input. Cannot be used together with --params. When the workflow uses Zod schemas, the file contents are validated against schemas.input.

--viewport

string

Viewport size in WIDTHxHEIGHT format, for example 1920x1080. Falls back to .libretto/config.json, then 1366x768.

--tsconfig

string

Path to a tsconfig.json file for module resolution during workflow compilation.

--no-visualize

boolean

Disable ghost cursor and element highlight visualization in headed mode.

--provider

string

Browser provider to use for this run. Must be local, kernel, browserbase, steel, or libretto-cloud. Overrides LIBRETTO_PROVIDER and the provider setting in .libretto/config.json.

To keep local debugging and workflow runs on the same browser provider, set provider in .libretto/config.json. See Alternative providers for Kernel, Browserbase, Steel, AWS, and GCP setup.

Behavior on failure

When a workflow fails, Libretto keeps the browser open at the point of failure. You can then use snapshot and exec to inspect the live page state before editing the workflow code.

# Workflow fails, browser stays open
npx libretto run ./integration.ts --session debug-flow --headed

# Inspect the failure state
npx libretto snapshot --session debug-flow

# Prototype a fix
npx libretto exec --session debug-flow "await page.locator('.error-message').textContent()"

# Re-run after fixing the code
npx libretto run ./integration.ts --headless

Validation loop

Prefer run --headless for the normal fix-and-verify loop. When the headless run passes, do a final headed run if you or the user wants to watch the finished workflow:

# Fix/verify loop, fast, no visible browser
npx libretto run ./integration.ts --headless

# Final confirmation run, shows the browser
npx libretto run ./integration.ts --headed

Examples

# Basic run
npx libretto run ./integration.ts

# Headless run with inline params
npx libretto run ./integration.ts --headless --params '{"status":"open"}'

# Run with a params file
npx libretto run ./integration.ts --params-file ./params.json

# Run with explicit session name for post-failure inspection
npx libretto run ./integration.ts --session debug-flow --headed

resume

The resume command unpauses a workflow that has stopped at an await pause(session) call. Use it repeatedly until the workflow completes or pauses again at the next breakpoint.

npx libretto resume --session debug-example

Flags

--session

string

required

The session name of the paused workflow to resume.

The `pause()` API

Insert await pause(session) calls in your workflow file to create interactive breakpoints, similar to debugger breakpoints in the browser flow. The workflow stops at each pause() call and waits for resume before continuing.

import { workflow, pause } from "libretto";
import { z } from "zod";

export default workflow(
  "myWorkflow",
  {
    input: z.object({}),
    output: z.object({
      done: z.boolean(),
    }),
  },
  async (ctx) => {
    const { session, page } = ctx;

    await page.goto("https://linkedin.com");

    // Pause here for inspection
    await pause(session);

    await page.locator("#submit").click();

    // Pause again before the final step
    await pause(session);

    return { done: true };
  },
);

pause() is a no-op when NODE_ENV === "production". You can leave pause() calls in your workflow code during development and they will be silently skipped in production.

Complete debugging flow

Run the workflow and let it fail (or pause)

npx libretto run ./integration.ts --session debug-flow --headed

If the workflow hits a pause(), it prints Workflow paused. and returns. The browser stays open.

Inspect the paused page state

npx libretto snapshot --session debug-flow

npx libretto exec --session debug-flow "await page.url()"

Resume the workflow

npx libretto resume --session debug-flow

Keep running resume until the workflow prints Integration completed. or fails with an error.

Fix the code and re-run

Edit the workflow file to fix any issues found during inspection, then re-run:

npx libretto run ./integration.ts --headless

snapshot

Inspect page state after a failure or pause.

exec

Prototype fixes against the paused browser before editing code.

CLI

Runtime

run

Syntax

Flags

Behavior on failure

Validation loop

Examples

resume

Flags

The `pause()` API

Complete debugging flow

snapshot

exec

​run

​Syntax

​Flags

​Behavior on failure

​Validation loop

​Examples

​resume

​Flags

​The pause() API

​Complete debugging flow

snapshot

exec

run

Syntax

Flags

Behavior on failure

Validation loop

Examples

resume

Flags

The `pause()` API

Complete debugging flow