Skip to main content

​
What the CLI does

The Ditto CLI is the command-line surface for two jobs: importing the strings already in a codebase (scan) and writing Ditto’s text to disk as string files your app loads (pull). It wraps the Ditto API, so anything the CLI does can also be done with direct API calls. Teams run it locally and in CI.

​
Install

Node.js 20 or higher is required as of version 5.6.0.
You can run every command with npx and install nothing:
To pin a version in a project, install it as a development dependency:
Then npx @dittowords/cli <command> uses the installed version.

​
Log in

Log in through your browser:
A browser tab opens for you to log in to Ditto and approve access. The session is saved to $HOME/.config/ditto, so you only do this once per machine. There is no API key to create or paste, and commands act as you, with your Ditto account’s permissions. To sign out, run logout.
login and logout require version 5.7.0 or higher.

​
In CI, or anywhere without a browser

Browser login is the recommended way to authenticate, including for coding agents working on your machine (the agent tells you when the tab is about to open). Use an API key only where no browser is available, such as a CI job, and set it in the DITTO_TOKEN environment variable.
1

Create an API key (a workspace admin does this once)

The steps are in API authentication.
2

Set the variable

In CI, store the key as a secret and expose it as DITTO_TOKEN. The Ditto Specs CLI reads the same variable, and the MCP server accepts the key as an Authorization: token header.
DITTO_TOKEN takes precedence over a saved login, so a machine with both keeps using the API key. Commands then act as the user who generated the key rather than the person running them. Use it in pipelines, not on developer machines.

​
Credential precedence

The CLI uses the first credential it finds:
  1. The DITTO_TOKEN environment variable
  2. A session saved by login
  3. An API key saved by an earlier run
  4. A prompt for an API key
Sessions and API keys are saved to $HOME/.config/ditto. The file holds credentials, so treat it like any other secret: keep it out of commits and out of shared images. To use a different file, set DITTO_CONFIG_FILE to its path.
To switch Ditto accounts, run logout and then login again. If DITTO_TOKEN is set, unset or replace it first; it outranks a saved session, so your commands would keep using the API key.We don’t recommend editing the credentials file by hand. To replace a saved API key, delete $HOME/.config/ditto; the CLI prompts for a new key the next time it runs.
A session renews itself as you keep using the CLI. If one sits unused long enough to expire, the next command stops and asks you to run login again.