# tldr-python-client
[](https://pypi.python.org/pypi/tldr)
[](https://github.com/tldr-pages/tldr-python-client/actions/workflows/test.yml)
[](https://github.com/tldr-pages/tldr-python-client/actions/workflows/github-code-scanning/codeql)
[](https://snapcraft.io/tldr)
🐍 Official Python command-line client for [tldr pages](https://github.com/tldr-pages/tldr) 📚.
## Installation
<details open>
<summary>Check Repology Packaging Status!</summary>
<a href="https://repology.org/project/tldr-python-client/versions">
<img src="https://repology.org/badge/vertical-allrepos/tldr-python-client.svg" alt="Packaging status">
</a>
</details>
### from PyPI
```bash
pip install tldr
```
Install the Python Client in an isolated environment using [`pipx`](https://pipx.pypa.io/stable/):
```bash
pipx install tldr
```
### from Arch Linux repository
```bash
sudo pacman -S tldr
```
### from Fedora packages repository
```bash
sudo dnf install tldr
```
### from Snap Store
```bash
sudo snap install tldr
```
## Usage
```bash
usage: tldr command [options]
Python command line client for tldr
positional arguments:
command command to lookup
options:
-h, --help show this help message and exit
-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
```
## Configuration
You can configure the behavior and output of the `tldr` client by setting environment variables. For example, in the `.bashrc` file:
```bash
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
```
### Platform
Determines the platform that tldr will use based on the custom `TLDR_PLATFORM` environment variable or automatically via system platform detection.
For a complete list of supported platform values for the `--platform` option flag, refer to the [help page](#usage).
### Cache
Cache is downloaded from `TLDR_DOWNLOAD_CACHE_LOCATION` (defaults to the one described in [the client specification](https://github.com/tldr-pages/tldr/blob/main/CLIENT-SPECIFICATION.md#caching)), unzipped and extracted into the [local cache directory](#cache-location). Pages are loaded directly from `TLDR_PAGES_SOURCE_LOCATION` if `tldr <command>` is used.
- `TLDR_CACHE_ENABLED` (default is `1`):
- If set to `1`, 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 to `0`, 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 is `168` hours, which is equivalent to a week): maximum age of the cache in hours to be considered as valid when `TLDR_CACHE_ENABLED` is set to `1`.
#### Cache location
In order of precedence:
- `$XDG_CACHE_HOME/tldr`
- `$HOME/.cache/tldr`
- `~/.cache/tldr`
If you are experiencing issues with *tldr*, consider deleting the cache files before trying other measures:
```bash
tldr --clear-cache
```
#### Autocomplete
[`shtab`](https://pypi.org/project/shtab) is required for autocompletion using the `--print-completion` argument.
```bash
# 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
```
See the `shtab` [docs](https://pypi.org/project/shtab/#usage) for other installation methods and
supported shells.
For autocomplete in [`fish`](https://fishshell.com/), while it is not supported in `shtab` yet,
please see [#183](https://github.com/tldr-pages/tldr-python-client/issues/183) for manually adding
an autocomplete for `tldr` for `fish`.
### SSL Inspection
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. This __should be avoided__ unless absolutely necessary.
Alternatively, It is possible to use a different certificate store/bundle by setting:
- `TLDR_CERT=/path/to/certificates.crt`
### Colors
Values of the `TLDR_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
### Language
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 will
try to use the language specified by `TLDR_LANGUAGE`. If it is not set, or the page does not exist in that language,
then tldr will use the
language set using `LANGUAGE` and `LANG` (ignoring the values `C` and `POSIX`).
If neither is set, then tldr will always attempt to get the `en` page. Finally, if `LANG` is set, it uses `LANGUAGE`, if set,
first, as the priority list to try languages in, followed by `LANG` if not included in `LANGUAGE`
and `en` as a fallback (assuming it does not already appear somewhere in `LANGUAGE` or `LANG`).
All language values should be set to a value that follows [RFC 1766](https://tools.ietf.org/html/rfc1766.html),
with the special exceptions of `C` and `POSIX` which are ignored.
### Remote source
If you wish to use your own instance of the tldr pages instead of the default repository, you
can 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 to `https://raw.githubusercontent.com/tldr-pages/tldr/main/pages`.
- it can also point to a local directory using `file:///path/to/directory`.
- `TLDR_DOWNLOAD_CACHE_LOCATION` to control where to pull a zip of all pages from.
- defaults to `https://github.com/tldr-pages/tldr/releases/latest/download/tldr.zip`.
### Command options
Pages might contain `{{[*|*]}}` patterns to let the client decide whether to show shortform or longform versions of options. This can be configured with `TLDR_OPTIONS`, which accepts values `short`, `long` and `both`.
Raw data
{
"_id": null,
"home_page": null,
"name": "tldr",
"maintainer": null,
"docs_url": null,
"requires_python": "~=3.9",
"maintainer_email": null,
"keywords": "cheatsheets, documentation, man, manpages, tldr, tldr-pages",
"author": "Felix Yan and tldr-pages contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b7/5d/2c1c95238204dba8a7bae619801e27062ab19d21b8022c5781e414f9d530/tldr-3.4.2.tar.gz",
"platform": null,
"description": "# tldr-python-client\n\n[](https://pypi.python.org/pypi/tldr)\n[](https://github.com/tldr-pages/tldr-python-client/actions/workflows/test.yml)\n[](https://github.com/tldr-pages/tldr-python-client/actions/workflows/github-code-scanning/codeql)\n[](https://snapcraft.io/tldr)\n\n\ud83d\udc0d Official Python command-line client for [tldr pages](https://github.com/tldr-pages/tldr) \ud83d\udcda.\n\n\n\n## Installation\n\n<details open>\n <summary>Check Repology Packaging Status!</summary>\n <a href=\"https://repology.org/project/tldr-python-client/versions\">\n <img src=\"https://repology.org/badge/vertical-allrepos/tldr-python-client.svg\" alt=\"Packaging status\">\n </a>\n</details>\n\n### from PyPI\n\n```bash\npip install tldr\n```\n\nInstall the Python Client in an isolated environment using [`pipx`](https://pipx.pypa.io/stable/):\n\n```bash\npipx install tldr\n```\n\n### from Arch Linux repository\n\n```bash\nsudo pacman -S tldr\n```\n\n### from Fedora packages repository\n\n```bash\nsudo dnf install tldr\n```\n\n### from Snap Store\n\n```bash\nsudo snap install tldr\n```\n\n## Usage\n\n```bash\nusage: tldr command [options]\n\nPython command line client for tldr\n\npositional arguments:\n command command to lookup\n\noptions:\n -h, --help show this help message and exit\n -v, --version show program's version number and exit\n --search \"KEYWORDS\" Search for a specific command from a query\n -u, --update, --update_cache\n Update the local cache of pages and exit\n -k, --clear-cache Delete the local cache of pages and exit\n -p PLATFORM, --platform PLATFORM\n Override the operating system [android, freebsd, linux, netbsd, openbsd, osx, sunos, windows, common]\n -l, --list List all available commands for operating system\n -s SOURCE, --source SOURCE\n Override the default page source\n -c, --color Override color stripping\n -r, --render Render local markdown files\n -L LANGUAGE, --language LANGUAGE\n Override the default language\n -m, --markdown Just print the plain page file.\n --short-options Display shortform options over longform\n --long-options Display longform options over shortform\n --print-completion {bash,zsh,tcsh}\n print shell completion script\n```\n\n## Configuration\n\nYou can configure the behavior and output of the `tldr` client by setting environment variables. For example, in the `.bashrc` file:\n\n```bash\nexport TLDR_COLOR_NAME=\"cyan\"\nexport TLDR_COLOR_DESCRIPTION=\"white\"\nexport TLDR_COLOR_EXAMPLE=\"green\"\nexport TLDR_COLOR_COMMAND=\"red\"\nexport TLDR_COLOR_PARAMETER=\"white\"\nexport TLDR_LANGUAGE=\"es\"\nexport TLDR_CACHE_ENABLED=1\nexport TLDR_CACHE_MAX_AGE=720\nexport TLDR_PAGES_SOURCE_LOCATION=\"https://raw.githubusercontent.com/tldr-pages/tldr/main/pages\"\nexport TLDR_DOWNLOAD_CACHE_LOCATION=\"https://github.com/tldr-pages/tldr/releases/latest/download/tldr.zip\"\nexport TLDR_OPTIONS=short\nexport TLDR_PLATFORM=linux\n```\n\n### Platform\n\nDetermines the platform that tldr will use based on the custom `TLDR_PLATFORM` environment variable or automatically via system platform detection.\n\nFor a complete list of supported platform values for the `--platform` option flag, refer to the [help page](#usage).\n\n### Cache\n\nCache is downloaded from `TLDR_DOWNLOAD_CACHE_LOCATION` (defaults to the one described in [the client specification](https://github.com/tldr-pages/tldr/blob/main/CLIENT-SPECIFICATION.md#caching)), unzipped and extracted into the [local cache directory](#cache-location). Pages are loaded directly from `TLDR_PAGES_SOURCE_LOCATION` if `tldr <command>` is used.\n\n- `TLDR_CACHE_ENABLED` (default is `1`):\n - If set to `1`, 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.\n - If set to `0`, the client will fetch from the internet, and fall back to the cache if the page cannot be fetched from the internet.\n- `TLDR_CACHE_MAX_AGE` (default is `168` hours, which is equivalent to a week): maximum age of the cache in hours to be considered as valid when `TLDR_CACHE_ENABLED` is set to `1`.\n\n#### Cache location\n\nIn order of precedence:\n\n- `$XDG_CACHE_HOME/tldr`\n- `$HOME/.cache/tldr`\n- `~/.cache/tldr`\n\nIf you are experiencing issues with *tldr*, consider deleting the cache files before trying other measures:\n\n```bash\ntldr --clear-cache\n```\n\n#### Autocomplete\n\n[`shtab`](https://pypi.org/project/shtab) is required for autocompletion using the `--print-completion` argument.\n\n```bash\n# bash\ntldr --print-completion bash | sudo tee \"$BASH_COMPLETION_COMPAT_DIR\"/tldr\n\n# zsh (it is recommended to check where zsh/site-functions directory is located)\n## for macOS:\ntldr --print-completion zsh | sudo tee /usr/local/share/zsh/site-functions/_tldr\n## for Linux:\ntldr --print-completion zsh | sudo tee /usr/share/zsh/site-functions/_tldr\n```\n\nSee the `shtab` [docs](https://pypi.org/project/shtab/#usage) for other installation methods and\nsupported shells.\n\nFor autocomplete in [`fish`](https://fishshell.com/), while it is not supported in `shtab` yet,\nplease see [#183](https://github.com/tldr-pages/tldr-python-client/issues/183) for manually adding\nan autocomplete for `tldr` for `fish`.\n\n### SSL Inspection\n\nFor networks that sit behind a proxy, it may be necessary to disable SSL verification for the client to function. Setting the following:\n\n- `TLDR_ALLOW_INSECURE=1`\n\nwill disable SSL certificate inspection. This __should be avoided__ unless absolutely necessary.\n\nAlternatively, It is possible to use a different certificate store/bundle by setting:\n\n- `TLDR_CERT=/path/to/certificates.crt`\n\n### Colors\n\nValues of the `TLDR_COLOR_x` variables may consist of three parts:\n\n- Font color: `blue, green, yellow, cyan, magenta, white, grey, red`\n- Background color: `on_blue, on_cyan, on_magenta, on_white, on_grey, on_yellow, on_red, on_green`\n- Additional effects, which depend on the platform: `reverse, blink, dark, concealed, underline, bold`\n\nYou may specify as many additional effects as you want, while only one of font and background color.\n\nAny of the values above may be omitted. For example, you can do similar things as the following:\n\n- `TLDR_COLOR_NAME=\"\"` use default system font color with default background color without any effects\n- `TLDR_COLOR_DESCRIPTION=\"white\"` for white text on default system background color without any effects\n- `TLDR_COLOR_NAME=\"cyan dark\"` for dark cyan text on default system background color\n- `TLDR_COLOR_NAME=\"on_red\"` for default system font color on the red background color\n- `TLDR_COLOR_PARAMETER=\"red on_yellow underline\"` for underlined red text on yellow background\n- `TLDR_COLOR_NAME=\"bold underline\"` for default system font and background colors with underline and bolded effects\n\n### Language\n\nThe language that tldr will use is dependent on several factors. If you specify a language via the\n`--language` flag, tldr will attempt to use that language and only that language. Otherwise, it will\ntry to use the language specified by `TLDR_LANGUAGE`. If it is not set, or the page does not exist in that language,\nthen tldr will use the\nlanguage set using `LANGUAGE` and `LANG` (ignoring the values `C` and `POSIX`).\n\nIf neither is set, then tldr will always attempt to get the `en` page. Finally, if `LANG` is set, it uses `LANGUAGE`, if set,\nfirst, as the priority list to try languages in, followed by `LANG` if not included in `LANGUAGE`\nand `en` as a fallback (assuming it does not already appear somewhere in `LANGUAGE` or `LANG`).\n\nAll language values should be set to a value that follows [RFC 1766](https://tools.ietf.org/html/rfc1766.html),\nwith the special exceptions of `C` and `POSIX` which are ignored.\n\n### Remote source\n\nIf you wish to use your own instance of the tldr pages instead of the default repository, you\ncan either use the `--source` flag when using tldr or by specifying the following environment variables:\n\n- `TLDR_PAGES_SOURCE_LOCATION` to control where to get individual pages from.\n - defaults to `https://raw.githubusercontent.com/tldr-pages/tldr/main/pages`.\n - it can also point to a local directory using `file:///path/to/directory`.\n- `TLDR_DOWNLOAD_CACHE_LOCATION` to control where to pull a zip of all pages from.\n - defaults to `https://github.com/tldr-pages/tldr/releases/latest/download/tldr.zip`.\n\n### Command options\n\nPages might contain `{{[*|*]}}` patterns to let the client decide whether to show shortform or longform versions of options. This can be configured with `TLDR_OPTIONS`, which accepts values `short`, `long` and `both`.\n",
"bugtrack_url": null,
"license": null,
"summary": "Official Python command line client for tldr pages.",
"version": "3.4.2",
"project_urls": {
"Changelog": "https://github.com/tldr-pages/tldr-python-client/blob/main/CHANGELOG.md",
"Funding": "https://liberapay.com/tldr-pages",
"Homepage": "https://tldr.sh",
"Issues": "https://github.com/tldr-pages/tldr-python-client/issues",
"Source": "https://github.com/tldr-pages/tldr-python-client"
},
"split_keywords": [
"cheatsheets",
" documentation",
" man",
" manpages",
" tldr",
" tldr-pages"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ebc1125b6c5adf5feb8a7dfda7bd5ffc60f1d16fd4b9b9bed99d9846ee3e8c75",
"md5": "769e30fca947dce9626e08d13c39429e",
"sha256": "7fadd2e48e2bebc5406a9301808cef568d0521e95f2e9855461f61bf061699d2"
},
"downloads": -1,
"filename": "tldr-3.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "769e30fca947dce9626e08d13c39429e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.9",
"size": 13772,
"upload_time": "2025-09-12T14:54:41",
"upload_time_iso_8601": "2025-09-12T14:54:41.410330Z",
"url": "https://files.pythonhosted.org/packages/eb/c1/125b6c5adf5feb8a7dfda7bd5ffc60f1d16fd4b9b9bed99d9846ee3e8c75/tldr-3.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b75d2c1c95238204dba8a7bae619801e27062ab19d21b8022c5781e414f9d530",
"md5": "357d0ae35eb732e2b1be02369850b2d2",
"sha256": "7bb210b47b3697c6050b7e17fbc283c2a2aeba6d794b63e607376396f9c510a9"
},
"downloads": -1,
"filename": "tldr-3.4.2.tar.gz",
"has_sig": false,
"md5_digest": "357d0ae35eb732e2b1be02369850b2d2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.9",
"size": 17347,
"upload_time": "2025-09-12T14:54:42",
"upload_time_iso_8601": "2025-09-12T14:54:42.856328Z",
"url": "https://files.pythonhosted.org/packages/b7/5d/2c1c95238204dba8a7bae619801e27062ab19d21b8022c5781e414f9d530/tldr-3.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-12 14:54:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tldr-pages",
"github_project": "tldr-python-client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "termcolor",
"specs": []
},
{
"name": "colorama",
"specs": [
[
"==",
"0.4.6"
]
]
},
{
"name": "shtab",
"specs": [
[
">=",
"1.3.10"
]
]
}
],
"lcname": "tldr"
}
JSON
