deepl-cli

CLI tool for translating text using the DeepL API. Pipe-friendly, supports context and formality options.

Prerequisites

• Node.js >= 18
• A DeepL API key (free tier: 500,000 characters/month)

Installation

npm install -g @daliusd/deepl-cli

Configuration

Create ~/.config/deepl-cli/config.json:

mkdir -p ~/.config/deepl-cli

Option A -- Static API key:

{
  "api_key": "your-deepl-api-key"
}

Option B -- Command-based key (for password managers like pass, 1Password CLI, etc.):

{
  "api_key_command": "pass show deepl-api-key"
}

If both are present, api_key_command takes precedence.

Commands

All translation is done via a single command:

deepl-cli [options] [text]

Basic Translation

deepl-cli -t de "Hello, world!"

Specify Source Language

deepl-cli -t de -s en "Hello"

By default the source language is auto-detected. Use -s only when auto-detection is insufficient.

Context-Aware Translation

Context influences the translation but is not itself translated or billed:

deepl-cli -t de -c "This is a greeting in a formal business email" "Hello"

Formality Control

# Formal
deepl-cli -t de -f more "How are you?"

# Informal
deepl-cli -t de -f less "How are you?"

Valid formality values: less, more, default, prefer_less, prefer_more.

Piped Input

echo "Hello, world!" | deepl-cli -t de

Translated text goes to stdout with no extra formatting, making it pipeline-friendly:

echo "Hello" | deepl-cli -t de | pbcopy

Verbose Mode

Metadata is written to stderr so stdout remains clean:

deepl-cli -t de -v "Hello, world!"
# stdout: Hallo, Welt!
# stderr: Detected source language: en
# stderr: Billed characters: 13

Options Reference

Common Language Codes

Language codes are case-insensitive and follow ISO 639-1.

Source languages (or omit for auto-detection):

Target languages (some include regional variants):

See the DeepL API documentation for the full list.

Tips

• No arguments or --help shows usage information.
• Multiple words as positional arguments are joined with a space: deepl-cli -t de Hello world translates "Hello world".
• Verbose mode writes metadata to stderr, so piping stdout is always safe.
• api_key_command is recommended over api_key to avoid storing secrets in plain text.