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

| Option | Short | Description | |--------|-------|-------------| | --target <lang> | -t | Target language code (required, e.g. de, en-US, fr) | | --source <lang> | -s | Source language code (default: auto-detect) | | --context <text> | -c | Additional context for translation (not translated, not billed) | | --formality <level> | -f | Formality: less, more, default, prefer_less, prefer_more | | --verbose | -v | Show metadata (detected source language, billed characters) | | --help | -h | Show help | | --version | | Show version |

Common Language Codes

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

Source languages (or omit for auto-detection):

| Code | Language | |------|----------| | en | English | | de | German | | fr | French | | es | Spanish | | it | Italian | | ja | Japanese | | zh | Chinese | | pl | Polish | | nl | Dutch | | pt | Portuguese | | ru | Russian |

Target languages (some include regional variants):

| Code | Language | |------|----------| | en-US | English (American) | | en-GB | English (British) | | de | German | | fr | French | | es | Spanish | | it | Italian | | ja | Japanese | | zh-Hans | Chinese (Simplified) | | zh-Hant | Chinese (Traditional) | | pl | Polish | | nl | Dutch | | pt-BR | Portuguese (Brazilian) | | pt-PT | Portuguese (European) | | ru | Russian |

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.