Ditto CLI
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.

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.

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 CLI README 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.
​
Last modified 26d ago