libretto 0.5.1 → 0.5.3-experimental.0

package/scripts/generate-changelog.ts

@@ -0,0 +1,132 @@
+import { execFileSync } from "node:child_process";
+import { Agent, type AgentTool, type AgentEvent } from "@mariozechner/pi-agent-core";
+import { getModel } from "@mariozechner/pi-ai";
+import { Type } from "@sinclair/typebox";
+
+const tag = process.argv[2];
+if (!tag) {
+  console.error("Usage: generate-changelog.ts <tag>");
+  console.error("Example: generate-changelog.ts v0.5.2");
+  process.exit(1);
+}
+
+if (!process.env.ANTHROPIC_API_KEY) {
+  console.error("ANTHROPIC_API_KEY is required.");
+  process.exit(1);
+}
+
+const ALLOWED_GH_SUBCOMMANDS = new Set(["pr", "release", "repo", "issue"]);
+const ALLOWED_ACTIONS = new Set(["list", "view", "diff", "status", "checks"]);
+
+const ghTool: AgentTool = {
+  name: "gh",
+  label: "GitHub CLI",
+  description: [
+    "Run a read-only GitHub CLI command. The arguments are passed directly to `gh`.",
+    "Examples: 'release list --limit 5', 'pr list --state merged --json number,title',",
+    "'pr view 128 --json title,body,files', 'pr diff 128'.",
+    "Only read operations are allowed (list, view, diff, etc.). Mutating commands will be rejected.",
+  ].join(" "),
+  parameters: Type.Object({
+    args: Type.String({ description: "Arguments to pass to gh (without the leading 'gh')" }),
+  }),
+  execute: async (_toolCallId, rawParams) => {
+    const params = rawParams as { args: string };
+    const args = params.args.trim();
+    const parts = args.split(/\s+/);
+    const subcommand = parts[0];
+
+    if (!subcommand || !ALLOWED_GH_SUBCOMMANDS.has(subcommand)) {
+      throw new Error(`Subcommand '${subcommand}' is not allowed. Allowed: ${[...ALLOWED_GH_SUBCOMMANDS].join(", ")}`);
+    }
+
+    const action = parts[1];
+    if (!action || !ALLOWED_ACTIONS.has(action)) {
+      throw new Error(`Action '${action}' is not allowed. Allowed: ${[...ALLOWED_ACTIONS].join(", ")}`);
+    }
+
+    try {
+      const output = execFileSync("gh", parts, {
+        encoding: "utf8",
+        timeout: 300_000,
+        maxBuffer: 1024 * 1024,
+      });
+      return { content: [{ type: "text", text: output }], details: {} };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(`gh command failed: ${message}`);
+    }
+  },
+};
+
+const agent = new Agent({
+  initialState: {
+    systemPrompt: [
+      `Generate release notes for the ${tag} release of Libretto.`,
+      "",
+      "Use the gh tool to explore what changed since the previous release.",
+      "Useful queries:",
+      "- 'release list --limit 5' to find the previous release tag",
+      "- 'pr list --state merged --limit 50 --json number,title,body,labels' to find merged PRs",
+      "- 'pr diff NUMBER' to see the full diff of a PR (base to head, not individual commits)",
+      "- 'pr view NUMBER --json title,body,files' to see PR details",
+      "",
+      "IMPORTANT: Always read the full PR diff to understand what actually changed.",
+      "Do NOT rely solely on PR titles and descriptions — they may be incomplete or misleading.",
+      "The diff is the source of truth for what the release note should say.",
+      "",
+      "Guidelines:",
+      "- Write concise, user-facing release notes in markdown.",
+      "- Group changes into sections like Features, Fixes, and Improvements. Only include sections that have entries.",
+      "- Focus on what changed from the user's perspective, not internal implementation details.",
+      "- Do NOT include PR numbers or links.",
+      "- Skip PRs labeled 'skip-changelog'.",
+      "- Your response must contain ONLY the raw markdown release notes. No preamble like 'Here are the release notes'. No commentary or explanation. No '---' separators. The very first character of your response must be '#'. Example format:",
+      "",
+      "## Features",
+      "",
+      "- **Thing**: Description",
+    ].join("\n"),
+    model: getModel("anthropic", "claude-sonnet-4-6"),
+    tools: [ghTool],
+  },
+});
+
+let finalText = "";
+
+agent.subscribe((event: AgentEvent) => {
+  if (event.type === "agent_end") {
+    const messages = event.messages;
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const msg = messages[i];
+      if (msg.role === "assistant" && Array.isArray(msg.content)) {
+        for (const block of msg.content) {
+          if (typeof block === "object" && "type" in block && block.type === "text" && "text" in block) {
+            finalText = block.text as string;
+            return;
+          }
+        }
+      }
+    }
+  }
+});
+
+await agent.prompt("Generate the release notes now.");
+
+if (!finalText) {
+  console.error("Changelog generation failed: no text output from agent.");
+  process.exit(1);
+}
+
+// Strip any preamble before the first markdown heading.
+const headingIndex = finalText.indexOf("\n#");
+if (headingIndex >= 0) {
+  finalText = finalText.slice(headingIndex + 1);
+} else if (finalText.startsWith("#")) {
+  // Already starts with a heading, keep as-is.
+} else {
+  console.error("Changelog generation failed: output does not contain markdown headings.");
+  process.exit(1);
+}
+
+process.stdout.write(finalText);

package/scripts/skills-libretto.mjs

@@ -11,7 +11,7 @@ import {
 import { relative, resolve, join } from "node:path";
 
 export const SKILL_DIRS = [
-  "skills/libretto",
+  "packages/libretto/skills/libretto",
   ".agents/skills/libretto",
   ".claude/skills/libretto",
 ];

package/scripts/sync-skills.mjs

@@ -6,7 +6,7 @@ import { fileURLToPath } from "node:url";
 import { SKILL_DIRS, syncRepoSkills } from "./skills-libretto.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const repoRoot = join(__dirname, "..");
+const repoRoot = join(__dirname, "..", "..", "..");
 
 syncRepoSkills(repoRoot);
 console.log(`libretto: synced skill mirrors across ${SKILL_DIRS.join(", ")}`);

package/skills/libretto/SKILL.md

@@ -10,30 +10,31 @@ metadata:
 ## How Libretto Works
 
 - Libretto is a CLI for exploring live websites and building or debugging reusable browser automation scripts.
-- Use Libretto to inspect the real site first: open pages, observe state, inspect requests, and prototype interactions before writing code.
+- Use Libretto commands to inspect the site and open pages, observe state, inspect requests, and prototype interactions.
 - Libretto work must end in script changes. Create or edit the workflow file instead of stopping at interactive exploration.
 
 ## Default Integration Approach
 
-- Prefer network requests first for new integrations.
+- Prefer network requests first for new integrations unless the user explicitly asks for Playwright or UI automation, then do not use the site's internal API.
 - Read `references/site-security-review.md` before committing to a network-first approach on a new site.
 - Fall back to passive interception or Playwright-driven UI automation when the security review rules network requests out, the request path is not workable, or the user explicitly asks for Playwright.
 
 ## Setup
 
-- Ask the user to set up snapshot analysis before relying on `snapshot` for page understanding.
-- Use `npx libretto init` for first-time workspace setup.
+- Use `npx libretto init` for first-time workspace setup (sets up config file and snapshot command).
 - If credentials are already available, `npx libretto ai configure openai|anthropic|gemini|vertex` is usually enough.
 
 ## Working Rules
 
 - Announce which session you are using and what page you are on.
 - Ask instead of guessing when it is unclear what to click, type, or submit.
+- Do not treat visibility as interactivity. If an element will not act, inspect blockers before retrying.
+- Defer repo/code review until you begin generating code, unless the user explicitly asks for it earlier.
 - Read and follow guidelines in `references/code-generation-rules.md` before generating or editing production workflow code.
-- After interactive exploration and code generation, test key logic with `exec`, then verify the workflow file with `run --headless`.
+- Validation requires a successful clean `run --headless` with confirmation of the actual returned output, not just process success. If the user wants to watch the finished workflow, do a final headed `run` after headless validation succeeds.
+- Treat exploration sessions as disposable unless the user explicitly wants one kept open.
 - Get explicit user confirmation before mutating actions or replaying network requests that may have side effects.
 - Never run multiple `exec` commands at the same time.
-- Keep the browser session open until the user says the session is done.
 
 ## Commands
 
@@ -63,6 +64,7 @@ npx libretto connect http://127.0.0.1:9223 --session another-session
 
 - Use `snapshot` as the primary page observation tool.
 - Always provide both `--objective` and `--context`.
+- A single snapshot objective can include multiple questions or analysis tasks.
 - Use it before guessing at selectors, after workflow failures, and whenever the visible page state is unclear.
 - When analysis is involved, expect it to take time. Use a timeout of at least 2 minutes for shell-wrapped calls.
 
@@ -81,13 +83,16 @@ npx libretto snapshot \
 
 - Use `exec` for focused inspection and short-lived interaction experiments.
 - Use `exec` to validate selectors, inspect data, or prototype a step before you encode it in the workflow file.
+- Use `exec -` to run multi-line scripts from stdin, especially when the code is too long or complex for a command line argument.
+- Available globals: `page`, `context`, `browser`, `state`, `fetch`, `Buffer`.
 - Let failures throw. Do not hide `exec` failures with `try/catch` or `.catch()`.
 - Do not run multiple `exec` commands in parallel.
 
 ```bash
 npx libretto exec "return await page.url()"
 npx libretto exec "return await page.locator('button').count()"
-npx libretto exec --visualize "await page.locator('button:has-text(\"Continue\")').click()"
+npx libretto exec "await page.locator('button:has-text(\"Continue\")').click()"
+echo "return await page.url()" | npx libretto exec - --session debug-example
 ```
 
 ### `pages`
@@ -100,45 +105,25 @@ npx libretto pages --session debug-example
 npx libretto exec --session debug-example --page <page-id> "return await page.url()"
 ```
 
-### `network`
-
-- Use `network` to inspect the requests the page already made.
-- Prefer this when discovering how a site loads data or when validating whether a network-first approach is workable.
-- Filter aggressively by method, URL pattern, and page when the log is noisy.
-
-```bash
-npx libretto network --session debug-example --last 20
-npx libretto network --session debug-example --method POST --filter 'referral|patient'
-npx libretto network --session debug-example --page <page-id>
-```
-
-### `actions`
-
-- Use `actions` when you need a quick record of recent user or agent interactions in the current session.
-- Keep it lightweight. It is a helper for orientation, not the main integration-building workflow.
-
-```bash
-npx libretto actions --session debug-example --last 20
-npx libretto actions --session debug-example --action click --source user
-```
-
 ### `run`
 
-- Use `run` to verify a workflow file after creating it or editing it.
+- Use `run` to verify a workflow file after creating it or editing it, preferring `run --headless` for the normal fix/verify loop.
+- Plain `run` defaults to headed mode.
 - If the workflow fails, Libretto keeps the browser open. Inspect the failed state with `snapshot` and `exec` before editing code.
+- Insert `await pause(session)` statements in the workflow file when you need to stop at specific states for interactive debugging, like breakpoints in the browser flow.
 - If the workflow pauses, resume it with `npx libretto resume --session <name>`.
 - Re-run the same workflow after each fix to verify the browser behavior end to end.
 
 ```bash
-npx libretto run ./integration.ts main
-npx libretto run ./integration.ts main --params '{"status":"open"}'
-npx libretto run ./integration.ts main --auth-profile app.example.com --headed
+npx libretto run ./integration.ts workflowName --headless --params '{"status":"open"}'
+npx libretto run ./integration.ts workflowName --auth-profile app.example.com
 ```
 
 ### `resume`
 
-- Workflows pause by calling `await pause()` in the workflow file.
-- Use `resume` when a workflow hit `await pause()`.
+- Workflows pause by calling `await pause("session-name")` in the workflow file. Import `pause` from `"libretto"`.
+- `pause(session)` is a no-op when `NODE_ENV === "production"`.
+- Use `resume` when a workflow hit a `pause()` call.
 - Keep resuming the same session until the workflow completes or pauses again.
 
 ```bash
@@ -147,7 +132,7 @@ npx libretto resume --session debug-example
 
 ### `save`
 
-- Use `save` when the user logs in manually and wants to reuse that authenticated browser state later.
+- Use `save` only when the user explicitly asks to save or reuse authenticated browser state.
 
 ```bash
 npx libretto save app.example.com
@@ -155,7 +140,7 @@ npx libretto save app.example.com
 
 ### `close`
 
-- Use `close` only when the user is done with the session.
+- Use `close` when the user is done with the session or an exploration session is no longer helping progress (unless the user asked to keep watching that browser).
 - `close --all` is available for workspace cleanup.
 
 ```bash
@@ -163,6 +148,36 @@ npx libretto close --session debug-example
 npx libretto close --all
 ```
 
+## Session Logs
+
+Session state is stored in `.libretto/sessions/<session>/state.json`.
+
+Session logs are JSONL files at `.libretto/sessions/<session>/`:
+
+- CLI logs are in `.libretto/sessions/<session>/logs.jsonl`.
+- Action logs are in `.libretto/sessions/<session>/actions.jsonl`.
+- Network logs are in `.libretto/sessions/<session>/network.jsonl`.
+
+Use `jq` to query jsonl logs directly — for any filtering, slicing, or inspection task.
+
+```bash
+# Last 20 action entries
+tail -n 20 .libretto/sessions/<session>/actions.jsonl | jq .
+
+# POST requests only
+jq 'select(.method == "POST")' .libretto/sessions/<session>/network.jsonl
+```
+
+### Action log (`actions.jsonl`)
+
+Key fields: `ts` (ISO timestamp), `source` (`user` or `agent`), `action` (`click`, `fill`, `goto`, etc.), `selector` (locator used by the agent), `bestSemanticSelector` (canonical selector for user DOM events), `success` (boolean), `url` (navigation target), `value` (typed or submitted value), `error` (message on failure).
+
+Read `references/action-logs.md` for full field descriptions and user-vs-agent entry semantics.
+
+### Network log (`network.jsonl`)
+
+Key fields: `ts` (ISO timestamp), `method` (HTTP method, e.g. `GET`, `POST`), `url` (request URL), `status` (HTTP status code), `contentType` (response content type), `responseBody` (response body string, may be null).
+
 ## Examples
 
 ### Building new browser automation workflows
@@ -202,5 +217,6 @@ Assistant: I found the issue. I'll patch the workflow code, then rerun `npx libr
 - Read `references/configuration-file-reference.md` when you need to inspect or change `.libretto/config.json` for snapshot model selection or viewport defaults.
 - Read `references/site-security-review.md` before reviewing the site's security posture and deciding whether to lead with network requests, passive interception, or Playwright DOM automation on a new site.
 - Read `references/code-generation-rules.md` before writing or editing production workflow files.
-- Read `references/auth-profiles.md` when the site requires login and the simplest path is to save local browser state.
+- Read `references/auth-profiles.md` when auth-profile behavior is relevant.
 - Read `references/pages-and-page-targeting.md` when a session has multiple open pages or you need `--page`.
+- Read `references/action-logs.md` for full action log field descriptions and user-vs-agent event semantics.

package/skills/libretto/references/action-logs.md

@@ -0,0 +1,101 @@
+# Action Logs
+
+- Stored at `.libretto/sessions/<session>/actions.jsonl`.
+- One JSON object per line.
+- Query the file directly with `jq`, for example `tail -n 20 .libretto/sessions/<session>/actions.jsonl | jq .`.
+- This is an orientation log, not a replay trace.
+
+## User vs Agent
+
+- `agent` entries log the Playwright action Libretto observed, usually as `action` plus `selector`, and sometimes `value`, `url`, `duration`, or `error`.
+- `user` entries log the browser DOM event Libretto captured, so they can include `bestSemanticSelector`, `targetSelector`, `ancestorSelectors`, `nearbyText`, `composedPath`, and `coordinates`.
+- This is why agent entries usually describe what Playwright tried to do, while user entries can describe what element was actually interacted with in the page.
+
+## Fields
+
+- `ts`
+  ISO timestamp.
+
+- `pageId`
+  Playwright target id for the page that produced the entry.
+
+- `action`
+  Logged action name, such as `click`, `dblclick`, `fill`, `goto`, or `reload`.
+
+- `source`
+  `user` for captured DOM events, `agent` for logged Playwright calls.
+
+- `success`
+  `true` if the action completed, `false` if Libretto logged a failure.
+
+- `selector`
+  Selector or locator hint for agent entries.
+
+- `bestSemanticSelector`
+  Canonical selector for user DOM events.
+
+- `targetSelector`
+  Selector for the raw DOM event target. Usually only present for user DOM events.
+
+- `ancestorSelectors`
+  Meaningful ancestor selector candidates for a user DOM event. Ordered from closest meaningful ancestor to farthest meaningful ancestor.
+
+- `nearbyText`
+  Short visible text near the event target, used as human context.
+
+- `composedPath`
+  Compact event-path summaries. Ordered from the raw event target to farthest ancestor.
+
+- `coordinates`
+  Rounded `clientX` and `clientY` for pointer-style events:
+
+```json
+{ "x": 42, "y": 24 }
+```
+
+- `value`
+  Typed, selected, or submitted value when the action had one.
+
+- `url`
+  Navigation target or recorded page URL for navigation-style actions.
+
+- `duration`
+  Elapsed time in milliseconds when Libretto recorded it.
+
+- `error`
+  Error message when the action failed.
+
+## User Example
+
+```json
+{
+  "ts": "2026-03-20T22:34:56.123Z",
+  "pageId": "A1B2C3D4E5F6",
+  "action": "dblclick",
+  "source": "user",
+  "bestSemanticSelector": "button#saveBtn",
+  "targetSelector": "span",
+  "ancestorSelectors": ["button#saveBtn", "form[action=\"/save\"]"],
+  "nearbyText": "Save",
+  "composedPath": ["span [text=\"Save\"]", "button#saveBtn [text=\"Save\"]"],
+  "coordinates": {
+    "x": 42,
+    "y": 24
+  },
+  "success": true
+}
+```
+
+## Agent Example
+
+```json
+{
+  "ts": "2026-03-20T22:35:10.456Z",
+  "pageId": "A1B2C3D4E5F6",
+  "action": "click",
+  "source": "agent",
+  "selector": "page.getByRole(\"button\", {\"name\":\"Save\"})",
+  "duration": 187,
+  "success": true
+}
+```

package/skills/libretto/references/auth-profiles.md

@@ -1,12 +1,11 @@
 # Auth Profiles
 
-Use this reference when the target site requires login and the user wants to reuse local authenticated browser state.
+Use this reference only when the user explicitly asks to save or reuse local authenticated browser state.
 
 ## When to Use This
 
 - The site requires manual login.
 - The user is running workflows locally.
-- Reusing a saved session is simpler than building credential-handling logic into the workflow.
 
 ## Workflow
 

package/skills/libretto/references/code-generation-rules.md

@@ -6,7 +6,7 @@ Follow the user's existing codebase conventions, abstractions, and patterns when
 
 ## Workflow File Structure
 
-Generated files must export a `workflow()` instance so they can be run via `npx libretto run <file> <exportName>`. Import `workflow` and its types from `"libretto"`:
+Generated files must export a `workflow()` instance so they can be run via `npx libretto run <file> <workflowName>`. Import `workflow` and its types from `"libretto"`:
 
 ```typescript
 import { workflow, pause, type LibrettoWorkflowContext } from "libretto";
@@ -23,7 +23,8 @@ type Output = {
 };
 
 export const myWorkflow = workflow<Input, Output>(
-  async (ctx, input): Promise<Output> => {
+  "myWorkflow",
+  async (ctx: LibrettoWorkflowContext, input): Promise<Output> => {
     const { session, page, logger } = ctx;
 
     logger.info("workflow-start", { session, query: input.query });
@@ -37,12 +38,12 @@ export const myWorkflow = workflow<Input, Output>(
 
 Key points:
 
-- The named export (e.g., `myWorkflow`) is what you pass as the second arg to `npx libretto run ./file.ts myWorkflow`
-- `workflow(handler)` returns a branded workflow object with a `.run(ctx, input)` method. The CLI expects that contract.
+- `workflow(name, handler)` takes a unique workflow name and returns the workflow object that Libretto can run.
+- `npx libretto run ./file.ts myWorkflow` resolves `myWorkflow` from the workflows exported by `./file.ts`, so export or re-export the workflow from that file directly or through a `workflows` object, and make sure the run argument matches the name passed to `workflow("myWorkflow", ...)`.
 - `ctx` provides `session`, `page`, `logger`, and `services` (generic, default `{}`)
 - `input` comes from `--params '{"query":"foo"}'` or `--params-file params.json` on the CLI
-- If the site requires a saved login session, pass `--auth-profile <domain>` to the CLI (created via `npx libretto save <domain>`)
 - Use `await pause(ctx.session)` (or `await pause(session)`) to pause the workflow for debugging. It is a no-op in production.
+- After validation is complete and the workflow is confirmed working end to end, remove all `pause()` calls and pause-only workflow params unless the user explicitly says to keep them.
 - The browser is launched and closed automatically by the CLI. Do not launch or close it in the handler.
 
 ## Passing Application Dependencies via Services
@@ -57,6 +58,7 @@ import { type Transaction } from "./db";
 type MyServices = { tx?: Transaction };
 
 export const myWorkflow = workflow<Input, Output, MyServices>(
+  "myWorkflow",
   async (ctx, input) => {
     if (ctx.services.tx) {
       await ctx.services.tx.insert(/* ... */);
@@ -80,12 +82,14 @@ await myWorkflow.run(
 When running standalone via `npx libretto run`, services defaults to `{}`,
 so mark fields optional for anything unavailable in that context.
 
-## Playwright Locators for DOM Interaction
+## Playwright DOM Interaction Rules
 
 Generated code must use Playwright locator APIs for all DOM interactions. Do not use `page.evaluate()` with `document.querySelector`, `querySelectorAll`, `textContent`, `click()`, or other DOM APIs when a Playwright locator can do the same thing.
 
 During the interactive `exec` phase, `page.evaluate` is fine for quick prototyping. In generated production code, translate those patterns into Playwright locators.
 
+Before extracting data (for example text, rows, or field values), wait for the target content itself to be ready, not just its container.
+
 ### Anti-Patterns
 
 These patterns come up frequently during interactive sessions and should not carry over into production code:

package/skills/libretto/references/pages-and-page-targeting.md

@@ -26,4 +26,4 @@ npx libretto snapshot --session debug-flow --page <page-id> --objective "Find th
 
 - A session can contain more than one page.
 - When multiple pages are open, think about page targeting first before debugging selectors.
-- Use `pages` to resolve the correct page id, then pass `--page` to `exec`, `snapshot`, `network`, or `actions` when needed.
+- Use `pages` to resolve the correct page id, then pass `--page` to `exec` or `snapshot` when needed.

package/src/cli/commands/execution.ts

@@ -605,9 +605,10 @@ async function runIntegrationFromFile(
   );
   const payload = JSON.stringify({
     integrationPath: args.integrationPath,
-    exportName: args.exportName,
+    workflowName: args.workflowName,
     session: args.session,
     params: args.params,
+    credentials: args.credentials,
     headless: args.headless,
     visualize: args.visualize,
     authProfileDomain: args.authProfileDomain,
@@ -656,11 +657,20 @@ async function runIntegrationFromFile(
   console.log("Integration completed.");
 }
 
+function readStdinSync(): string | null {
+  if (process.stdin.isTTY === true) return null;
+  try {
+    const content = readFileSync(0, "utf8");
+    return content.trim().length > 0 ? content : null;
+  } catch {
+    return null;
+  }
+}
+
 export const execInput = SimpleCLI.input({
   positionals: [
-    SimpleCLI.positional("codeParts", z.array(z.string()).default([]), {
+    SimpleCLI.positional("code", z.string().optional(), {
       help: "Playwright TypeScript code to execute",
-      variadic: true,
     }),
   ],
   named: {
@@ -671,8 +681,8 @@ export const execInput = SimpleCLI.input({
     page: pageOption(),
   },
 }).refine(
-  (input) => input.codeParts.length > 0,
-  `Usage: libretto exec <code> [--session <name>] [--visualize]`,
+  (input) => input.code !== undefined,
+  `Usage: libretto exec <code|-> [--session <name>] [--visualize]\n       echo '<code>' | libretto exec - [--session <name>] [--visualize]`,
 );
 
 export const execCommand = SimpleCLI.command({
@@ -681,8 +691,15 @@ export const execCommand = SimpleCLI.command({
   .input(execInput)
   .use(withRequiredSession())
   .handle(async ({ input, ctx }) => {
+    const code = input.code!;
+    const codeFromArgsOrStdin = code === "-" ? readStdinSync() : code;
+    if (codeFromArgsOrStdin === null) {
+      throw new Error(
+        "Missing stdin input for `exec -`. Pipe Playwright code into stdin.",
+      );
+    }
     await runExec(
-      input.codeParts.join(" "),
+      codeFromArgsOrStdin,
       ctx.session,
       ctx.logger,
       input.visualize,
@@ -690,15 +707,15 @@ export const execCommand = SimpleCLI.command({
     );
   });
 
-const runUsage = `Usage: libretto run <integrationFile> <integrationExport> [--params <json> | --params-file <path>] [--tsconfig <path>] [--headed|--headless] [--no-visualize] [--viewport WxH]`;
+const runUsage = `Usage: libretto run <integrationFile> <workflowName> [--params <json> | --params-file <path>] [--credentials <json>] [--tsconfig <path>] [--headed|--headless] [--no-visualize] [--viewport WxH]`;
 
 export const runInput = SimpleCLI.input({
   positionals: [
     SimpleCLI.positional("integrationFile", z.string().optional(), {
       help: "Path to the integration file",
     }),
-    SimpleCLI.positional("integrationExport", z.string().optional(), {
-      help: "Named workflow export to run",
+    SimpleCLI.positional("workflowName", z.string().optional(), {
+      help: "Workflow name to run (from workflow(name, handler))",
     }),
   ],
   named: {
@@ -710,6 +727,9 @@ export const runInput = SimpleCLI.input({
       name: "params-file",
       help: "Path to a JSON params file",
     }),
+    credentials: SimpleCLI.option(z.string().optional(), {
+      help: "Inline JSON credentials passed to ctx.credentials",
+    }),
     tsconfig: SimpleCLI.option(z.string().optional(), {
       help: "Path to a tsconfig used for workflow module resolution",
     }),
@@ -729,7 +749,7 @@ export const runInput = SimpleCLI.input({
   },
 })
   .refine(
-    (input) => Boolean(input.integrationFile && input.integrationExport),
+    (input) => Boolean(input.integrationFile && input.workflowName),
     runUsage,
   )
   .refine(
@@ -772,6 +792,13 @@ export const runCommand = SimpleCLI.command({
     assertSessionAvailableForStart(ctx.session, ctx.logger);
 
     const params = resolveRunParams(input.params, input.paramsFile);
+    const rawCredentials = input.credentials
+      ? parseJsonArg("--credentials", input.credentials)
+      : undefined;
+    if (rawCredentials !== undefined && (typeof rawCredentials !== "object" || rawCredentials === null || Array.isArray(rawCredentials))) {
+      throw new Error("--credentials must be a JSON object (e.g., '{\"key\": \"value\"}').");
+    }
+    const credentials = rawCredentials as Record<string, unknown> | undefined;
     const headlessMode = input.headed
       ? false
       : input.headless
@@ -786,9 +813,10 @@ export const runCommand = SimpleCLI.command({
     await runIntegrationFromFile(
       {
         integrationPath: input.integrationFile!,
-        exportName: input.integrationExport!,
+        workflowName: input.workflowName!,
         session: ctx.session,
         params,
+        credentials,
         tsconfigPath: input.tsconfig,
         headless: headlessMode ?? false,
         visualize,