tldr: the Python client for tldr pages

What the client does with the tldr pages

tldr is the official Python command line client for tldr pages, the community-maintained collection of short, example-driven cheatsheets. The client's job is to find the right page for the command you typed, fetch it, and render it in your terminal.

The usage output in the README is the whole feature surface, and reading it tells you what the client does and does not try to do. There is a positional command to look up, a --search option to search for a specific command from a query, and --update to update the local cache of pages. --clear-cache deletes it. There is a --platform option to override the operating system across a list of android, freebsd, linux, netbsd, openbsd, osx, sunos, windows and common. There is --list to list all available commands for the operating system, and --source to override the default page source.

Then the display options. --color overrides colour stripping, --render renders local markdown files, --language overrides the default language, --markdown just prints the plain page file, and --short-options and --long-options choose which form of the option list is shown. The --print-completion option outputs a shell completion script for bash, zsh or tcsh.

The --platform option is the feature that makes this more than a page fetcher. The tldr pages carry platform-specific notes, so a page for a command behaves differently on macOS than on Linux, and the client picks the right variant by detecting the system platform or by taking the override. The --list option then shows the commands that have pages for the platform in effect, which is a different and usually shorter list than the total number of pages.

Installing from PyPI or a distribution package

The simplest install is from PyPI.

pip install tldr

The README also suggests pipx for an isolated environment, which is the better choice for a command line tool that you want on your path without its dependencies in the same environment as your projects.

pipx install tldr

Distribution packages exist too. On Arch Linux it is in the official repository.

sudo pacman -S tldr

On Fedora it is in the packages repository.

sudo dnf install tldr

And there is a Snap Store package.

sudo snap install tldr

The README links a Repology badge for the packaging status, which is the usual way to see the full list of distributions carrying the client. A snapcraft badge for the Snap release is also present.

The package metadata sets the floor at Python 3.10 or above, and the classifiers cover 3.10 through 3.14, with operating system classifiers for Android, macOS, Windows, Linux, the BSDs and SunOS.

The dependency set is deliberately tiny: termcolor for the coloured output, colorama at a pinned 0.4.6 but only on Windows, and shtab at 1.3.10 or above for the completion scripts. The whole implementation lives in a single file, tldr.py, with the rest of the repository holding tests, documentation, images and the snap packaging.

Configuring colours, language, platform and options

The client is configured through environment variables rather than a config file, and the README gives a full set you can put in your shell profile.

export TLDR_COLOR_NAME="cyan"
export TLDR_COLOR_DESCRIPTION="white"
export TLDR_COLOR_EXAMPLE="green"
export TLDR_COLOR_COMMAND="red"
export TLDR_COLOR_PARAMETER="white"
export TLDR_LANGUAGE="es"
export TLDR_CACHE_ENABLED=1
export TLDR_CACHE_MAX_AGE=720
export TLDR_PAGES_SOURCE_LOCATION="https://raw.githubusercontent.com/tldr-pages/tldr/main/pages"
export TLDR_DOWNLOAD_CACHE_LOCATION="https://github.com/tldr-pages/tldr/releases/latest/download/tldr.zip"
export TLDR_OPTIONS=short
export TLDR_PLATFORM=linux

The five colour variables cover the parts of a page, the name, the description, the example, the command itself and the parameters, and each takes a font colour, a background colour and effects. The available font colours are blue, green, yellow, cyan, magenta, white, grey and red, the background colours are the on_ variants of eight of those, and the effects are reverse, blink, dark, concealed, underline and bold. You may specify as many effects as you want and only one of font and background colour, and any of the values may be omitted, so an empty value means the system default with no effects.

The remaining variables cover behaviour. TLDR_LANGUAGE sets the language, TLDR_PLATFORM overrides the detected platform, TLDR_OPTIONS=short selects the short form of the option list, and the two location variables point at the pages and at the downloadable cache archive.

How the cache behaves and where it lives

The caching model is the part of the client worth understanding, because it decides whether a lookup needs the network.

The cache is downloaded from TLDR_DOWNLOAD_CACHE_LOCATION, which defaults to the location described in the client specification, then unzipped and extracted into the local cache directory. When you run tldr with a command, pages are loaded directly from TLDR_PAGES_SOURCE_LOCATION. A system cache in $XDG_DATA_DIRS/tldr is also supported, and it gets queried on a user cache miss.

Two switches control the behaviour. TLDR_CACHE_ENABLED defaults to 1, and with it set to 1 the client first tries to load from cache and falls back to fetching from the internet if the cache does not exist or is too old. Set to 0, the client fetches from the internet first and falls back to the cache if the page cannot be fetched.

TLDR_CACHE_MAX_AGE defaults to 168 hours, which the README notes is equivalent to a week, and it is the maximum age of the cache in hours to be considered valid when the cache is enabled.

The cache location follows a precedence order, and the first existing one wins.

tldr --clear-cache

That command is the answer to the README's advice that if you are experiencing issues with tldr, you should consider deleting the cache files before trying other measures. The precedence is $XDG_CACHE_HOME/tldr, then $HOME/.cache/tldr, then the tldr subdirectory of the user cache.

The default of one week means a page for a command whose flags changed last month can be stale, and a network client whose whole value is a fast lookup should be re-run with --update after a change you know about.

Shell completion and the SSL inspection escape hatch

Completion is generated by the client and written into your shell's completion directory, and shtab is required for it.

# bash
tldr --print-completion bash | sudo tee "$BASH_COMPLETION_COMPAT_DIR"/tldr

# zsh (it is recommended to check where zsh/site-functions directory is located)
## for macOS:
tldr --print-completion zsh | sudo tee /usr/local/share/zsh/site-functions/_tldr
## for Linux:
tldr --print-completion zsh | sudo tee /usr/share/zsh/site-functions/_tldr

The zsh case is the fiddly one, because the completion file has to go into the site-functions directory under the name _tldr, and where that directory lives depends on the distribution, which is why the README recommends checking its location first.

Fish is not supported by shtab yet, and the README points at issue 183 for manually adding an autocomplete for fish.

Then there is the setting the README is careful about. For networks behind a proxy it may be necessary to disable SSL verification for the client to function, and setting TLDR_ALLOW_INSECURE=1 does that, with the warning that this should be avoided unless absolutely necessary. The alternative is a different certificate store, set through TLDR_CERT pointing at a path to a certificates.crt file.

That pairing is the right way round. The insecure switch is a single character in your profile and applies to every request the client makes, while the certificate bundle is explicit and auditable.

Where the tldr client is the wrong choice

The first limitation is scope. A tldr page is a short sheet of examples, not documentation. If you want the full manual for a command, the client will not give it to you, and a man page or the tool's own help output is the answer. The client also does not explain itself, so for a command with a large surface, a tldr page tells you that the flag exists without telling you what it does.

The second is that the pages are community written and the client will happily show you a page for a command that does not exist on your system, or one that describes a version you do not have. The --list option shows what pages exist for the platform, which reduces the problem but does not solve it, since the page content is not validated against the installed tool version.

The third is the cache and its staleness. A week is a long time for a page describing a command line, and a client that answers from a stale cache does not say so. There is no version check against the installed tool, and the --update flag is a manual action.

The fourth is the SSL escape hatch being one environment variable away. A user who sets TLDR_ALLOW_INSECURE=1 to get past a corporate proxy has permanently disabled certificate checking for a client that fetches pages over the network, and the README's own warning is that it should be avoided unless absolutely necessary. In a shared shell profile that is a decision with a long tail.

The fifth is the Python floor. Python 3.10 or above is required, which is not a constraint today but does mean the client will not run on the older Python that ships with, for example, a CentOS 7 host or a Raspberry Pi OS image pinned to an old release. The Snap and distribution packages sidestep this by bundling their own interpreter.

The sixth is the fish gap. Autocompletion is not supported by shtab for fish, and the workaround is a manual issue-thread recipe, so a fish user is on their own.

Licence, maintenance and the cost of a cheatsheet client

The project is under the MIT licence, with the LICENSE.md file at the root, and the package metadata declares it. The authors are listed as Felix Yan and the tldr-pages contributors.

The repository is not archived and the last push was on 2026-10-14, so the client is being maintained. The release history shows 3.4.4 in February 2026, 3.4.3 in September 2025 and 3.4.2 a fortnight earlier, so the patch cadence is regular and the minor releases are infrequent, which is what you would expect for a client whose interface is stable.

The project classifies itself as Production/Stable, and the CI setup includes a test workflow badge and a CodeQL code scanning badge, so the client is tested and scanned in CI.

The build system is Hatchling, with the version taken dynamically rather than hardcoded in the pyproject, and there is a separate requirements.txt holding the three runtime dependencies for developers. The optional cli extra collects pytest, pytest-runner, flake8 and the Sphinx packages, and the docs/ directory is a Sphinx site with sphinx-argparse, which is how the usage output in the README is generated from the argument parser rather than copied by hand. There is also a .flake8 configuration and a CHANGELOG.md.

The running cost of the client is close to zero. It is a short-lived process that either reads a cached file or makes one or two HTTP requests, and the cache means the second invocation of the same command is a local file read. The only recurring cost is the periodic cache refresh, and the way to control that is TLDR_CACHE_MAX_AGE, which is the setting to reach for on a slow or metered connection.

Editorial conclusion

tldr suits anyone who wants example-driven command help in a terminal, since the client is a single pip package with no daemon and a cache that makes repeated lookups instant. It does not suit a reader who wants the full manual, because a tldr page is a short example sheet by design. Verify the Python version first, at 3.10 or above, and set TLDR_CACHE_MAX_AGE if you use it on a slow or metered connection, since the default cache age is a week.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. tldr-pages/tldr-python-client on GitHub