Skip to main content

​
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. 
npx ditto-spec init
FlagDescription
--agentWrite agent configuration (Claude Code or Cursor). See Agent Setup.
--forceOverwrite customized skill files in .claude/commands/. Only applies with --agent.
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.

​
scaffold

Creates a new index.ditto.md Ditto spec file for a component with the correct YAML structure and empty managed keys. 
npx ditto-spec scaffold <ComponentName> --path <dir>
Argument / FlagDescription
<ComponentName>Name of the component (required).
--path <dir>Directory where the spec file is created. Defaults to the current directory.
Example: 
npx ditto-spec scaffold DialogueModal --path src/components/DialogueModal
After scaffolding, add surfaces and tags to the generated file, then run ditto-spec pull to populate style guide rules from the platform.

​
pull

Syncs style guide rules from the Ditto platform into Ditto spec files by tag matching. 
npx ditto-spec pull
FlagDescription
--dry-runShow 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
Requires DITTO_API_KEY. Set it in your environment or in a .env file at the repo root.

​
check

Validates all Ditto spec files: YAML parses correctly, required keys are present, surfaces have tags arrays. Exits non-zero on any failure. 
npx ditto-spec check
Useful as a pre-commit hook or CI step to catch malformed Ditto spec files before they’re merged.

​
list

Prints an inventory of all Ditto specs with their surfaces, tags, and constraints. 
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. 
npx ditto-spec rules
FlagDescription
--styleguide "<name-or-id>"Limit output to one specific style guide.
Requires DITTO_API_KEY. Without --styleguide, output is filtered to guides in your styleguides config (or all guides if unset).

​
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. 
npx ditto-spec create-rules
FlagDescription
--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:
ShapeFields
Style rulename (required), description, examples (array of {from, to}), tags, section
Terminology entryterm (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. 
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
Requires DITTO_API_KEY. After creating rules, run ditto-spec pull to sync them into your Ditto spec files.