Skip to main content
All commands run through npx, so nothing needs to be installed globally:
The examples below omit -y and @latest for brevity. Every command that talks to Ditto needs a credential: a saved browser login or the DITTO_TOKEN environment variable. See Install and log in.

​
scan

Analyzes a path for user-facing text and sends the candidates to Ditto, where you review them and turn them into library components. This is the first step of setting up Ditto on a codebase; the walkthrough is Scan your repo.
[path] is the file or directory to scan; it defaults to the current directory. The CLI extracts candidate strings, uploads them, and prints a link to the review page:
Requires Node.js 20 or higher and a credential. Without a saved login or DITTO_TOKEN, scan stops and prompts for an API key. --list-directories and --local need no credential.
What is uploaded. For each candidate: the text, file path and line, how it was detected (markup text, attribute value, localization resource value, or other), the i18n key and locale if it came from a translation file, surrounding source lines, and nearby identifiers. In a Git checkout with a remote, also the remote’s host and path, commit, branch, scanned paths, and file renames since the last scan. Never credentials. Requires a clean default branch. Scan records the commit and branch it read, and the code links Ditto builds point at them. To keep those links on code your team shares, scan runs only from a clean checkout of your repository’s default branch. It stops, without uploading, on uncommitted changes, a non-default branch, or a detached HEAD:
The default branch comes from origin/HEAD, falling back to a local main or master. Because that reference is set when you clone and doesn’t update on its own, a mismatch is confirmed against your remote first, so a branch renamed after you cloned won’t block you. Scanning outside a Git repository is unaffected. Preview counts by directory. Extract candidates, print a per-directory count, and exit without uploading:
Counts are rolled up, so each directory includes its subdirectories. Directories are listed in tree order, indented by depth, with the whole-scan total first. Write candidates locally instead of uploading.
Writes <out-dir>/candidates.ndjson, one JSON object per line. Add --prefix <prefix> to prefix the file name. Each object has value_raw, snapshot_text, detection_kind (markup_text, markup_attr, resource_value, other), location (file, line, column), language, framework, i18n_key, locale_key, source_context, context_identifiers, and usage_evidence. Plan limits. Trial workspaces can classify up to 1,000 strings in total across all of their scans; paid plans have no cap. Re-scanning a directory does not count twice. If a scan would exceed the remaining budget, the CLI stops before uploading and suggests the largest subdirectories that fit (up to 10):
Options

​
pull

Fetches the latest text from Ditto and writes string files to disk, as described by your config file.
Files are written to the output directory in your config (./ditto by default). For the structure of the generated files, see Files. Because pull updates files in your repo, you manage the result like any other change: commit it, open a pull request, or run it in CI before a build. Custom config location. By default pull reads ./ditto/config.yml relative to where you run it. Use -c / --config for another path, or set the DITTO_PROJECT_CONFIG_FILE environment variable:
Request metadata. -m / --meta attaches arbitrary key-value data to the API requests, which shows in Ditto’s activity history:

​
login

Logs in to Ditto through your browser and saves the session to $HOME/.config/ditto.
A browser tab opens for you to log in and approve access. Later commands reuse the session and renew it as needed. If DITTO_TOKEN is set, the CLI keeps using that API key instead, because an environment variable outranks a saved session; see credential precedence.
login and logout require version 5.7.0 or higher.

​
logout

Forgets the session saved on this machine and revokes it with Ditto.
Reports back if DITTO_TOKEN is still set, because commands would keep working with that API key.