Skip to main content

Documentation Index

Fetch the complete documentation index at: https://libretto.sh/docs/llms.txt

Use this file to discover all available pages before exploring further.

Deploy workflow bundles to Libretto Cloud, then use the failure emails and debug tools when runs break.

​
Before you deploy

Libretto Cloud commands and API requests use https://api.libretto.sh. Issue an API key for the deployment environment: 
export LIBRETTO_API_KEY=<issued-api-key>

​
Expected deploy directory

libretto experimental deploy uploads one package directory at a time. That directory must contain:
  • A package.json
  • An entry file for workflow discovery
  • The workflow files you want to deploy
By default, Libretto looks for index.ts inside the directory you pass to deploy. Recommended layout: 
my-automations/
├── package.json
├── index.ts
└── src/
    └── workflows/
        ├── check-eligibility.ts
        └── submit-prior-auth.ts
Each workflow file should default-export a workflow(...). Then index.ts should export the workflows you want Libretto Cloud to discover: 
export { default as checkEligibility } from "./src/workflows/check-eligibility";
export { default as submitPriorAuth } from "./src/workflows/submit-prior-auth";
The API uses the workflow name from the workflow("...") call inside the file, not the filename or the export alias from index.ts. If your workflows live in a package inside a monorepo, run deploy against that package directory instead of the monorepo root. The deploy command has two separate path concepts:
  • The positional argument is the package directory to bundle and upload. That directory must contain package.json.
  • --entry-point is the file inside that package directory that Libretto should use for workflow discovery.
For example: 
npx libretto experimental deploy my-automations --entry-point src/workflows/check-eligibility.ts
In that command:
  • my-automations is the package directory
  • src/workflows/check-eligibility.ts is the entry file relative to my-automations

​
Deploy workflows

Use deploy to upload a workflow bundle to Libretto Cloud: 
cd my-automations
npx libretto experimental deploy .
That command expects:
  • . to contain package.json
  • ./index.ts to be the deploy entry point
  • index.ts to export the workflows that should be deployed
The positional argument to deploy is the source directory to package and upload. It is not the path to a workflow file. If you want to deploy from a different entry file, keep the source directory as the package root and use --entry-point relative to that directory: 
npx libretto experimental deploy my-automations \
  --description "payer portal workflows" \
  --entry-point src/workflows/check-eligibility.ts
The CLI bundles the deploy artifact, uploads it to Libretto Cloud, then waits for the build to finish. When the build is ready, it prints the deployment id and the discovered workflow names.

​
Run a deployed workflow

After the deployment finishes, call the hosted jobs endpoint with the workflow name from your code. For example, if your workflow file looks like this: 
// src/workflows/check-eligibility.ts
import { workflow } from "libretto";

type Input = {
  memberId: string;
};

export default workflow<Input, { status: string }>(
  "check-eligibility",
  async ({ page }, input) => {
    await page.goto("https://example.com/eligibility");

    return {
      status: "eligible",
    };
  },
);
then hit the endpoint with workflow: "check-eligibility": 
curl -X POST "https://api.libretto.sh/v1/jobs/create" \
  -H "x-api-key: $LIBRETTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "json": {
      "workflow": "check-eligibility",
      "params": {
        "memberId": "12345"
      },
      "timeout_seconds": 300
    }
  }'
That request returns a job_id immediately. Use that id to fetch status or the final result: 
curl -X POST "https://api.libretto.sh/v1/jobs/get" \
  -H "x-api-key: $LIBRETTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "json": {
      "id": "<job-id>"
    }
  }'
The workflow value must match the workflow name declared in code and discovered during deploy, not the deployment id, filename, or export alias.

​
Investigate cloud failures

When a Libretto Cloud workflow job fails, the platform emails the configured debug recipient with:
  • A short diagnosis.
  • A handoff prompt for a local coding agent.
  • Links to the relevant debug context, such as screenshots or recordings when available.
That email is designed to move the fix back into a local coding workflow quickly. After you receive it, use the local repo and Libretto tooling to inspect the failure and patch the workflow. For the local debugging flow, see Debugging workflows.

​
Hosting options

Libretto Cloud is the managed path. If you would rather run Libretto on infrastructure you control, use the self-hosting docs instead:
This page covers the managed hosted-platform flow. The self-hosting pages are the right reference when you want to own the runtime, scheduler, and secrets infrastructure yourself.

Overview

Start with the high-level cloud workflow.

Authentication

Create accounts, join organizations, and issue API keys.

Billing

Manage plans and open the billing portal.