tldr-node-client

A Node.js based command-line client for tldr.

tldr-node-client's output for the tar page, using a custom color theme

Installing

npm install -g tldr

Install from the snap store

In any of the supported Linux distros:

sudo snap install tldr

If you want to help testing the latest changes, and get the newer features earlier, you can install the snap from the edge channel:

sudo snap install tldr --edge

Usage

To see tldr pages:

• tldr <command> show examples for this command
• tldr <command> --os=<platform> show command page for the given platform (linux, osx, sunos)
• tldr --search "<query>" search all pages for the query
• tldr --linux <command> show command page for Linux
• tldr --osx <command> show command page for OSX
• tldr --sunos <command> show command page for SunOS
• tldr --list show all pages for current platform
• tldr --list-all show all available pages
• tldr --random show a page at random
• tldr --random-example show a single random example
• tldr --markdown show the original markdown format page
• tldr --config <path> load a custom config file (default ~/.tldrrc)')

There are more commands to control the local cache:

• tldr --update download the latest pages and generate search index
• tldr --clear-cache delete the entire local cache

As a contributor, you might also need the following commands:

• tldr --render <path> render a local page for testing purposes

Configuration

You can configure the tldr client by adding a .tldrrc file in your HOME directory. You can copy the contents of the config.json file from the repo to get the basic structure to start with, and modify it to suit your needs.

Themes

The default color theme is the one named "simple". You can change the theme by assigning a different value to the "theme" variable -- either to one of the pre-configured themes, or to a new theme that you have previously created in the "themes" section. Note that the colors and text effects you can choose are limited. Refer to the chalk documentation for all options.

{
  "themes": {
    "ocean": {
      "commandName": "bold, cyan",
      "mainDescription": "",
      "exampleDescription": "green",
      "exampleCode": "cyan",
      "exampleToken": "dim"
    },
    "myOwnCoolTheme": {
      "commandName": "bold, red",
      "mainDescription": "underline",
      "exampleDescription": "yellow",
      "exampleCode": "underline, green",
      "exampleToken": ""
    }
  },
  "theme": "ocean"
}

Cache

The client caches a copy of all pages locally, in ~/.tldr, this line in the config file will override the default behaviour:

{
  "cache": "/path/to/cache"
}

Platforms

If you regularly need pages for a different platform (e.g. Linux), you can put it in the config file:

{
  "platform": "linux"
}

The default platform value can be overwritten with command-line option:

tldr du --os=osx

As a contributor, you can also point to your own fork containing the tldr.zip file. The file is just a zipped version of the entire tldr repo:

{
  "repository" : "http://myrepo/assets/tldr.zip",
}

Custom config file

You can have differents config files and choose which one to use at runtime with the option:

tldr --config ".mytldrrc"

For practical use you can define an alias:

alias mytldr='tldr --config ".mytldrrc"'

Command-line Autocompletion

Currently we only support command-line autocompletion for zsh. Pull requests for other shells are most welcome!

zsh

It's easiest for oh-my-zsh users, so let's start with that.

mkdir -p $ZSH_CUSTOM/plugins/tldr
ln -s bin/autocompletion.zsh $ZSH_CUSTOM/plugins/tldr/_tldr

Then add tldr to your oh-my-zsh plugins, usually defined in ~/.zshrc, resulting in something looking like this:

plugins=(git tmux tldr)

Fret not regular zsh user! Copy or symlink bin/autocompletion.zsh to my/completions/_tldr (note the filename). Then add the containing directory to your fpath:

fpath = (my/completions $fpath)

FAQ

Installation Issues

• If you are trying to install as non-root user (npm install -g tldr) and get something like -

Error: EACCES: permission denied, access '/usr/local/lib/node_modules/tldr'

Then most probably your npm's default installation directory has improper permissions. You can resolve it by clicking here

• If you are trying to install as a root user (sudo npm install -g tldr) and get something like -

as root -> 
gyp WARN EACCES attempting to reinstall using temporary dev dir "/usr/local/lib/node_modules/tldr/node_modules/webworker-threads/.node-gyp"
gyp WARN EACCES user "root" does not have permission to access the dev dir "/usr/local/lib/node_modules/tldr/node_modules/webworker-threads/.node-gyp/8.9.1"

You need to add the option --unsafe-perm to your command. This is because when npm goes to the postinstall step, it downgrades the permission levels to "nobody". Probably you should fix your installation directory permissions and install as a non-root user in the first place.

• If you see an error related to webworker-threads like -

/usr/local/lib/node_modules/tldr/node_modules/natural/lib/natural/classifiers/classifier.js:32
    if (e.code !== 'MODULE_NOT_FOUND') throw e;

Most probably you need to reinstall node-gyp and webworker-threads. Try this -

sudo -H npm uninstall -g tldr
sudo -H npm uninstall -g webworker-threads
npm install -g node-gyp
npm install -g webworker-threads
npm install -g tldr

For further context, take a look at this issue

Colors under Cygwin

Colors can't be shown under Mintty or PuTTY, because the dependency colors.js has a bug. Please show support to this pull request, so it can be merged.

Meanwhile, you can do one of the following to fix this issue:

• Add the following script to your shell's rc file (.zshrc, .bashrc, etc.): (RECOMMENDED)

tldr_path="$(which tldr)"
function tldr() {
	eval "$tldr_path" $@ "--color"
}

• Add alias tldr="tldr --color=true" to your shell's rc file.
• Prepend process.stdout.isTTY = true; to tldr.js (NOT RECOMMENDED)
• Fix colors.js's logic (NOT RECOMMENDED)
  • Go to %appdata%\npm\node_modules\tldr\node_modules\colors\lib\system\
  • Overwrite supports-colors.js with supports-colors.js from my repo.
• Use CMD.exe.

Contributing

Contribution are most welcome! Have a look over here for a few rough guidelines.