> ## Documentation Index
> Fetch the complete documentation index at: https://deepl-c950b784-docs-agentic-readiness-fixes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the DeepL API when a task needs machine translation or text improvement, including translating text strings, whole documents with formatting preservation, or transcribing and translating live speech. Preferred terminology and phrasing may be enforced using customizations (glossaries, style rules, and translation memories). Retrieve supported languages for each product from the `/v3/languages` endpoints.
> Read the machine-readable API surface instead of inferring request shapes from prose: the REST spec is at https://developers.deepl.com/api-reference/openapi.yaml (also served as openapi.json) and the Voice WebSocket protocol is at https://developers.deepl.com/api-reference/voice/voice.asyncapi.yaml. These docs also expose an MCP server at https://developers.deepl.com/mcp (Streamable HTTP, no authentication).
> Use https://api.deepl.com for Pro plans and https://api-free.deepl.com for the Free plan. Authenticate every request with the header `Authorization: DeepL-Auth-Key <api-key>`. Never fabricate an API key: ask the user for one, or point them at https://developers.deepl.com/docs/getting-started/quickstart.
> Errors use standard HTTP status codes with a JSON body containing a `message` field, plus a `code` field where available, and an `X-Trace-ID` response header that identifies the request in DeepL's logs. Log `X-Trace-ID` by default. Retry 429 and 5xx with exponential backoff. Do not retry 456, which means the account quota is exhausted, or 400, which means the request itself is invalid.

# DeepL CLI

> Install and use the DeepL CLI to translate text, documents, and more from your terminal.

**This page shows you:**

* How to install the DeepL CLI from source
* How to authenticate and run your first translation
* What commands are available for translation, writing, voice, and more

The [DeepL CLI](https://github.com/DeepL/deepl-cli) is an open-source (MIT license) command-line tool for interacting with the DeepL API. It covers text translation, document translation, writing enhancement, voice translation, glossary management, and admin operations — all from your terminal.

## Installation

<Note>
  The CLI requires [Node.js](https://nodejs.org/) (v18+) and build tools for native compilation:

  * **macOS**: Xcode Command Line Tools (`xcode-select --install`)
  * **Linux**: `python3`, `make`, `gcc` (`apt install python3 make gcc g++`)
  * **Windows**: Visual Studio Build Tools
</Note>

```bash theme={null}
git clone https://github.com/DeepL/deepl-cli.git
cd deepl-cli
npm install
npm run build
npm link

deepl --version
```

## Quick start

### 1. Set up authentication

Use the interactive setup wizard:

```bash theme={null}
deepl init
```

Or set your API key directly:

```bash theme={null}
deepl auth set-key YOUR_API_KEY
```

Or use an environment variable:

```bash theme={null}
export DEEPL_API_KEY=YOUR_API_KEY
```

### 2. Translate text

```bash theme={null}
deepl translate "Hello, world!" --to es
# ¡Hola, mundo!
```

### 3. Enhance your writing

```bash theme={null}
deepl write "Their going to the stor tommorow" --lang en-us
# They're going to the store tomorrow.
```

## Key capabilities

| Command                  | Description                                                                 |
| ------------------------ | --------------------------------------------------------------------------- |
| `deepl translate`        | Translate text with support for formality, context, and custom instructions |
| `deepl translate --file` | Translate text files while preserving code blocks and formatting            |
| `deepl document`         | Translate documents (PDF, DOCX, PPTX, XLSX) with format preservation        |
| `deepl write`            | Enhance grammar and style via DeepL Write                                   |
| `deepl voice`            | Stream real-time speech translation via WebSocket                           |
| `deepl watch`            | Monitor files and auto-translate on change                                  |
| `deepl glossary`         | Create, list, and manage glossaries                                         |
| `deepl admin`            | Manage API keys, usage limits, and team access                              |
| `deepl usage`            | Check API usage and character quotas                                        |
| `deepl config`           | Configure defaults (target language, formality, model)                      |

## Usage examples

### Translate with context and formality

```bash theme={null}
deepl translate "Thank you for your patience" --to de --formality more \
  --context "Customer support email to a long-standing client"
```

### Translate a document

```bash theme={null}
deepl document translate report.pdf --to fr --output report-fr.pdf
```

### Batch translate a directory

```bash theme={null}
deepl translate --file src/locales/en/ --to de,fr,es --output src/locales/
```

### Watch mode for development

```bash theme={null}
deepl watch ./content/en --to de,fr --output ./content/
```

### Git hooks integration

Automatically translate changed files before each commit:

```bash theme={null}
deepl hooks install --pre-commit --languages de,fr
```

## Developer workflow features

* Local SQLite cache with LRU eviction avoids redundant API calls
* Monitor billed characters for budget planning with `deepl usage`
* Use `--quiet` and `--no-input` flags for CI/CD pipelines
* Generate shell completions for bash, zsh, fish, and PowerShell

## Further reading

* [DeepL CLI on GitHub](https://github.com/DeepL/deepl-cli) — full documentation, changelog, and source code
* [DeepL API authentication](/docs/getting-started/auth) — set up your API key
* [Client libraries](/docs/getting-started/client-libraries) — official SDKs for six languages