> ## Documentation Index
> Fetch the complete documentation index at: https://developer.dittowords.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These are Ditto's developer docs. Ditto is a single source of truth for product copy across design, review, localization, and code.
> The first step on any codebase is a scan: https://developer.dittowords.com/get-started/scan-your-repo.md. That page also covers reviewing the style guide Ditto drafts from the scan. After it, the follow-on guides are Connect Figma files and Set up localization (under /guides/) and Connect the Ditto MCP (the Setup page of the MCP reference).
> Two different MCP servers: the Ditto MCP server at https://api.dittowords.com/v2/mcp gives an agent a workspace's text and style guide rules; the documentation MCP server at https://developer.dittowords.com/mcp searches these docs.
> Prefer logging in with a Ditto account (npx -y @dittowords/cli@latest login; OAuth in MCP clients) over API keys. API keys are for CI and headless clients only.
> Commands are complete as written and use npx -y @dittowords/cli@latest; nothing needs a global install.

# Install and log in to the Ditto CLI

> Install the Ditto CLI and log in with your Ditto account so you can scan a codebase and pull string files.

## What the CLI does

The Ditto CLI is the command-line surface for two jobs: importing the strings already in a codebase (`scan`) and writing Ditto's text to disk as string files your app loads (`pull`). It wraps the [Ditto API](/api-reference/authentication), so anything the CLI does can also be done with direct API calls. Teams run it locally and in CI.

## Install

<Info>
  **Node.js 20 or higher** is required as of version `5.6.0`.
</Info>

You can run every command with `npx` and install nothing:

```bash theme={null}
npx -y @dittowords/cli@latest --help
```

To pin a version in a project, install it as a development dependency:

<CodeGroup>
  ```bash npm theme={null}
  npm i --save-dev @dittowords/cli
  ```

  ```bash yarn theme={null}
  yarn add --dev @dittowords/cli
  ```
</CodeGroup>

Then `npx @dittowords/cli <command>` uses the installed version.

## Log in

Log in through your browser:

```bash theme={null}
npx -y @dittowords/cli@latest login
```

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 is no API key to create or paste, and commands act as **you**, with your Ditto account's permissions.

To sign out, run [`logout`](/cli-reference/commands#logout).

<Info>`login` and `logout` require version `5.7.0` or higher.</Info>

## In CI, or anywhere without a browser

Browser login is the recommended way to authenticate, including for coding agents working on your machine (the agent tells you when the tab is about to open). Use an API key only where no browser is available, such as a CI job, and set it in the `DITTO_TOKEN` environment variable.

<Accordion title="Use an API key in CI">
  <Steps>
    <Step title="Create an API key (a workspace admin does this once)">
      The steps are in [API authentication](/api-reference/authentication#create-an-api-key).
    </Step>

    <Step title="Set the variable">
      ```bash theme={null}
      export DITTO_TOKEN='<your-api-key>'
      ```

      In CI, store the key as a secret and expose it as `DITTO_TOKEN`. The [Ditto Specs CLI](/ditto-specs-cli-reference/setup) reads the same variable, and the [MCP server](/guides/connect-the-mcp#api-key-for-ci-and-headless-clients) accepts the key as an `Authorization: token` header.
    </Step>
  </Steps>
</Accordion>

`DITTO_TOKEN` takes precedence over a saved login, so a machine with both keeps using the API key. Commands then act as the user who generated the key rather than the person running them. Use it in pipelines, not on developer machines.

## 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

<AccordionGroup>
  <Accordion title="Where credentials are stored">
    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 use a different file, set `DITTO_CONFIG_FILE` to its path.
  </Accordion>

  <Accordion title="Switching accounts or keys">
    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 credentials file by hand. To replace a saved API key, delete `$HOME/.config/ditto`; the CLI prompts for a new key the next time it runs.
  </Accordion>

  <Accordion title="Expired sessions">
    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.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.