@lyba/cli commands

@lyba/cli creates Lyba review sessions from CI for React deploy previews. 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.

The CLI does not inject the overlay. Install @lyba/react in the app too; without it, the review link can open the preview but no Lyba UI will appear.

Running the CLI

npx @lyba/cli session create

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

lyba session create

Commands

lyba session create

lyba session create [options]

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.

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 yours 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

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.

The command is safe to run repeatedly for the same project: it reuses the project record and creates a new session for the new preview. Run it for every preview deploy you want reviewed.

lyba login

npx @lyba/cli login

Opens the Lyba dashboard, asks you to approve the CLI, and stores the returned API key in ~/.lyba/config.json with 0600 permissions. After that, lyba session create runs without --api-key.

lyba whoami

npx @lyba/cli whoami

Shows the active credential.

lyba logout

npx @lyba/cli logout

Removes the stored key.

Authentication

The CLI authenticates with an agency API key from Dashboard → Settings → API keys. Resolution order:

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

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

Do not commit API keys and do not put them in frontend environment variables. The key is only for server-side CI usage.

Locally

Sign in through the browser instead of pasting a key:

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

Environment variables

Auto-detected CI variables

Provider variables supply the preview URL and deploy metadata. GitHub Actions variables supply repo, SHA, branch and PR metadata when your deploy provider runs inside Actions. For per-host recipes, see Create sessions from CI.

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=...

• Review link — the main link, usually https://lyba.io/r/<slug>. It is durable and rotates a fresh, short-lived review token whenever opened.
• Direct link — a fallback on the preview URL with #lyba_token=.... It contains a token in the URL fragment, which is convenient but less durable than the short /r/<slug> link.

See Projects, sessions and review links for how the two relate.

GitHub Actions outputs

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

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

Give the step an id to use them in later steps:

- 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 }}

Errors

For review-link and overlay problems, see Troubleshooting.

Security notes

• Review links are client-facing capabilities. Share them with reviewers, not in public channels.
• Approval receipts are generated by Lyba's backend and are bound to the session commit SHA.