Repository files navigation

🐍 Official Python command-line client fortldr pages 📚.

Check Repology Packaging Status!

pip install tldr

Install the Python Client in an isolated environment usingpipx:

pipx install tldr

sudo pacman -S tldr

sudo dnf install tldr

sudo snap install tldr

usage: tldrcommand [options]Pythoncommand line clientfor tldrpositional arguments:commandcommand to lookupoptions:  -h, --help            show thishelp message andexit  -v, --version         show program's version number and exit  --search "KEYWORDS"   Search for a specific command from a query  -u, --update, --update_cache                        Update the local cache of pages and exit  -k, --clear-cache     Delete the local cache of pages and exit  -p PLATFORM, --platform PLATFORM                        Override the operating system [android, freebsd, linux, netbsd, openbsd, osx, sunos, windows, common]  -l, --list            List all available commands for operating system  -s SOURCE, --source SOURCE                        Override the default page source  -c, --color           Override color stripping  -r, --render          Render local markdown files  -L LANGUAGE, --language LANGUAGE                        Override the default language  -m, --markdown        Just print the plain page file.  --short-options       Display shortform options over longform  --long-options        Display longform options over shortform  --print-completion {bash,zsh,tcsh}                        print shell completion script

You can configure the behavior and output of thetldr client by setting environment variables. For example, in the.bashrc file:

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=1export TLDR_CACHE_MAX_AGE=720export 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=shortexport TLDR_PLATFORM=linux

Determines the platform that tldr will use based on the customTLDR_PLATFORM environment variable or automatically via system platform detection.

For a complete list of supported platform values for the--platform option flag, refer to thehelp page.

Cache is downloaded fromTLDR_DOWNLOAD_CACHE_LOCATION (defaults to the one described inthe client specification), unzipped and extracted into thelocal cache directory. Pages are loaded directly fromTLDR_PAGES_SOURCE_LOCATION iftldr <command> is used.

• TLDR_CACHE_ENABLED (default is1):
  • If set to1, the client will first try to load from cache, and fall back to fetching from the internet if the cache doesn't exist or is too old.
  • If set to0, the client will fetch from the internet, and fall back to the cache if the page cannot be fetched from the internet.
• TLDR_CACHE_MAX_AGE (default is168 hours, which is equivalent to a week): maximum age of the cache in hours to be considered as valid whenTLDR_CACHE_ENABLED is set to1.

In order of precedence:

• $XDG_CACHE_HOME/tldr
• $HOME/.cache/tldr
• ~/.cache/tldr

If you are experiencing issues withtldr, consider deleting the cache files before trying other measures:

tldr --clear-cache

shtab is required for autocompletion using the--print-completion argument.

# bashtldr --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

See theshtabdocs for other installation methods andsupported shells.

For autocomplete infish, while it is not supported inshtab yet,please see#183 for manually addingan autocomplete fortldr forfish.

For networks that sit behind a proxy, it may be necessary to disable SSL verification for the client to function. Setting the following:

• TLDR_ALLOW_INSECURE=1

will disable SSL certificate inspection. Thisshould be avoided unless absolutely necessary.

Alternatively, It is possible to use a different certificate store/bundle by setting:

• TLDR_CERT=/path/to/certificates.crt

Values of theTLDR_COLOR_x variables may consist of three parts:

• Font color:blue, green, yellow, cyan, magenta, white, grey, red
• Background color:on_blue, on_cyan, on_magenta, on_white, on_grey, on_yellow, on_red, on_green
• Additional effects, which depend on the platform:reverse, blink, dark, concealed, underline, bold

You may specify as many additional effects as you want, while only one of font and background color.

Any of the values above may be omitted. For example, you can do similar things as the following:

• TLDR_COLOR_NAME="" use default system font color with default background color without any effects
• TLDR_COLOR_DESCRIPTION="white" for white text on default system background color without any effects
• TLDR_COLOR_NAME="cyan dark" for dark cyan text on default system background color
• TLDR_COLOR_NAME="on_red" for default system font color on the red background color
• TLDR_COLOR_PARAMETER="red on_yellow underline" for underlined red text on yellow background
• TLDR_COLOR_NAME="bold underline" for default system font and background colors with underline and bolded effects

The language that tldr will use is dependent on several factors. If you specify a language via the--language flag, tldr will attempt to use that language and only that language. Otherwise, it willtry to use the language specified byTLDR_LANGUAGE. If it is not set, or the page does not exist in that language,then tldr will use thelanguage set usingLANGUAGE andLANG (ignoring the valuesC andPOSIX).

If neither is set, then tldr will always attempt to get theen page. Finally, ifLANG is set, it usesLANGUAGE, if set,first, as the priority list to try languages in, followed byLANG if not included inLANGUAGEanden as a fallback (assuming it does not already appear somewhere inLANGUAGE orLANG).

All language values should be set to a value that followsRFC 1766,with the special exceptions ofC andPOSIX which are ignored.

If you wish to use your own instance of the tldr pages instead of the default repository, youcan either use the--source flag when using tldr or by specifying the following environment variables:

• TLDR_PAGES_SOURCE_LOCATION to control where to get individual pages from.
  • defaults tohttps://raw.githubusercontent.com/tldr-pages/tldr/main/pages.
  • it can also point to a local directory usingfile:///path/to/directory.
• TLDR_DOWNLOAD_CACHE_LOCATION to control where to pull a zip of all pages from.
  • defaults tohttps://github.com/tldr-pages/tldr/releases/latest/download/tldr.zip.

Pages might contain{{[*|*]}} patterns to let the client decide whether to show shortform or longform versions of options. This can be configured withTLDR_OPTIONS, which accepts valuesshort,long andboth.