Skip to main content

​
Overview

The Ditto CLI allows developers to access the Ditto API directly from the command line. The Ditto CLI updates text directly in local development. Teams can also build workflows with the CLI, including utilizing it in CI/CD.

​
Installation

Node.js 20 or higher is required as of version 5.6.0, which includes packages that depend on Node 20+.
To install the CLI as a development dependency:
After installation, you can get a list of the available commands by running the help command.
Note: npx comes with npm 5.2 or higher

​
Authentication

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’s no API key to create or paste, and commands act as you — your Ditto account and its permissions. To sign out, run logout.
login and logout require version 5.7.0 or higher.

​
In CI, or anywhere without a browser

Set the DITTO_TOKEN environment variable to an API key. You can generate an API key in your developer integrations settings.
DITTO_TOKEN takes precedence over a saved login, so a machine with both keeps using the API key. Commands act as the user who generated the key rather than the person running them, which is what you want for a pipeline and what you don’t want on a shared laptop.

​
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 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 authentication file by hand. To replace a saved API key, delete the $HOME/.config/ditto file and you’ll be prompted for a new key the next time the CLI executes.
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.