📖 tldr

tldr: a few short, practical examples for a command, instead of the whole manual page.
tldr tar                 show examples for tar
tldr git commit          subcommands work too, typed as you would say them
tldr -l | grep docker    list the pages in the cache and search them
tldr --update            download the newest pages (then it works offline)

tldr (short for "too long; didn't read") is a collection of community-written help pages: for each command, a one-line description and the handful of examples people use most, with the part you change marked in the text. The pages live in one shared project, tldr-pages. A small program (a "client") shows them in your terminal. It is a reminder for the command you half remember, not a replacement for man: the manual says everything, tldr says what you probably wanted.

This page is the written version of the Timesavers video. Every command below was run for real, in an Ubuntu 24.04 container, with the client called tealdeer 1.9.0 (the release binary, checked against its checksum) and the shared pages downloaded on the day of the lab (7,383 entries in the list). The pages are written by volunteers and change over time, so what you see on your machine can differ from the screens here. The video used the setting compact = true so a page fits on the screen; the section about settings shows the default, with blank lines. The section "What was not run" lists what was not tried.

Use tldr when you know a command exists and half remember how to use it:

unpack or pack something           tldr tar: the letters for create, extract, list, with a gzipped archive
which flag was that?               tldr find, tldr rsync, tldr curl, tldr ss
a git or docker subcommand         tldr git commit, tldr docker run
a command you never used           tldr ln, then the example for the thing you wanted
your own team's commands           add your own pages (see the section on custom pages)

It does not replace man. A page has a few examples, not every option, and the pages are written by volunteers: a new option of a new version may be missing, and an example can be slightly out of date. For the full truth, use man or the command's own --help. Its strength is speed: one short screen, with the thing you change spelled out.

tldr is a set of pages and there are several clients that show them. Ubuntu 24.04 has these packages (the lab ran apt-cache policy):

$ apt-cache policy tealdeer | head -3; apt-cache policy tldr | head -3; apt-cache policy tldr-py | head -3
tealdeer:
  Installed: 1.6.1-4build2
  Candidate: 1.6.1-4build2
tldr:
  Installed: (none)
  Candidate: 0.9.2-5
tldr-py:
  Installed: (none)
  Candidate: 0.7.0-6

tealdeer is written in Rust and starts fast. The package called tldr is a stand-in that pulls in a client written in Haskell (tldr-hs); tldr-py is a client written in Python. Only tealdeer was run for this page. It provides the command tldr.

The package in Ubuntu 24.04 is tealdeer 1.6.1, and it cannot update its page cache. The address it downloads from now returns a web page instead of the pages:

$ tldr --update
Successfully created cache directory path `/tmp/h1/.cache/tealdeer`.
Could not update cache

Caused by:
    0: Could not decompress downloaded ZIP archive
    1: invalid Zip archive: Could not find central directory end
exit status: 1
200 text/html; charset=utf-8
<!DOCTYPE html>

So tldr from that package has no pages (every command says "Page cache not found"). The project's release, 1.9.0, works. The lab downloaded the Linux (x86_64) binary and checked it against the checksum file published next to it:

$ B=https://github.com/tealdeer-rs/tealdeer/releases/download/v1.9.0
$ curl -fsSLO $B/tealdeer-linux-x86_64-musl
$ curl -fsSLO $B/tealdeer-linux-x86_64-musl.sha256
$ cat tealdeer-linux-x86_64-musl.sha256 && sha256sum -c tealdeer-linux-x86_64-musl.sha256
dc7263b550e90c0689ea2cb434e3144469805d5dddecbb1f7fc534e1185b7408  tealdeer-linux-x86_64-musl
tealdeer-linux-x86_64-musl: OK
$ install -m755 tealdeer-linux-x86_64-musl ~/.local/bin/tldr
$ tldr --version
tealdeer 1.9.0

(The checksum file comes from the same release page as the binary, so it catches a damaged download, not a tampered release.) Then download the pages once:

$ tldr --update
Successfully updated cache.
Pages for the following languages were downloaded: en

The pages are kept in ~/.cache/tealdeer, and the lab's copy was about 30 MB. After that, tldr works without a network.

Give it the command name. In the lab the setting compact = true was on, as in the video; it removes the blank lines between examples:

$ tldr tar
  Archiving utility.
  Often combined with a compression method, such as `gzip` or `bzip2`.
  More information: <https://www.gnu.org/software/tar/manual/tar.html>.
  [c]reate an archive and write it to a [f]ile:
      tar cf path/to/target.tar path/to/file1 path/to/file2 ...
  [c]reate a g[z]ipped archive and write it to a [f]ile:
      tar czf path/to/target.tar.gz path/to/file1 path/to/file2 ...
  [c]reate a g[z]ipped (compressed) archive from a directory using relative paths:
      tar czf path/to/target.tar.gz --directory path/to/directory .
  E[x]tract a (compressed) archive [f]ile into the current directory [v]erbosely:
      tar xvf path/to/source.tar.ext
  E[x]tract a (compressed) archive [f]ile into the target directory:
      tar xf path/to/source.tar.ext --directory path/to/directory
  [c]reate a compressed archive and write it to a [f]ile, using the file extension to [a]utomatically determine the compression program:
      tar caf path/to/target.tar.xz path/to/file1 path/to/file2 ...
  Lis[t] the contents of a tar [f]ile [v]erbosely:
      tar tvf path/to/source.tar
  E[x]tract files matching a pattern from an archive [f]ile:
      tar xf path/to/source.tar --wildcards "*.html"
  Make a tar of a folder, skipping .git:
      tar czf path/to/target.tar.gz --exclude=.git path/to/folder

The first lines say what the command is. Then each example has a sentence and the command. The letters in square brackets in the sentence ([c]reate, E[x]tract, [f]ile) point to the option letters. The words that are yours to change are shown as plain text in the command (path/to/target.tar and path/to/file1) and, on a colour terminal, are underlined in the default colours. The text cannot show that, so see the video. The last example is the one added in a later section.

The exit status is 0 when a page is found. For a page that does not exist:

$ tldr nonexistentthing
Page `nonexistentthing` not found in cache.
Try updating with `tldr --update`, or submit a pull request to:
https://github.com/tldr-pages/tldr
exit status: 1

(That is a message and an exit status of 1.)

Programs such as git and docker have a page for each subcommand. Type the name the way you would say it:

$ tldr git commit
  Commit files to the repository.
  More information: <https://git-scm.com/docs/git-commit>.
  Open an editor to write a message and commit staged files to the repository:
      git commit
  Commit staged files to the repository with the specified message:
      git commit --message "message"
  Commit staged files with a message read from a file:
      git commit --file path/to/commit_message_file
  Auto stage all modified and deleted files and commit:
      git commit --all --message "message"
  Commit staged files and sign them with the specified GPG key (or the one defined in the configuration file if no `key_id` is specified):
      git commit --gpg-sign key_id --message "message"
...

The same page can be asked for as git-commit, and the lab checked that the two print identical text:

git commit and git-commit print the same page

tldr git, without a subcommand, shows the general git page, which lists a few common commands and says that subcommands have their own pages:

$ tldr git | head -5
  Distributed version control system.
  Some subcommands such as `commit`, `add`, `branch`, `switch`, `push`, etc. have their own usage documentation.
  More information: <https://git-scm.com/docs/git>.
  Create an empty Git repository:
      git init

The page for tar had 22 lines, and a page for git commit 19, in compact mode. Most pages in the lab ran to about 20 lines.

-l lists every page in the cache. There is no search of the text of the pages in tealdeer 1.9.0 (the help lists no such option), so use grep on the list of names:

$ tldr -l | wc -l
7383
$ tldr -l | grep '^docker' | head -8
docker
docker-build
docker-buildx-build
docker-buildx-create
docker-buildx-du
docker-buildx-inspect
docker-buildx-ls
docker-buildx-prune

The list has 7,383 lines in the lab: names of commands (docker) and subcommands joined by a minus (docker-build). The pages are grouped by platform in the cache: 4,734 in the folder common and 2,067 in linux, which makes 6,801. The rest of the list (the other platform folders were not counted) comes from pages for other systems.

A caution when you pipe the list into head. tealdeer 1.9.0 prints a panic message when the reader closes the pipe early:

$ tldr -l | head -5
!
$
%
((
,

thread 'main' (3084) panicked at /rustc/31fca3adb283cc9dfd56b49cdee9a96eb9c96ffd/library/std/src/io/stdio.rs:1165:9:
failed printing to stdout: Broken pipe (os error 32)
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

It is harmless (the lines you asked for were printed), but it looks alarming. The earlier command, grep and then head, did not show it in the lab. A similar message, "Could not write to stdout ... Broken pipe", appeared when a page was piped to head.

The cache has pages for several systems. On Linux, tldr looks in the common pages and the Linux pages. -p chooses another platform for one lookup, for example a page that only exists for Windows:

$ tldr -p windows ipconfig
  Display and manage the network configuration of Windows.
  More information: <https://learn.microsoft.com/windows-server/administration/windows-commands/ipconfig>.
  List all network adapters:
      ipconfig
  Show a detailed list of network adapters:
      ipconfig /all
  Renew the IP addresses for a network adapter:
      ipconfig /renew adapter

and one for macOS (the platform is called osx in the cache, and the help of 1.9.0 lists macos):

$ tldr -p osx say
  Convert text to speech.
  More information: <https://keith.github.io/xcode-man-pages/say.1.html>.
  Say a phrase aloud:
      say "I like to ride my bike."
  Read a file aloud:
      say --input-file filename.txt

A surprise in the lab. A command that has no common or Linux page is shown from another platform, without a warning. ipconfig on Ubuntu has no such command, and tldr ipconfig printed the macOS page:

$ tldr ipconfig
  View and control IP configuration state.
  More information: <https://keith.github.io/xcode-man-pages/ipconfig.8.html>.
  List all network interfaces:
      ipconfig getiflist
  Show the IP address of an interface:
      ipconfig getifaddr interface_name

The link in the page (a macOS manual page) is the only hint. If a page does not fit your system, check the link, and use -p linux to be sure you get a Linux page. That option was not run for this case.

-L chooses a language. Only English pages were downloaded in the lab ("Pages for the following languages were downloaded: en"), and a German request found nothing:

$ tldr -L de tar
Page `tar` not found in cache.
Try updating with `tldr --update`, or submit a pull request to:
https://github.com/tldr-pages/tldr

A page is a small Markdown file. Put it in the custom pages folder (tldr --show-paths prints where it is) and name it NAME.page.md. The first line is the title, the line that starts with > is the description, and each example is a line starting with - and a sentence, then the command in backticks. {{double braces}} mark what the reader changes. In the lab:

$ mkdir -p ~/.local/share/tealdeer/pages
$ printf '# deploy\n\n> Push the staging build to production.\n\n- Deploy a branch:\n\n`deploy {{branch}}`\n\n- Roll back the last deploy:\n\n`deploy --rollback`\n' > ~/.local/share/tealdeer/pages/deploy.page.md
$ tldr deploy
  Push the staging build to production.
  Deploy a branch:
      deploy branch
  Roll back the last deploy:
      deploy --rollback

It shows like any other page, and tldr -l lists it (line 1202 in the lab's list, since the list is sorted by name together with the others):

$ tldr -l | grep -n '^deploy'
1202:deploy

A page with the name of an existing page replaces the shared page. In the lab a custom ln.page.md was shown instead of the real ln page:

  My own ln page.
  Link:
      ln a b

(The test file was removed afterwards.) To add to a page instead of replacing it, make a patch: NAME.patch.md, with only the examples you want added. They appear at the end of the shared page. In the lab, a patch for tar:

$ printf -- '- Make a tar of a folder, skipping .git:\n\n`tar czf {{path/to/target.tar.gz}} --exclude=.git {{path/to/folder}}`\n' > ~/.local/share/tealdeer/pages/tar.patch.md
$ tldr tar | tail -4
      tar xf path/to/source.tar --wildcards "*.html"
  Make a tar of a folder, skipping .git:
      tar czf path/to/target.tar.gz --exclude=.git path/to/folder

Version 1.9.0 can also open the right file in your editor: tldr --edit-page NAME and tldr --edit-patch NAME, using the program named in the variable EDITOR. In the lab a small script stood in for the editor, and the files were created in the right place:

$ EDITOR=/tmp/ed.sh tldr --edit-page foo
Editing "/home/ubuntu/.local/share/tealdeer/pages/foo.page.md"
exit status: 0
/home/ubuntu/.local/share/tealdeer:
pages

/home/ubuntu/.local/share/tealdeer/pages:
foo.page.md

(The editor script wrote the page; a real editor was not used.) Custom pages are not shared and do not change when you update: the updates only touch the cache.

The settings are in ~/.config/tealdeer/config.toml. The file does not exist at first. tldr --seed-config creates one with every setting at its default:

$ tldr --seed-config
$ sed -n 1,16p ~/.config/tealdeer/config.toml
[style.description]
underline = false
bold = false
italic = false

[style.command_name]
foreground = "cyan"
underline = false
bold = false
italic = false

[style.example_text]
foreground = "green"
underline = false
bold = false
italic = false
...

The file has sections for the colours (style), the layout (display), the updates and the folders. The video used one setting only:

$ cat ~/.config/tealdeer/config.toml
[display]
compact = true

Without it, a page has a blank line between the examples and is longer. The same page for tar, default settings (37 lines, against 22 in compact mode):


  Archiving utility.
  Often combined with a compression method, such as `gzip` or `bzip2`.
  More information: <https://www.gnu.org/software/tar/manual/tar.html>.

  [c]reate an archive and write it to a [f]ile:

      tar cf path/to/target.tar path/to/file1 path/to/file2 ...

  [c]reate a g[z]ipped archive and write it to a [f]ile:

      tar czf path/to/target.tar.gz path/to/file1 path/to/file2 ...

  [c]reate a g[z]ipped (compressed) archive from a directory using relative paths:

      tar czf path/to/target.tar.gz --directory path/to/directory .

  E[x]tract a (compressed) archive [f]ile into the current directory [v]erbosely:

      tar xvf path/to/source.tar.ext
...

In the default settings, long option names are used when a page offers both (ln --symbolic). placeholder_format = "short" in the display section gave the short names instead (the lab printed ln -s), and show_title = true prints the command name as a title line above the page. Colours (the style sections) change how the parts of a page are painted, and a text page cannot show that. Reading the settings from another file (--config-path) and changing one for a single run (--override-config) are listed in the help of 1.9.0 and were not run.

The pages change every day. tldr --update downloads the current set (about 30 MB in the lab) and replaces the cache:

$ tldr --update
Successfully updated cache.
Pages for the following languages were downloaded: en
exit status: 0

The client checks the age of the cache. When it is old, it says so, once before the page:

$ tldr ln     (the lab set the dates of the cache back by 60 days)
The cache hasn't been updated for 60 days.
You should probably run `tldr --update` soon.

  Create links to files and directories.
  More information: <https://www.gnu.org/software/coreutils/manual/html_node/ln-invocation.html>.

and -q (quiet) leaves that message out:

$ tldr -q ln
Create links to files and directories.
  More information: <https://www.gnu.org/software/coreutils/manual/html_node/ln-invocation.html>.

tldr --clear-cache deletes the cache, after which the pages are gone until the next update:

Successfully cleared cache at `/tmp/h5/.cache/tealdeer/tldr-pages`.
Page cache not found. Please run `tldr --update` to download the cache.


and with auto_update = true in the updates section of the settings, a missing cache is downloaded by the first lookup, as the lab showed (the page for ln appeared right after the download):

$ printf '[updates]\nauto_update = true\n' > config.toml
$ tldr ln
Successfully created cache directory `/tmp/h5/.cache/tealdeer/tldr-pages`.
Successfully updated cache.
Pages for the following languages were downloaded: en


The update used the network, so a machine behind a proxy or with no internet needs the pages copied in some other way. That was not tried.

When the output is not a terminal, tldr leaves out the colours. In the lab, a pipe gave plain text, and the same command run on a terminal (through script, which fakes one) gave the example text wrapped in a green colour code (the ^[[32m is the escape character, shown by cat -v):

$ tldr ln | cat -v | head -2; script -qc 'tldr ln' /dev/null | cat -v | head -3
  Create links to files and directories.
  More information: <https://www.gnu.org/software/coreutils/manual/html_node/ln-invocation.html>.
---
  Create links to files and directories.^M
  More information: <https://www.gnu.org/software/coreutils/manual/html_node/ln-invocation.html>.^M
  ^[[32mCreate a symbolic link to a file or directory:^[[0m^M

(--color never and --color always set this by hand; --color never was the only one of the two run, and it showed no change in a pipe.)

--raw prints the page as the Markdown it is stored in, which is what a custom page looks like:

$ tldr --raw ln | head -9
# ln

> Create links to files and directories.
> More information: <https://www.gnu.org/software/coreutils/manual/html_node/ln-invocation.html>.

- Create a symbolic link to a file or directory:

`ln {{[-s|--symbolic]}} /{{path/to/file_or_directory}} {{path/to/symlink}}`

(Here {{[-s|--symbolic]}} is the source form of an option with a short and a long name; the client chooses which one to show, as in the settings section.) -f renders a Markdown file that is not in the cache, a way to check a page you are writing:

$ tldr -f /tmp/demo.md
  A demo page.
  Say hello:
      echo hello

With no arguments, tldr prints its help (and exits with status 2 in the lab). The long help of 1.9.0 lists the options, including ones this page did not use:

$ tldr
tealdeer 1.9.0: A fast TLDR client
Danilo Bargen <mail@dbrgn.ch>, Niklas Mohrin <dev@niklasmohrin.de>
...

Only tealdeer was run: the Haskell client (tldr-hs, behind the Ubuntu package called tldr) and the Python client (tldr-py) were not installed. The Ubuntu package of tealdeer 1.6.1 was installed only to show that its update fails; its pages were never shown. The release binary was Linux x86_64 only; other install routes (cargo, snap and others) were not tried. Not run: the style (colour) settings, --pager and use_pager, --config-path, --override-config, --short-options and --long-options, the extra platforms other than windows and osx, languages other than English (only one language was downloaded and asked), pages in a language that is partly translated, and the search section of the settings. The time stamp warning was produced with a faked date, not by waiting. The panic message on a closed pipe was seen with 1.9.0 only. Behind a proxy, offline from the start, and a very old cache (more than 60 days) were not tried. The pages are written by volunteers. The lab did not check them for accuracy beyond running the first example of a few of them.

Page cache not found. The cache is empty. Run tldr --update (needs the network), or set auto_update = true.

tldr --update fails with "Could not decompress downloaded ZIP archive". The old client from the Ubuntu 24.04 package downloads from an address that now returns a web page. Install a newer release of tealdeer (1.9.0 worked).

The page looks like it is for another system. tldr falls back to pages for other platforms when your system has none. Check the link at the top of the page, and use -p linux.

I see "Could not write to stdout" or a panic message. That is what tealdeer 1.9.0 prints when the program after the pipe (such as head) stops reading. The output you asked for was already printed.

The page is missing an option I need. The pages show common cases. Use man or the command's --help for the rest. You can add a patch with your own example.

My own page does not show. The file must be named NAME.page.md and be in the custom pages folder that tldr --show-paths names. The lab folder was ~/.local/share/tealdeer/pages.

Tips. Keep the cache fresh with an occasional tldr --update. Add a patch for the one example you always forget. For commands of your own team, write a page and share the file.