Ditto CLI

The Ditto CLI simplifies the process of syncing a codebase with a Ditto.


The Ditto CLI simplifies the process of syncing a codebase with Ditto and enables you to immediately start fetching data without having to build your own HTTP requests.
The CLI prioritizes simplicity and ease-of-use over flexibility; for a comprehensive look into everything the API supports, see our API Reference.


This page provides an introduction to the CLI and how it works. For a detailed reference on CLI behavior and all supported configuration options, please refer to the CLI README on GitHub.


The Ditto CLI can be installed via npm
$ npm install @dittowords/cli
The CLI can be installed globally using the -g flag or can be installed as a development dependency using the -D flag; we strongly recommend the latter.
It can also be executed with or without installing using npx:
$ npx @dittowords/cli
When installed, the name of the CLI's binary is ditto-cli


Since the Ditto CLI uses the Ditto API under the hood, you'll need to create an API key. On its first execution, the CLI will ask for the key:
$ npx @dittowords/cli
│ │
│ Welcome to the Ditto CLI. │
│ │
│ We're glad to have you here. │
│ │
What is your API key? >
Paste your API key at the prompt and hit enter. You should see the following message indicating that you've authenticated successfully:
✔ What is your API key? · xxx-xxx-xxx
Thanks for authenticating.
We'll save the key to: /Users/username/.config/ditto
Authentication only happens a single time. After you've authenticated once, you can enable the CLI for use in one or more directories by running the ditto-cli command and choosing the projects you'd like to sync from.
The CLI also supports reading an API key directly from the environment variable DITTO_API_KEY.
Any API key collected by the CLI is stored in the file ~/.config/ditto If you ever want to change out the API key you're currently using, you can delete this file and then re-run the CLI to regenerate it.

How it works

For every command that is run using the Ditto CLI, a local folder called ditto (./ditto relative to the current working directory) is consulted as the source of truth for how that command should execute.
If you run any CLI command in a directory where a ditto folder doesn't exist, one will be automatically created for you.
Inside of the ditto folder lives a file called config.yml, which is where all CLI configuration options should be specified; these include which projects should be synced with the current directory, what format data should be stored in, and whether or not variant data should be included.
Some of the CLI's commands are oriented towards helping you manage the config.yml file, like adding (ditto-cli project add) or removing (ditto-cli project remove) projects.
The primary action used for syncing data is ditto-cli pull - this command will read the list of projects from ditto/config.yml and use the Ditto API to fetch and store data about those projects in the ditto folder to be consumed in your application.

Additional Reference

See the CLI README for a full list of CLI commands and supportedconfig.yml options.
See Example Projects for references of using the CLI to integrate with Ditto.

Feature Requests

Have additional uses cases or improvements you'd want our React SDK to handle? Let us know by opening an issue, or feel free to open a pull request!