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.

profiles

Save and reuse authenticated browser state across runs.

save

The save command saves the current browser session's cookies, localStorage, and IndexedDB as a named local auth profile. Workflows load it by declaring authProfile.
npx libretto save linkedin --session app-login --sites linkedin.com

When to use save

Only use save when you want to save or reuse authenticated browser state. A typical flow:
  1. Open the site in headed mode
    npx libretto open https://linkedin.com --headed --session app-login
  2. Log in manually
    The browser window is visible. Log in as usual.
  3. Save the session
    npx libretto save linkedin --session app-login --sites linkedin.com
    The profile is saved to .libretto/profiles/linkedin.json.
  4. Use the profile in future runs
    Declare authProfile: "linkedin" in the workflow, then run it normally:
    npx libretto run ./integration.ts

Flags

path profileNamestringrequired
The local profile name. Passed as the first positional argument. Example: linkedin, twitter, or twitter2.
path --sessionstringrequired
The session to save. Use the same name you passed to npx libretto open --session.
path --sitesstringrequired
Comma-separated site or domain list to capture, for example linkedin.com,auth.linkedin.com.
Subdomains do not need to be listed separately when the parent domain is enough for the login. For example, linkedin.com captures cookies for www.linkedin.com and auth.linkedin.com. Add multiple sites when the login uses separate parent domains, such as example.com,example-login.com.

Storage-state profiles and persistent browser profiles

The save command creates a Playwright storage-state profile. It preserves cookies, localStorage, and IndexedDB, which is sufficient for most websites. It does not preserve sessionStorage, service-worker memory, or authentication that the server binds to a specific browser process.
Use a persistent browser profile when signing in again after loading a saved auth profile invalidates the session. Launch Chrome with a dedicated --user-data-dir, keep that browser process running, and attach Libretto with connect.
A persistent browser profile contains credentials and the browser's complete local state. Give each account a separate directory, restrict filesystem access, and do not run multiple browser processes against the same directory.

import-chrome-profiles

The import-chrome-profiles command imports cookies, localStorage, and IndexedDB from an existing Chrome DevTools Protocol session into a named local profile. The profile name is the local Libretto profile you want to create. The --sites list decides which signed-in sites are copied from Chrome.
npx libretto import-chrome-profiles twitter --cdp-url http://127.0.0.1:9222 --sites x.com,twitter.com
Start Chrome with remote debugging enabled, log in normally, then run the fetch command. The CDP URL comes from the Chrome process you launched with --remote-debugging-port; for example, port 9222 gives http://127.0.0.1:9222. The profile is saved under .libretto/profiles/<profileName>.json.
The command asks before attaching because disconnecting from an existing CDP session can close or relaunch that Chrome window. Use --yes only when the user has already consented.
Recent Chrome versions reject remote debugging against the default user-data directory; if Chrome prints that error, copy the desired profile to a temporary user-data directory and launch Chrome from that copy.

cloud profiles list

List hosted auth profile names known to Libretto Cloud:
npx libretto cloud profiles list
libretto cloud deploy automatically registers any authProfile names declared by deployed workflows. Hosted runs use the browser provider's native profile API; local profile files are not uploaded.
Local profiles and cloud profiles are intentionally separate. There is no command to copy a local profile file into a cloud profile, or to download a cloud profile into .libretto/profiles/. Local profiles are Playwright storage-state JSON for local runs; cloud profiles are provider-native browser profiles managed by the hosted browser provider.

cloud profiles delete

Delete a hosted auth profile name and its provider mappings:
npx libretto cloud profiles delete twitter

Profile storage

Profiles are stored in .libretto/profiles/<profileName>.json. They are:
  • Machine-local, not shared across environments or team members.
  • Git-ignored by default.
  • Subject to session expiry. If authentication stops working, repeat the login-and-save flow.
Profiles contain session cookies that are effectively credentials. The .libretto/ directory is already git-ignored, but double-check your .gitignore if you're storing Libretto state in a non-standard location.
Powered byHolocron