# Loracle CLI
Source: https://docs.getloracle.com/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-server) or the [Storybook addon](/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](https://app.getloracle.com) (**Project Settings > API Keys**)

## Publish your Storybook

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

    The package exposes the `loracle` binary.

    Or run it directly with `npx`:

    ```bash theme={null}
    npx @loracle-js/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. |
    | `--dry-run` | Scrape and validate without uploading. 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-js/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: 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](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-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**.
  </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>
  <Card title="MCP server" icon="robot" href="/mcp-server">
    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>


# Loracle
Source: https://docs.getloracle.com/index

Connect your design system to AI.

Loracle indexes your Storybook component library and makes it queryable by AI. Publish your design system with the CLI, then use it from any coding agent via MCP or directly inside Storybook with the AI addon.

```text theme={null}
Storybook → CLI → Loracle Cloud ← MCP ← Coding Agent
                                ← Storybook Addon
```

## Choose your path

<Columns>
  <Card title="Publish your design system" icon="upload" href="/cli">
    Use the CLI to index your Storybook and make it queryable by AI.
  </Card>

  <Card title="Use with a coding agent" icon="robot" href="/mcp-server">
    Add the MCP server to Cursor, Claude Code, or Windsurf.
  </Card>

  <Card title="Build stories with AI" icon="pencil" href="/storybook-addon">
    Install the Storybook addon for in-editor AI generation.
  </Card>
</Columns>


# MCP server
Source: https://docs.getloracle.com/mcp-server

Query your design system from any coding agent.

After adding the Loracle MCP server, your coding agent can search your component catalog with natural language.

## Before you begin

* An API key from the [Loracle dashboard](https://app.getloracle.com) (**Project Settings > API Keys**)
* A published design system (see the [CLI guide](/cli))

## Set up your IDE

Add the Loracle MCP endpoint to your IDE's configuration. The server is hosted — no local installation required.

Use the API key you copied from the Loracle dashboard. It starts with `sk_live_`.

<Tabs>
  <Tab title="Cursor">
    Add to `.cursor/mcp.json` in your project root:

    ```json .cursor/mcp.json theme={null}
    {
      "mcpServers": {
        "loracle": {
          "url": "https://mcp.getloracle.com",
          "headers": {
            "Authorization": "Bearer <your-api-key>"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Code">
    Add a project-level server with the Claude Code CLI:

    ```bash theme={null}
    export LORACLE_API_KEY="sk_live_..."
    claude mcp add --transport http loracle https://mcp.getloracle.com --header "Authorization: Bearer $LORACLE_API_KEY"
    ```

    Or add it to `.mcp.json` in your project root:

    ```json .mcp.json theme={null}
    {
      "mcpServers": {
        "loracle": {
          "type": "http",
          "url": "https://mcp.getloracle.com",
          "headers": {
            "Authorization": "Bearer <your-api-key>"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    Add to `~/.codeium/windsurf/mcp_config.json`:

    ```json ~/.codeium/windsurf/mcp_config.json theme={null}
    {
      "mcpServers": {
        "loracle": {
          "serverUrl": "https://mcp.getloracle.com",
          "headers": {
            "Authorization": "Bearer <your-api-key>"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

Restart your IDE after saving the configuration.

## Available tools

### get\_components

Search your design system catalog by natural language. Returns matching component names, props, and usage documentation.

```javascript theme={null}
get_components({ query: "button with loading state" })
```

Your coding agent calls this tool automatically when it needs to find components. You can also ask it directly — for example, "find a date picker component from our design system."

## Next steps

<Columns>
  <Card title="Loracle CLI" icon="upload" href="/cli">
    Publish or update your design system catalog.
  </Card>

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


# Quick start
Source: https://docs.getloracle.com/quick-start

Get up and running in minutes.

Pick the path that matches your role. Each one takes a few minutes.

## Publish your design system

For teams that maintain a Storybook and want to make it available to AI.

<Steps>
  <Step title="Get an API key">
    Sign in to the [Loracle dashboard](https://app.getloracle.com) and navigate to **Project Settings > API Keys**. Copy your key — it starts with `sk_live_`.
  </Step>

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

  <Step title="Publish">
    ```bash theme={null}
    export LORACLE_API_KEY="sk_live_..."
    loracle publish https://your-storybook.com --version 1.0.0
    ```

    The CLI connects to your Storybook, scrapes every component, and uploads the catalog to Loracle.
  </Step>
</Steps>

[Learn more about the CLI](/cli)

## Use with a coding agent

For developers who want their coding agent to search the design system.

<Steps>
  <Step title="Get an API key">
    Sign in to the [Loracle dashboard](https://app.getloracle.com) and copy your API key from **Project Settings > API Keys**.
  </Step>

  <Step title="Add the MCP to your IDE">
    Add the Loracle MCP endpoint to your IDE's MCP configuration. See [MCP server](/mcp-server) for setup snippets for Cursor, Claude Code, and Windsurf.
  </Step>

  <Step title="Start using it">
    Your coding agent now has access to `get_components` — ask it to find components from your design system and it will query the catalog automatically.
  </Step>
</Steps>

[Learn more about the MCP server](/mcp-server)

## Build stories with AI

For developers who want AI-assisted story generation inside Storybook. Uses [OpenCode](https://opencode.ai) to connect to your existing AI provider credentials.

<Steps>
  <Step title="Install the addon">
    ```bash theme={null}
    npm install @loracle-js/storybook-addon
    ```
  </Step>

  <Step title="Register the addon">
    Add it to your `.storybook/main.ts` addons array:

    ```typescript .storybook/main.ts theme={null}
    const config = {
      addons: [
        // ...other addons
        "@loracle-js/storybook-addon",
      ],
    };
    export default config;
    ```
  </Step>

  <Step title="Launch Storybook">
    Start Storybook and open the **Loracle** panel. The addon uses OpenCode as its coding agent and picks up your existing provider configuration automatically.
  </Step>
</Steps>

[Learn more about the Storybook addon](/storybook-addon)


# Storybook addon
Source: https://docs.getloracle.com/storybook-addon

Build and iterate on stories with AI.

After installing the addon, you can generate and refine story files with AI directly inside Storybook.

<Tip>
  The addon runs on [OpenCode](https://opencode.ai) and connects to your existing AI provider credentials.
</Tip>

## Before you begin

* Storybook 8 or higher
* Node.js 22+
* An AI provider subscription (Anthropic, OpenAI, Google, or Amazon Bedrock)

## Install the addon

<Steps>
  <Step title="Install the package">
    ```bash theme={null}
    npm install @loracle-js/storybook-addon
    ```
  </Step>

  <Step title="Register in your Storybook config">
    ```typescript .storybook/main.ts theme={null}
    const config = {
      addons: [
        // ...other addons
        "@loracle-js/storybook-addon",
      ],
    };
    export default config;
    ```
  </Step>

  <Step title="Start Storybook">
    Launch Storybook and open the **Loracle** panel at the bottom of the screen.
  </Step>
</Steps>

## Configure with opencode.json

The addon uses [OpenCode](https://opencode.ai) to connect to your provider. Use `opencode.json` to choose your AI provider and model, and to connect the addon to your published component catalog via MCP.

```json opencode.json theme={null}
{
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "mcp": {
    "loracle": {
      "type": "remote",
      "url": "https://mcp.getloracle.com",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}
```

| Field         | Why you'd set it                                                                                                                                                            |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider`    | Choose your AI provider: `anthropic`, `amazon-bedrock`, `openai`, or `google`.                                                                                              |
| `model`       | Pick a specific model, such as `claude-sonnet-4-6`, `us.anthropic.claude-sonnet-4-6`, or `gpt-4o`.                                                                          |
| `mcp.loracle` | Give the AI access to your published component catalog so it can look up real components, props, and usage examples when writing stories. See the [MCP guide](/mcp-server). |

Authenticate your provider after saving:

```bash theme={null}
opencode auth login --provider anthropic
```

Without a config file the addon falls back to the provider already connected in OpenCode. See the [OpenCode documentation](https://opencode.ai/docs) for all available options.

<Tip>
  The addon reads MCP config from `opencode.json`, not `.mcp.json`. This keeps the addon's tool access separate from your coding agents.
</Tip>

## Guide the AI with AGENTS.md

The addon runs on OpenCode, so it respects standard agent instruction files: [AGENTS.md](https://agents.md/), `CLAUDE.md`, and others. Use them to set persistent rules for how the AI writes stories.

Useful things to include:

* **Import paths**: Where your components live, so the agent doesn't guess
* **Story structure**: Naming conventions, required exports, file layout
* **Styling rules**: Design tokens over raw CSS, or a specific styling approach
* **Forbidden patterns**: No inline styles, no hardcoded strings, no deprecated APIs

```markdown AGENTS.md theme={null}
# Story guidelines

- Import components from `@acme/ui`, never from internal paths
- Use the `variant` prop for visual styles, not custom CSS
- Every story file must have a default export with `title` and `component`
- Group stories to match the component folder structure (e.g. `Forms/TextInput`)
- Use design tokens from `@acme/theme` for colors and spacing
- Never hardcode text: use descriptive placeholder content
```

Changes take effect on the next prompt. No restart is required.

## Use the chat panel

Open any story and switch to the **Loracle** panel. Describe what you want, and the AI edits the story file while Storybook hot-reloads with the result.

Example prompts:

* "Add a disabled state to this button story"
* "Create variants for small, medium, and large sizes"
* "Style this to match our brand colors"

## Attach an image

Click the image button in the chat input to attach a screenshot or design mockup. The AI uses it as visual context when generating code. Supported formats: PNG, JPEG, and WebP.

## Revert a change

Every AI response snapshots your story file. Hover over any past message to reveal the **Restore** button. Clicking it rolls the file back to that point and reloads the page.

## Troubleshooting

### "Setup required" onboarding screen

The addon couldn't detect an AI provider. Either:

* Create `opencode.json` with your provider and model
* Or authenticate via OpenCode: `opencode auth login --provider anthropic`
* See the [OpenCode provider guide](https://opencode.ai/docs/providers) for all supported providers

### "Error: fetch failed"

The AI provider couldn't be reached. Check that:

* Your provider credentials are valid: run `opencode auth login --provider <provider>`
* Your API key has available credits
* You're not behind a proxy that blocks the provider's API

### AI can't edit my files

By default the addon only allows edits to `*.stories.*` files. If you need broader access, add a custom `permission` field to your `opencode.json`.

## Next steps

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

  <Card title="Loracle CLI" icon="upload" href="/cli">
    Publish your design system to make it available via MCP.
  </Card>
</Columns>