Loracle CLI

After completing this guide, your component catalog will be indexed and queryable by AI through the MCP server or the Storybook addon.

Before you begin

A running Storybook instance or a deployed Storybook URL
Node.js 22 or higher
An API key from the Loracle dashboard (Project Settings > API Keys)

Publish your Storybook

Install the CLI

npm install -g @loracle-js/cli

The package exposes the loracle binary.Or run it directly with npx:

npx @loracle-js/cli publish <url> --version <version>

Set your API key

export LORACLE_API_KEY="sk_live_..."

Run publish

loracle publish https://your-storybook.com --version 1.0.0

The CLI connects to your Storybook, extracts every component with its props and documentation, and uploads the catalog to Loracle.

Flag	Description
`<url>`	URL of your running Storybook
`--version`	Semver string (e.g. `1.0.0`). Each publish creates a versioned snapshot of your catalog.
`--dry-run`	Scrape and validate without uploading. Optional.

CI/CD

Automate publishing on every release. The CLI uses Playwright internally to scrape your Storybook, so your CI environment needs a Chromium browser available.

Store your LORACLE_API_KEY as a CI secret. Never commit it to your repository.

The core steps are the same on every CI:

Install your dependencies
Install Chromium (npx playwright install --with-deps chromium)
Build and serve your Storybook on a local port
Wait for the server (npx wait-on http://localhost:6006)
Run npx @loracle-js/cli publish <url> --version <version>

GitHub Actions
GitLab CI
Other CIs

Add these steps to your workflow. ubuntu-latest requires an explicit Chromium install.

- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: 22

- run: npm ci
- run: npx playwright install --with-deps chromium

- name: Serve Storybook
  run: |
    npm run build-storybook
    npx http-server storybook-static -p 6006 &
    npx wait-on http://localhost:6006

- name: Publish to Loracle
  env:
    LORACLE_API_KEY: ${{ secrets.LORACLE_API_KEY }}
  run: npx @loracle-js/cli publish http://localhost:6006 --version <your-version>

Store LORACLE_API_KEY as a repository secret.

The Playwright Docker image includes Chromium, so no extra install step is needed.

.gitlab-ci.yml

publish-loracle:
  image: mcr.microsoft.com/playwright:v1.55.0-noble
  script:
    - npm ci
    - npm run build-storybook
    - npx http-server storybook-static -p 6006 &
    - npx wait-on http://localhost:6006
    - npx @loracle-js/cli publish http://localhost:6006 --version <your-version>
  variables:
    LORACLE_API_KEY: $LORACLE_API_KEY

Pin the image version to match your playwright dependency (npx playwright --version). Add LORACLE_API_KEY under Settings > CI/CD > Variables.

For Docker-based CIs (CircleCI, Bitbucket Pipelines), use mcr.microsoft.com/playwright:v1.55.0-noble as your base image — it includes Chromium so you can skip the install step. Pin the image version to match your playwright dependency (npx playwright --version).On VM-based runners, install Chromium explicitly:

npx playwright install --with-deps chromium

Get started

Products

Before you begin

Publish your Storybook

CI/CD

Next steps

MCP server

Storybook addon

​Before you begin

​Publish your Storybook

​CI/CD

​Next steps

MCP server

Storybook addon

Before you begin

Publish your Storybook

CI/CD

Next steps