> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getloracle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Loracle CLI

> Publish your Storybook to Loracle.

After completing this guide, your component catalog will be indexed and queryable by AI through the [MCP server](/mcp) or the [Storybook addon](/storybook-addon).

## Before you begin

* A running Storybook instance or a deployed Storybook URL
* Node.js 18 or higher
* An API key from the [Loracle dashboard](https://app.getloracle.com) (**Project Settings > API Keys**)

## Publish your Storybook

<Steps>
  <Step title="Install the CLI">
    ```bash theme={null}
    npm install -g @loracle/cli
    ```

    Or run it directly with `npx`:

    ```bash theme={null}
    npx @loracle/cli publish <url> --version <version>
    ```
  </Step>

  <Step title="Set your API key">
    ```bash theme={null}
    export LORACLE_API_KEY="sk_live_..."
    ```
  </Step>

  <Step title="Run publish">
    ```bash theme={null}
    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. |
    | `--api-url` | Override the Loracle API endpoint. Optional.                                             |
  </Step>
</Steps>

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

<Tip>
  Store your `LORACLE_API_KEY` as a CI secret. Never commit it to your repository.
</Tip>

The core steps are the same on every CI:

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

<Tabs>
  <Tab title="GitHub Actions">
    Add these steps to your workflow. `ubuntu-latest` requires an explicit Chromium install.

    ```yaml theme={null}
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: 20

    - 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/cli publish http://localhost:6006 --version <your-version>
    ```

    Store `LORACLE_API_KEY` as a [repository secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions).
  </Tab>

  <Tab title="GitLab CI">
    The Playwright Docker image includes Chromium, so no extra install step is needed.

    ```yaml .gitlab-ci.yml theme={null}
    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/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**.
  </Tab>

  <Tab title="Other CIs">
    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:

    ```bash theme={null}
    npx playwright install --with-deps chromium
    ```
  </Tab>
</Tabs>

## Next steps

<Columns cols={2}>
  <Card title="MCP server" icon="robot" href="/mcp">
    Connect your coding agent to the published catalog.
  </Card>

  <Card title="Storybook addon" icon="pencil" href="/storybook-addon">
    Use AI to generate stories from inside Storybook.
  </Card>
</Columns>