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.
$ 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.$ npx @dittowords/cli
When installed, the name of the CLI's binary is
ditto-cliSince 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.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.
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!
Last modified 3mo ago