Legacy tools

These tools predate the current Ditto CLI (5.x), the MCP server, and scan. They keep working for teams that adopted them, but new integrations should start with Scan your repo.

Legacy CLI mode

Version 5.x of the Ditto CLI pulls text from the current version of Ditto by default and still supports every 4.x feature behind the --legacy flag. Add the flag to any command that v4.5.2 supported:

npx @dittowords/cli --legacy pull [options]
npx @dittowords/cli --legacy project
npx @dittowords/cli --legacy component-folders [options]
npx @dittowords/cli --legacy generate-suggestions [options]
npx @dittowords/cli --legacy replace [options]
npx @dittowords/cli --legacy import-components [options]
npx @dittowords/cli --legacy help [command]

To use legacy and current features in the same repo, keep two config files and point at the legacy one with -c:

npx @dittowords/cli --legacy pull -c ./ditto/legacy-config.yml

Full reference: Legacy CLI installation, configuration, and files. Legacy API endpoints: Legacy API reference.

Ditto React SDK

ditto-react is a React and React Native library that reads the JSON string files written by the CLI and exposes them through a provider and hooks, with first-class support for variants. It works with all JSON output formats. Installation and usage are in the package README on npm. Issues go to dittowords/ditto-react. The library’s last release was 1.6.3; new React projects can use the CLI’s i18next output with react-i18next instead, which needs no Ditto-specific runtime dependency.

Legacy webhook events

These events are only available on legacy webhooks, which are connected directly to the legacy component library; if you joined Ditto after March 2025, you probably aren’t looking for these.

Component Creation

Emitted any time a component is created in Ditto.

{
  "event": "Component_Creation",
  "data": {
		"componentId": "test_component",
		"folderId": "test_folder", // null if not in a folder
		"name": "Test Component",
		"text": "This is a test component.",
		"status": "NONE",
		"notes": "",
		"tags": ["test_tag"]
	}
}

Component Deletion

Emitted any time a component is deleted in Ditto.

{
  "event": "Component_Deletion",
  "data": {
		"componentId": "test_component",
		"folderId": "test_folder", // null if not in a folder
		"name": "Test Component"
	}
}

Component Text Change

Emitted any time a component’s base text is changed in Ditto. Does not emit when variant text, plural text, or rich text styling is changed.

{
  "event": "Component_TextChange",
  "data": {
		"componentId": "test_component",
		"folderId": "test_folder", // null if not in a folder
		"textBefore": "This is a test component.",
		"textAfter": "This is a test component!"
	}
}

Component Status Change

Emitted any time a component’s status is changed in Ditto.

{
  "event": "Component_StatusChange",
  "data": {
		"componentId": "test_component",
		"folderId": "test_folder", // null if not in a folder
		"statusBefore": "NONE",
		"statusAfter": "WIP"
	}
}

Component ID Change

Emitted any time a component’s developer ID is changed in Ditto.

{
  "event": "Component_IdChange",
  "data": {
		"componentIdBefore": "test_component",
		"componentIdAfter": "test_component_1",
		"folderId": "test_folder", // null if not in a folder
	}
}

Test Event

Emitted when sending a test request while creating a webhook.

{
  "event": "TestEvent",
  "data": {
		"message": "Hello, Ditto!"
	}
}

Start here

Concepts

CLI Reference

API Reference

String Formats

MCP Reference

Ditto Specs CLI

Additional Tools

Legacy

Legacy tools

Legacy CLI mode

Ditto React SDK

Legacy webhook events

Component Creation

Component Deletion

Component Text Change

Component Status Change

Component ID Change

Test Event

​Legacy CLI mode

​Ditto React SDK

​Legacy webhook events

​Component Creation

​Component Deletion

​Component Text Change

​Component Status Change

​Component ID Change

​Test Event

Legacy CLI mode

Ditto React SDK

Legacy webhook events

Component Creation

Component Deletion

Component Text Change

Component Status Change

Component ID Change

Test Event