DeepL CLI

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

• Supports document translation pdf, docx, txt, etc.
• Supports glossaries
• Precompiled binaries available

• Download the binary from the Releases

brew install kojix2/brew/deepl-cli

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

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

The default command translates text:

deepl [options] <file>

For text-specific options, use the text subcommand:

deepl text [options] <text>

Options:

    -i, --input TEXT                 Input text
    -f, --from [LANG]                Source language [AUTO]
    -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
    -A, --ansi                       Do not remove ANSI escape codes

Note: ANSI escape sequences are removed by default.

To translate a document, use the doc subcommand:

deepl doc [options] <file>

Options for document translation:

    -f, --from [LANG]                Source language [AUTO]
    -t, --to [LANG]                  Target language [EN]
    -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

Supported file formats.

• docx - Microsoft Word Document
• pptx - Microsoft PowerPoint Document
• xlsx - Microsoft Excel Document
• pdf - Portable Document Format
• htm / html - HTML Document
• txt - Plain Text Document
• xlf / xliff - XLIFF Document, version 2.1

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

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

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

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

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 require an explicit source language and 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

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

fortune | tee /dev/stderr | deepl

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

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

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

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

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.

To display a list of available source languages:

deepl -f

To display a list of available target languages:

deepl -t

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.

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

• Fork this repository
• Report bugs
• Fix bugs and submit pull requests
• Write, clarify, or fix documentation
• Suggest or add new features

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

• https://github.com/kojix2/deepl.cr/

Built for a different audience.

• The official DeepL CLI is mainly intended for developers working with the DeepL API.
• This project is for people who want a lightweight translation tool they can use directly from the terminal.

This project is licensed under the MIT License.

Happy translating!