Setup

Prerequisites

Node.js >= 18
A Ditto API key — generate one from your developer integrations settings
A Ditto workspace with at least one style guide

Installation

Install the package

npm i --save-dev @dittowords/spec-cli

yarn add --dev @dittowords/spec-cli

Initialize your project

Run the init command from your repo root:

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

Set your API key

Set the DITTO_API_KEY environment variable:

export DITTO_API_KEY=your-api-key

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

Verify the connection

Run a dry-run pull to confirm everything is wired up:

npx ditto-spec pull --dry-run

You should see a list of discovered Ditto spec files and what style guide rules would be written.

Configuration

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

{
  "apiBase": "https://api.dittowords.com"
}

A full config with all options:

{
  "apiBase": "https://api.dittowords.com",
  "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.
`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:

npx ditto-spec init --agent

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 for detailed documentation of each skill.

Cursor

Appends a Ditto Specs section to .cursorrules with instructions for reading and creating Ditto specs.

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.

Overview

API Reference

CLI Reference

MCP Reference

Ditto Specs CLI Reference

Additional Tools

Legacy

Prerequisites

Installation

Configuration

Properties

Agent setup

​Prerequisites

​Installation

​Configuration

​Properties

​Agent setup

Prerequisites

Installation

Configuration

Properties

Agent setup