Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Deployments

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, then add it to your project .env file:
LIBRETTO_API_KEY=<issued-api-key>

Expected deploy directory

cloud 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 cloud 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 cloud 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 cloud deploy to upload a workflow bundle to Libretto Cloud:
cd my-automations
npx libretto cloud 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 cloud 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.
Use --auto-repair when failed jobs from this deployment should route to the autofix agent instead of the readonly debug agent.

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";
import { z } from "zod";

export default workflow(
  "check-eligibility",
  {
    input: z.object({
      memberId: z.string(),
    }),
    output: z.object({
      status: z.string(),
    }),
    startUrl: "https://example.com/eligibility",
  },
  async ({ page }, input) => {
    return {
      status: "eligible",
    };
  },
);
then create the hosted job with workflow: "check-eligibility". The params object must match the workflow input schema:
npx libretto cloud jobs create check-eligibility \
  --params '{"memberId":"12345"}' \
  --timeout-seconds 300
That command returns a job_id immediately. The equivalent API request is:
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
    }
  }'
Use the returned 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.

Schedule a deployed workflow

Use cloud schedules create for recurring runs. The cron expression is standard 5-field cron, and the timezone defaults to UTC:
npx libretto cloud schedules create check-eligibility \
  --cron "0 14 * * 1-5" \
  --timezone America/Los_Angeles \
  --params '{"memberId":"12345"}'
The command prints the schedule id and next fire time. Use --params-file instead of --params when the workflow input is too large to keep inline.

Hosting options

Libretto Cloud is the managed path. If you would rather use a different browser or infrastructure provider, use the alternative providers docs instead:
This page covers the managed hosted-platform flow. The alternative provider pages are the right reference when you want a different managed browser provider or 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.
Observability and Debugging
Debug workflow failures and investigate hosted workflow runs.
Libretto
Powered byHolocron