DeepL CLI

build Lines of Code

DeepL CLI is a fast and lightweight command-line tool for using DeepL API translation from the terminal.

Installation

Download

Homebrew

deepl-cli (macos)

brew install kojix2/brew/deepl-cli

Proxy settings (optional)

export HTTP_PROXY=http://[IP]:[port]
export HTTPS_PROXY=http://[IP]:[port]

The connection to the proxy itself is not encrypted, so https:// proxy URLs with credentials are rejected.

Prerequisites

You will need an API key for DeepL. Create one here and set it as an environment variable:

export DEEPL_AUTH_KEY=your_api_key_here

Usage

The default command translates text:

deepl [options] <file>

Translate text

For text-specific options, use the text subcommand:

deepl text [options] [file ...]

Pass file paths as positional arguments, use --input for literal text, or read from standard input when no files are given.

Options:

    -i, --input TEXT                 Input text
    -f, --from [LANG]                Source language [AUTO]; omit LANG to list
    -t, --to [LANG]                  Target language [EN]
    -p, --paste                      Input text from clipboard
    -g, --glossary NAME              Glossary name
        --glossary-id IDS            Glossary IDs (max 5)
    -F, --formality OPT              Formality (default more less)
    -C, --context TEXT               Context (experimental)
    -s, --split-sentences OPT        Split sentences
    -T, --tag-handling OPT           Tag handling
    -O, --outline-detection          Enable automatic XML structure detection
        --no-outline-detection       Disable automatic XML structure detection
    -S, --splitting-tags TAGS        Splitting tags
    -A, --ansi                       Do not remove ANSI escape codes

Note: ANSI escape sequences are removed by default.

With --tag-handling xml, DeepL detects XML structure automatically by default. --splitting-tags disables automatic detection for manual splitting unless --outline-detection is also specified. Use --no-outline-detection to disable automatic detection without specifying splitting tags.

Translate documents

To translate a document, use the doc subcommand:

deepl doc [options] <file>

Options for document translation:

    -f, --from [LANG]                Source language [AUTO]; omit LANG to list
    -t, --to [LANG]                  Target language [EN]; omit LANG to list
    -g, --glossary NAME              Glossary name
        --glossary-id IDS            Glossary IDs (max 5)
    -F, --formality OPT              Formality (default more less)
    -o, --output FILE                Output file
    -O, --output-format FORMAT       Output file format
        --watermark                  Enable document watermark
    -U, --upload-only                Upload file only
        --handle FILE                Document handle file

The output file must be different from the document handle file.

Supported file formats.

Manage glossaries

For glossary management, use the glossary subcommand:

deepl glossary [options] <subcommand>

Options for glossary management:

    list                             List glossaries
    create                           Create a glossary
    delete                           Delete glossaries
    edit                             Edit glossaries
    view                             View glossaries
    -l, --list                       List glossaries

Improve text (Rephrase)

Use the rephrase subcommand to rewrite text in different styles or tones.

Usage: deepl rephrase [options] <file>

Options for rephrase:

    -i, --input TEXT                 Input text
    -s, --writing-style STYLE        academic business casual default simple
    -t, --tone TONE                  confident diplomatic enthusiastic friendly

Correct text

Use correct to correct text while preserving its meaning. It accepts input from standard input or --input and writes the corrected text to standard output by default.

deepl correct --from EN --input "This sentence have an error."

Examples

Below are examples for translating text, translating documents, and working with glossaries.

Translate text

To translate the text "Hola mundo" from Spanish (ES) to English (EN):

deepl -i "Hola mundo" -t en        # Translation: Hello world

Or, using standard input:

echo "Hola mundo" | deepl -t en    # Translation: Hello world

Standard input translation is useful for quick references.

git --help | deepl -t fr | less

The man command can also be translated (by removing ANSI escape sequences):

man git | deepl -t de | less

To translate multiple lines, press Ctrl+D when you have finished typing. This is particularly useful when copying and pasting from the clipboard.

deepl -f es
# Hola
# mundo
# Ctrl + D

Translate text from the clipboard:

deepl --paste

You can also pass a text file as an argument:

deepl -t tr foo.txt

It's possible to pass multiple text files:

deepl -t nl foo.txt bar.txt

If you are translating multiple files, you might want to add the filename to the header:

bat --style header *.txt | deepl -t it

To use a glossary for translation:

deepl -g myglossary -f ru

When a glossary name is not unique, use its explicit ID instead:

deepl --glossary-id 01234567-89ab-cdef-0123-456789abcdef -f ru

Glossary IDs cannot be combined with --glossary. Up to five IDs can be supplied together, either comma-separated or by repeating --glossary-id:

deepl --from EN --to DE --glossary-id id-1,id-2 --input "Hello"
# Equivalent: --glossary-id id-1 --glossary-id id-2

DeepL requires a source language when a glossary is used. If --from is omitted, the CLI uses the glossary's source language for the target language. When that is ambiguous, specify --from.

To refer to the original text, you can use tee dev/stderr:

fortune | tee /dev/stderr | deepl

Translate Documents

You can directly translate documents:

deepl doc your.pdf -t pt
# The translated document will be saved as your_PT.pdf

To use a glossary for translation:

deepl doc -g myglossary -f pl

To translate a PDF document and save it in docx format:

deepl doc input.pdf -O docx -o output.docx

Glossary IDs can also be used for document translation. A watermark can be added to supported output formats:

deepl doc --from EN --to DE \
  --glossary-id id-1,id-2 \
  --watermark \
  input.pdf

Document translation temporarily writes a handle file such as input.pdf.deepl-handle.json and removes it after a successful download, unless --handle FILE is specified. The handle file contains the DeepL document key. Treat it as a secret. It is written with owner-only permissions on POSIX systems (mode 0600). Existing handle files are never overwritten; choose another path with --handle FILE. If a handle cannot be installed after upload, the CLI preserves it in a recovery file and prints its path.

When the automatic translated-document filename already exists, the CLI chooses a timestamped unique name instead of replacing the existing file. If receiving or saving the result fails after a successful download response, the CLI keeps a recovery file and prints its path. It may contain incomplete data. Recover that file rather than relying on another download: DeepL can delete the translated document after it has been downloaded.

To upload a document and check or download it later:

deepl doc -U input.pdf
deepl doc status --handle input.pdf.deepl-handle.json
deepl doc download --handle input.pdf.deepl-handle.json -o output.pdf

To translate multiple files, use Unix commands such as find, xargs, fd:

find . -name "*.pdf" -exec deepl doc -t ja {} \;
ls -1 *.docx | xargs -L1 deepl doc -t ko
fd -e pdf -e docx -x deepl doc -t zh

Glossaries

The DeepL API supports glossaries. The CLI uses the multilingual glossary endpoint (/v3/glossaries). See the API documentation for the glossary file format.

To create a glossary:

deepl glossary create -n mydic -f en -t pt mydict.tsv

To list glossaries:

deepl glossary list

To list only the names of the glossary:

deepl glossary -l

To use a glossary for text translation:

deepl -g mydict -f en deep.txt

To use a glossary for document translation:

deepl doc -g mydict -f en deep.pdf
deepl doc --glossary-id 01234567-89ab-cdef-0123-456789abcdef -f en deep.pdf

To display the contents of the glossary:

deepl glossary view mydict

--from and --to independently filter the glossary's dictionaries. The default translation target is not used to select a dictionary. A single matching pair is selected automatically; multiple matches require an interactive selection.

With --output FILE, an existing file is replaced only after all requested glossary entries have been retrieved successfully.

To edit a glossary:

deepl glossary edit mydict

The glossary is updated only when the editor exits successfully.

Glossary names must identify exactly one glossary. For delete, edit, or view operations on a duplicate name, use the existing ID mode instead:

deepl glossary delete --id 01234567-89ab-cdef-0123-456789abcdef

When run in a terminal, glossary delete asks for confirmation before deleting each glossary. Use --yes to skip the prompt. In scripts, or whenever standard input or standard error is redirected, --yes is required; otherwise the command exits with an error without deleting anything.

Rephrase

Change writing style:

bin/deepl rephrase -i "Thanks" -s academic
# Expressions of gratitude are extended.

Change tone:

bin/deepl rephrase -i "Thanks" -t friendly
# Thank you so much! I really appreciate it.

Information

To display a list of available source languages for text translation:

deepl -f

To display a list of available source languages for document translation:

deepl doc -f

To display a list of available target languages for text translation:

deepl -t

To display a list of available target languages for document translation:

deepl doc -t

To display the target languages supported by DeepL Write:

deepl rephrase -f
deepl correct -f

For these commands, --from selects the Write API's output language.

To output usage information:

deepl -u

# https://api.deepl.com
# character_count: 614842
# character_limit: 1000000000000

When an account reports them, document and speech usage categories are printed as well.

Environment Variables

Name Description
DEEPL_AUTH_KEY DeepL API authentication key
DEEPL_TARGET_LANG Default target language
DEEPL_USER_AGENT User-Agent
EDITOR Text editor for editing glossary

DeepL CLI automatically detects the target language, but if this does not work, the environment variable DEEPL_TARGET_LANG can be set.

If DEEPL_TARGET_LANG is unset or empty, the target language is taken from LC_ALL, LC_MESSAGES, or LANG (or the current Windows culture). Regions select DeepL language variants where available: for example, en_GB becomes EN-GB, pt_BR becomes PT-BR, and zh_TW or zh_HK becomes ZH-HANT. Other locales use the language code only, and EN is used when nothing is detected.

Contributing

Development

Compilation from source code

git clone https://github.com/kojix2/deepl-cli
cd deepl-cli
shards build --release -Dclipboard

A compiled binary file will be created in the bin directory. Installation is simply copying the generated binary.

Clipboard support is enabled only when the Crystal compile-time flag clipboard is set. Without this flag, the --paste option is not available and EasyClip is not required at compile time:

shards build --release
bin/deepl --version # deepl-cli <version> (clipboard disabled)

To build with clipboard support explicitly:

crystal build src/cli.cr -o bin/deepl --release -D clipboard
# or with shards:
shards build --release -Dclipboard
sudo cp bin/deepl /usr/local/bin

If you encounter a bug, follow the command with the -d option and run it. You can view the backtrace.

deepl doc -d a.pdf

DeepL API Library

Difference from the official DeepL CLI

Built for a different audience.

License

This project is licensed under the MIT License.

Happy translating!