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

> ## Agent Instructions
> These are Ditto's developer docs. Ditto is a single source of truth for product copy across design, review, localization, and code.
> The first step on any codebase is a scan: https://developer.dittowords.com/get-started/scan-your-repo.md. That page also covers reviewing the style guide Ditto drafts from the scan. After it, the follow-on guides are Connect Figma files and Set up localization (under /guides/) and Connect the Ditto MCP (the Setup page of the MCP reference).
> Two different MCP servers: the Ditto MCP server at https://api.dittowords.com/v2/mcp gives an agent a workspace's text and style guide rules; the documentation MCP server at https://developer.dittowords.com/mcp searches these docs.
> Prefer logging in with a Ditto account (npx -y @dittowords/cli@latest login; OAuth in MCP clients) over API keys. API keys are for CI and headless clients only.
> Commands are complete as written and use npx -y @dittowords/cli@latest; nothing needs a global install.

# Ditto Specs CLI commands

> All commands available in the Ditto Specs CLI

## init

First-time setup. Creates `dittospec.config.json` and `workspace.ditto.md` in the current directory, then detects your agent environment and prints setup suggestions.

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

| Flag | Description |
| - | - |
| `--agent` | Write agent configuration (Claude Code or Cursor). See [Agent Setup](/ditto-specs-cli-reference/setup#agent-setup). |
| `--force` | Overwrite customized skill files in `.claude/commands/`. Only applies with `--agent`. |

<Info>
  Re-running `init` is safe. Existing config files are not overwritten. With `--agent`, skill files are updated to the current CLI version and `CLAUDE.md` sections that already exist are skipped.
</Info>

## scaffold

Creates a new `index.ditto.md` Ditto spec file for a component with the correct YAML structure and empty managed keys.

```bash theme={null}
npx ditto-spec scaffold <ComponentName> --path <dir>
```

| Argument / Flag | Description |
| - | - |
| `<ComponentName>` | Name of the component (required). |
| `--path <dir>` | Directory where the spec file is created. Defaults to the current directory. |

Example:

```bash theme={null}
npx ditto-spec scaffold DialogueModal --path src/components/DialogueModal
```

<Info>
  After scaffolding, add surfaces and tags to the generated file, then run `ditto-spec pull` to populate style guide rules from the platform.
</Info>

## pull

Syncs style guide rules from the Ditto platform into Ditto spec files by tag matching.

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

| Flag | Description |
| - | - |
| `--dry-run` | Show what would change without writing files. |

The pull process:

1. Discovers all Ditto spec files under the configured `roots`
2. Fetches style guides from the API
3. Flattens style guide rules and wordlist entries across guides (filtered by `styleguides` config if set)
4. Separates base rules from locale-scoped rules (included when `locales` is configured)
5. Matches rules to Ditto specs by tag intersection
6. Rewrites the `rules` and `locales` keys in each file's YAML frontmatter

<Info>
  Requires `DITTO_TOKEN`. Set it in your environment or in a `.env` file at the repo root.
</Info>

## check

Validates all Ditto spec files: YAML parses correctly, required keys are present, surfaces have `tags` arrays. Exits non-zero on any failure.

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

<Info>
  Useful as a pre-commit hook or CI step to catch malformed Ditto spec files before they're merged.
</Info>

## list

Prints an inventory of all Ditto specs with their surfaces, tags, and constraints.

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

## rules

Prints every style guide rule on the platform, grouped by style guide and section. Shows each section's kind (`rules` or `wordlist`) and section ID.

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

| Flag | Description |
| - | - |
| `--styleguide "<name-or-id>"` | Limit output to one specific style guide. |

<Info>
  Requires `DITTO_TOKEN`. Without `--styleguide`, output is filtered to guides in your `styleguides` config (or all guides if unset).
</Info>

## create-rules

Creates a batch of style rules or terminology entries on the Ditto platform. Takes a JSON array of rules on stdin or via `--file`.

```bash theme={null}
npx ditto-spec create-rules
```

| Flag | Description |
| - | - |
| `--file <path>` | Read the JSON array from a file instead of stdin. |
| `--styleguide "<name-or-id>"` | Target style guide. Overrides the `defaultStyleguide` config. |
| `--section "<name-or-id>"` | Default section for rules that don't specify their own. Applies only to rules matching the section's kind. |

Each rule in the array is one of two shapes:

| Shape | Fields |
| - | - |
| Style rule | `name` (required), `description`, `examples` (array of `{from, to}`), `tags`, `section` |
| Terminology entry | `term` (required), `disallowed` (array of strings), `description`, `tags`, `section` |

Both shapes can be mixed in one batch. Each rule's optional `section` (name or ID, as shown by `ditto-spec rules`) maps it to an existing section of the style guide. The section's kind must match the rule's shape — `rules` sections for style rules, `wordlist` sections for terminology entries.

<CodeGroup>
  ```bash stdin theme={null}
  npx ditto-spec create-rules <<'EOF'
  [
    {
      "name": "Use active voice in CTAs",
      "description": "Lead CTAs with a verb",
      "tags": ["button", "call-to-action"],
      "examples": [{"from": "Your settings", "to": "Open settings"}],
      "section": "UI Patterns"
    },
    {
      "term": "sign up",
      "disallowed": ["signup", "sign-up"],
      "description": "Two words as a verb",
      "section": "Word List"
    }
  ]
  EOF
  ```

  ```bash --file theme={null}
  npx ditto-spec create-rules --file rules.json --styleguide "Brand Voice"
  ```
</CodeGroup>

<Info>
  Requires `DITTO_TOKEN`. After creating rules, run `ditto-spec pull` to sync them into your Ditto spec files.
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.