DeepL CLI - DeepL Documentation

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

The CLI requires Node.js (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

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:

deepl init

Or set your API key directly:

deepl auth set-key YOUR_API_KEY

Or use an environment variable:

export DEEPL_API_KEY=YOUR_API_KEY

2. Translate text

deepl translate "Hello, world!" --to es
# ¡Hola, mundo!

3. Enhance your writing

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

deepl translate "Thank you for your patience" --to de --formality more \
  --context "Customer support email to a long-standing client"

Translate a document

deepl document translate report.pdf --to fr --output report-fr.pdf

Batch translate a directory

deepl translate --file src/locales/en/ --to de,fr,es --output src/locales/

Watch mode for development

deepl watch ./content/en --to de,fr --output ./content/

Git hooks integration

Automatically translate changed files before each commit:

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

​Installation

​Quick start

​1. Set up authentication

​2. Translate text

​3. Enhance your writing

​Key capabilities

​Usage examples

​Translate with context and formality

​Translate a document

​Batch translate a directory

​Watch mode for development

​Git hooks integration

​Developer workflow features

​Further reading

Installation

Quick start

1. Set up authentication

2. Translate text

3. Enhance your writing

Key capabilities

Usage examples

Translate with context and formality

Translate a document

Batch translate a directory

Watch mode for development

Git hooks integration

Developer workflow features

Further reading