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

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