Skip to main content

​
Prerequisites

​
Installation

1

Install the package

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

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
3

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

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",
  "workspaceId": "your-workspace-id"
}
A full config with all options: 
{
  "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

KeyRequiredDescription
apiBaseYesDitto API base URL.
workspaceIdYesYour Ditto workspace ID.
rootsNoRepo-relative directories to search for Ditto spec files. Defaults to ["."].
styleguidesNoList of style guide names or IDs to pull style guide rules from. Defaults to all guides in the workspace.
localesNoLocale codes to include (e.g. ["de-DE", "fr-FR"]). Includes locale-scoped style guides matching these codes. Base (no-variant) guides are always included.
defaultStyleguideNoDefault 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
Appends a Ditto Specs section to CLAUDE.md (creates the file if absent) and writes three skill files to .claude/commands/:
SkillWhat it does
/ditto-spec-componentAnalyze a component, create Ditto spec files, auto-fill surfaces and tags, sync style guide rules
/ditto-spec-auditAudit copy in component instances against style guide rules in their Ditto specs
/ditto-spec-gapsFind style guide rule gaps, then create new rules on the platform
See Agent Skills for detailed documentation of each skill.
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.