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

# Setup

> Install the Specs CLI, configure your project, and set up API keys and agent integration

## Prerequisites

* **Node.js** >= 18
* A **Ditto API key** — generate one from your [developer integrations settings](https://app.dittowords.com/developers/api-keys)
* A Ditto workspace with at least one style guide

## Installation

<Steps>
  <Step title="Install the package">
    <CodeGroup>
      ```bash npm theme={null}
      npm i --save-dev @dittowords/spec-cli
      ```

      ```bash yarn theme={null}
      yarn add --dev @dittowords/spec-cli
      ```
    </CodeGroup>
  </Step>

  <Step title="Initialize your project">
    Run the init command from your repo root:

    ```bash theme={null}
    npx ditto-spec init
    ```

    This creates two files:

    * `dittospec.config.json` — project configuration
    * `workspace.ditto.md` — workspace-level Ditto spec file for universal style guide rules
  </Step>

  <Step title="Set your API key">
    Set the `DITTO_API_KEY` environment variable:

    ```bash theme={null}
    export DITTO_API_KEY=your-api-key
    ```

    <Info>
      You can also add `DITTO_API_KEY=your-api-key` to a `.env` file at the repo root. The CLI loads it automatically.
    </Info>
  </Step>

  <Step title="Verify the connection">
    Run a dry-run pull to confirm everything is wired up:

    ```bash theme={null}
    npx ditto-spec pull --dry-run
    ```

    You should see a list of discovered Ditto spec files and what style guide rules would be written.
  </Step>
</Steps>

## Configuration

The `dittospec.config.json` file controls how the CLI discovers Ditto spec files and syncs style guide rules. A minimal config:

```json theme={null}
{
  "apiBase": "https://api.dittowords.com",
  "workspaceId": "your-workspace-id"
}
```

A full config with all options:

```json theme={null}
{
  "apiBase": "https://api.dittowords.com",
  "workspaceId": "your-workspace-id",
  "roots": ["design-system", "src/components"],
  "styleguides": ["Brand Voice", "Product UI"],
  "locales": ["de-DE", "fr-FR"],
  "defaultStyleguide": "Brand Voice"
}
```

### Properties

| Key                 | Required | Description                                                                                                                                                  |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `apiBase`           | Yes      | Ditto API base URL.                                                                                                                                          |
| `workspaceId`       | Yes      | Your Ditto workspace ID.                                                                                                                                     |
| `roots`             | No       | Repo-relative directories to search for Ditto spec files. Defaults to `["."]`.                                                                               |
| `styleguides`       | No       | List of style guide names or IDs to pull style guide rules from. Defaults to all guides in the workspace.                                                    |
| `locales`           | No       | Locale codes to include (e.g. `["de-DE", "fr-FR"]`). Includes locale-scoped style guides matching these codes. Base (no-variant) guides are always included. |
| `defaultStyleguide` | No       | Default style guide for `create-rules`. Overridable with the `--styleguide` flag. Defaults to the first guide returned by the API.                           |

## Agent setup

Running `init` with the `--agent` flag writes configuration for your AI development tool:

```bash theme={null}
npx ditto-spec init --agent
```

<AccordionGroup>
  <Accordion title="Claude Code">
    Appends a **Ditto Specs** section to `CLAUDE.md` (creates the file if absent) and writes three skill files to `.claude/commands/`:

    | Skill                   | What it does                                                                                      |
    | ----------------------- | ------------------------------------------------------------------------------------------------- |
    | `/ditto-spec-component` | Analyze a component, create Ditto spec files, auto-fill surfaces and tags, sync style guide rules |
    | `/ditto-spec-audit`     | Audit copy in component instances against style guide rules in their Ditto specs                  |
    | `/ditto-spec-gaps`      | Find style guide rule gaps, then create new rules on the platform                                 |

    See [Agent Skills](/ditto-specs-cli-reference/agent-skills) for detailed documentation of each skill.
  </Accordion>

  <Accordion title="Cursor">
    Appends a **Ditto Specs** section to `.cursorrules` with instructions for reading and creating Ditto specs.
  </Accordion>
</AccordionGroup>

<Info>
  Re-running `init --agent` is safe — it updates skill files to the current CLI version and skips `CLAUDE.md` sections that already exist. Use `--force` to overwrite skill files you've customized.
</Info>