Create sessions from CI

@lyba/cli is the automation half of Lyba's React workflow. It runs after your preview deployment is available, tells Lyba which preview URL and commit SHA are under review, and prints a client-safe review link.

You usually install both packages: @lyba/react in the app so the overlay can activate on preview builds, and @lyba/cli in CI so every preview deploy gets a review session.

What the CLI does

lyba session create performs two API calls:

1. Ensures a Lyba project exists for your repo/site. This is idempotent and keyed by --project or the detected CI repo slug.
2. Creates a review session bound to a preview URL, commit SHA, git ref, provider, PR number, and optional reviewer emails.

It then prints:

• a durable review link, usually https://lyba.io/r/<slug>
• a direct fallback link with #lyba_token=... on the preview URL
• review-url and session-id outputs when running in GitHub Actions

The client later approves that session, and the approval receipt is bound to the commit SHA you passed or the CLI detected.

The CLI is the automated path. You can also create a session by hand from the dashboard (project → New review session). That form permits omitting the SHA, but an approval without one cannot identify a specific code revision.

Prerequisites

• A Lyba agency account.
• An agency API key from Dashboard → Settings → API keys.
• A React app with @lyba/react installed and gated to preview builds — see Quickstart: Next.js App Router or Quickstart: Vite / React.
• A CI/deploy system that can run this command after the preview URL exists.

The CLI does not inject the overlay. If the React package is not installed in the app, the review link can open the preview but no Lyba UI will appear.

Run it

npx @lyba/cli session create

Most CI providers expose enough environment variables for the CLI to detect the preview URL, commit SHA, branch, provider, repo slug, and PR number. If your provider does not, pass the missing values explicitly:

npx @lyba/cli session create \
  --project acme/web \
  --preview-url https://acme-web-git-feature.vercel.app \
  --sha 8f4e2c91a7a1d9c7f4e2c91a7a1d9c7f4e2c91a \
  --ref feature/new-homepage \
  --provider vercel \
  --pr 42

Every flag and environment variable is listed in the CLI reference.

Authentication

The CLI authenticates with an agency API key. Resolution order:

1. --api-key <key>
2. LYBA_API_KEY
3. ~/.lyba/config.json, created by lyba login

CI authentication

In CI, store the key as a secret and expose it as LYBA_API_KEY:

LYBA_API_KEY=lyba_xxx npx @lyba/cli session create

Local authentication

For local use, install or run the CLI and sign in through the browser:

npx @lyba/cli login
npx @lyba/cli whoami
npx @lyba/cli logout

lyba login opens the Lyba dashboard, asks you to approve the CLI, and stores the returned API key in ~/.lyba/config.json with 0600 permissions.

If you install the package globally or use a package manager shim, the binary is named lyba:

lyba session create

Auto-detected CI variables

The CLI recognizes:

Provider variables supply preview URL and deploy metadata. GitHub Actions variables supply repo, SHA, branch, and PR metadata when your deploy provider runs inside Actions.

CI recipes

GitHub Actions

Use this when your previous steps already deploy the preview and expose the preview URL in the environment.

- name: Create Lyba review session
  id: lyba
  run: npx @lyba/cli session create
  env:
    LYBA_API_KEY: ${{ secrets.LYBA_API_KEY }}

- name: Comment Lyba review link on PR
  if: steps.lyba.outputs.review-url
  run: gh pr comment "$PR" --body "Review this preview in Lyba: ${{ steps.lyba.outputs.review-url }}"
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    PR: ${{ github.event.number }}

If your deploy step writes the preview URL to an output, pass it explicitly:

- name: Create Lyba review session
  id: lyba
  run: >
    npx @lyba/cli session create
    --preview-url "${{ steps.deploy.outputs.preview-url }}"
    --sha "${{ github.sha }}"
    --ref "${{ github.head_ref || github.ref_name }}"
    --pr "${{ github.event.number }}"
  env:
    LYBA_API_KEY: ${{ secrets.LYBA_API_KEY }}

Vercel

Run after Vercel has produced the preview URL:

npx @lyba/cli session create \
  --preview-url "https://$VERCEL_URL" \
  --sha "$VERCEL_GIT_COMMIT_SHA" \
  --ref "$VERCEL_GIT_COMMIT_REF" \
  --provider vercel

If the command runs inside Vercel and VERCEL_URL is already available, those flags can usually be omitted.

Netlify

npx @lyba/cli session create \
  --preview-url "$DEPLOY_PRIME_URL" \
  --sha "$COMMIT_REF" \
  --ref "$BRANCH" \
  --provider netlify

Cloudflare Pages

npx @lyba/cli session create \
  --preview-url "$CF_PAGES_URL" \
  --sha "$CF_PAGES_COMMIT_SHA" \
  --ref "$CF_PAGES_BRANCH" \
  --provider cloudflare

Reviewer emails

Pass --client-emails when you want Lyba to record or notify intended reviewers:

npx @lyba/cli session create \
  --client-emails "ada@example.com,grace@example.com"

You can still share the printed review link manually. Reviewer accounts are not required.

Output

✓ Lyba review session created for acme/web @ 8f4e2c9
  Review link: https://lyba.io/r/GtJY36X
  Direct link: https://acme-web-git-feature.vercel.app#lyba_token=...

Use the Review link as the main link. It is durable and rotates a fresh, short-lived review token whenever opened.

Use the Direct link only as a fallback. It contains a token in the URL fragment, which is convenient but less durable than the short /r/<slug> link. See Review links.

In GitHub Actions, the CLI writes these lines to $GITHUB_OUTPUT:

review-url=<review link>
session-id=<session id>

Review links are client-facing capabilities. Share them with reviewers, not in public channels.

One session per deploy

Run session create for every preview deploy you want reviewed. Reusing one old review link across unrelated deploys weakens commit binding and can make DOM anchors less reliable.

The command is safe to run repeatedly for the same project. It will reuse the project record and create a new session for the new preview.

Test locally before wiring CI

You can test the integration before wiring CI:

1. Deploy a preview build with <LybaReview enabled={true} /> or with your preview gate evaluating true.

2. Run the CLI locally:

   bashCopy

   npx @lyba/cli session create \
     --project my-app \
     --project-name "My App" \
     --preview-url https://my-preview.example.com \
     --sha "$(git rev-parse HEAD)" \
     --ref "$(git branch --show-current)"
   

3. Open the printed review link.

Do not test by forcing enabled={true} in a production deployment. Use a preview deployment or a temporary non-production environment.

End-to-end setup checklist

1. Install @lyba/react in the app.
2. Render <LybaReview enabled={...} /> once near the root.
3. Make sure enabled is false on production and true on preview builds.
4. Add https://lyba.io to connect-src if your app uses CSP (see Content Security Policy).
5. Add LYBA_API_KEY to CI secrets.
6. Run npx @lyba/cli session create after the preview deploy.
7. Share steps.lyba.outputs.review-url or the printed Review link.
8. Resolve comments and request approval from the Lyba dashboard.

Something not working? See Troubleshooting.