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

# 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_API_KEY`. 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_API_KEY`. 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_API_KEY`. After creating rules, run `ditto-spec pull` to sync them into your Ditto spec files.
</Info>