CLI Reference

📝
Ditto
Search…
📝
CLI Reference
The Ditto CLI simplifies the process of syncing a codebase with a Ditto.
Overview
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.
Installation
The Ditto CLI can be installed via npm​
1
$ npm install @dittowords/cli
Copied!
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:
1
$ npx @dittowords/cli
Copied!
When installed, the name of the CLI's binary is ditto-cli
Authentication
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:
1
$ npx @dittowords/cli
2
​
3
┌──────────────────────────────────┐
4
│                                  │
5
│   Welcome to the Ditto CLI.      │
6
│                                  │
7
│   We're glad to have you here.   │
8
│                                  │
9
└──────────────────────────────────┘
10
    
11
What is your API key? >
Copied!
Paste your API key at the prompt and hit enter. You should see the following message indicating that you've authenticated successfully:
1
✔ What is your API key? · xxx-xxx-xxx
2
​
3
Thanks for authenticating.  
4
We'll save the key to: /Users/username/.config/ditto
Copied!
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.
Your API key is stored in the file ~/.config/ditto

If you ever want to change out the API key you're currently using, you can edit this file manually.
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 command reference below for a full list of CLI commands and supportedconfig.yml options.
See our example project for reference of how the CLI can be used to easily integrate Ditto with a React project.
Command Reference
pull
Usage: ditto-cli pull 
Text from the projects specified in ditto/config.yml is fetched and stored in (a) JSON file(s) in the ditto folder.
Additional Details
Whenever pull is executed, all .json and .js files present in the ditto folder will be removed before any data is written.
If the variants option is unspecified or set to false in ditto/config.yml, all text data will be stored in a single file: ditto/text.json.
If the variants option is set to true in ditto/config.yml, text data will be split across multiple files:
base.json will contain the base text for the specified projects
One additional JSON file will be generated for each variant that exists in the Ditto workspace associated with the provided API key, following the pattern [variant_api_id].json.
Independent of the value of the variants option, an index.js driver file will always be generated to provide an easy entry point by for front-end JavaScript applications to import all of the data synced from Ditto. See our example project for reference on how this file can be used.
If the format option is set to flat or structured in ditto/config.yml, text data will be stored in the specified format. Otherwise, text data will be stored in the default format -- grouped by frames and blocks.
​
project add
Usage: ditto-cli project add
A list of Ditto projects and the component library are presented in a prompt. When an option is selected, the list of projects in ditto/config.yml is updated to include the selected option. 
Additional Details
The prompt is only populated with projects that have developer mode enabled (including the component library) and are not already listed in ditto/config.yml.
A warning will display and the CLI will automatically exit with a non-error status code if the command is executed while ditto/config.yml already contains all projects in the workspace that have developer mode enabled.
​
project remove
Usage: ditto-cli project remove
The Ditto projects (including the component library) currently listed in ditto/config.yml are presented in a prompt. When an option is selected, the list of projects in ditto/config.yml is updated to exclude the selected option.
Additional Details
The prompt is only populated with the projects listed in ditto/config.yml.
A warning will display and the CLI will automatically exit with a non-error status code if the command is executed without any projects (including the component library) listed in ditto/config.yml .
config.yml Reference
The Ditto CLI will read from ditto/config.yml on the execution of every command. See a list of the supported options below.
projects (required)
A list of projects (including the component library) that text data should be pulled from. Each option should include an id property and a name property; the name property does not have to be an exact match with the name of the project in Ditto, but it will be for any projects added via the project add command.
format (optional)
The format the CLI should store text data in. If unspecified, text will be stored in a default format grouped by frames and blocks.
Supported Values
Unspecified
structured
flat 
variants (optional)
Whether or not the CLI should fetch and store variant data alongside the base text for the specified projects.
If true, text data will be stored across multiple JSON files in the ditto folder. If false or unspecified, text data will be stored in a single JSON file in the ditto folder. See the pull command for more details.
Supported Values
Unspecified
true
false
Full config example
1
projects:
2
    - name: Ditto Component Library
3
      id: ditto_component_library
4
    - name: Example Project
5
      id: 615b84ab22539b4ab78e5d11
6
format: flat
7
variants: true
Copied!
Reminder: the formatandvariantskeys are optional
​