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
Installation
Download
- Download the binary from the Releases
Homebrew
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.
docx- Microsoft Word Documentpptx- Microsoft PowerPoint Documentxlsx- Microsoft Excel Documentpdf- Portable Document Formathtm/html- HTML Documenttxt- Plain Text Documentxlf/xliff- XLIFF Document, version 2.1
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
- Fork this repository
- Report bugs
- Fix bugs and submit pull requests
- Write, clarify, or fix documentation
- Suggest or add new features
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.
- 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.
License
This project is licensed under the MIT License.
Happy translating!