UNPKG

7.9 kBMarkdownView Raw
1# tldr-node-client
2
3[![NPM version][npm-image]][npm-url]
4[![Travs CI Build Status][travis-image]][travis-url]
5[![AppVeyor CI Build status][appveyor-image]][appveyor-url]
6[![Gitter chat][gitter-image]][gitter-url]
7[![Snap Status](https://build.snapcraft.io/badge/tldr-pages/tldr-node-client.svg)](https://build.snapcraft.io/user/tldr-pages/tldr-node-client)
8
9A `Node.js` based command-line client for [tldr](https://github.com/tldr-pages/tldr).
10
11![tldr screenshot](screenshot.png)
12*tldr-node-client's output for the `tar` page, using a custom color theme*
13
14## Installing
15
16```bash
17npm install -g tldr
18```
19
20## Install from the snap store
21
22In any of the [supported Linux distros](https://snapcraft.io/docs/core/install):
23
24```bash
25sudo snap install tldr
26```
27
28If you want to help testing the latest changes, and get the newer features earlier, you can install the snap from the edge channel:
29
30```bash
31sudo snap install tldr --edge
32```
33
34## Usage
35
36To see tldr pages:
37
38- `tldr <command>` show examples for this command
39- `tldr <command> --os=<platform>` show command page for the given platform (`linux`, `osx`, `sunos`)
40- `tldr --search "<query>"` search all pages for the query
41- `tldr --linux <command>` show command page for Linux
42- `tldr --osx <command>` show command page for OSX
43- `tldr --sunos <command>` show command page for SunOS
44- `tldr --list` show all pages for current platform
45- `tldr --list-all` show all available pages
46- `tldr --random` show a page at random
47- `tldr --random-example` show a single random example
48- `tldr --markdown` show the original markdown format page
49
50The client caches a copy of all pages locally, in `~/.tldr`.
51There are more commands to control the local cache:
52
53- `tldr --update` download the latest pages and generate search index
54- `tldr --clear-cache` delete the entire local cache
55
56As a contributor, you might also need the following commands:
57
58- `tldr --render <path>` render a local page for testing purposes
59
60## Configuration
61
62You 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.
63
64The 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](https://github.com/chalk/chalk#styles) for all options.
65
66```json
67{
68 "themes": {
69 "ocean": {
70 "commandName": "bold, cyan",
71 "mainDescription": "",
72 "exampleDescription": "green",
73 "exampleCode": "cyan",
74 "exampleToken": "dim"
75 },
76 "myOwnCoolTheme": {
77 "commandName": "bold, red",
78 "mainDescription": "underline",
79 "exampleDescription": "yellow",
80 "exampleCode": "underline, green",
81 "exampleToken": ""
82 }
83 },
84 "theme": "ocean"
85}
86```
87
88If you regularly need pages for a different platform (e.g. Linux),
89you can put it in the config file:
90
91```json
92{
93 "platform": "linux"
94}
95```
96
97The default platform value can be overwritten with command-line option:
98
99```shell
100tldr du --os=osx
101```
102
103As 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:
104
105```js
106{
107 "repository" : "http://myrepo/assets/tldr.zip",
108}
109```
110
111## Command-line Autocompletion
112
113Currently we only support command-line autocompletion for zsh.
114Pull requests for other shells are most welcome!
115
116### zsh
117
118It's easiest for
119[oh-my-zsh](https://github.com/robbyrussell/oh-my-zsh)
120users, so let's start with that.
121
122```
123mkdir -p $ZSH_CUSTOM/plugins/tldr
124ln -s bin/autocompletion.zsh $ZSH_CUSTOM/plugins/tldr/_tldr
125```
126
127Then add tldr to your oh-my-zsh plugins,
128usually defined in `~/.zshrc`,
129resulting in something looking like this:
130
131```
132plugins=(git tmux tldr)
133```
134
135Fret not regular zsh user!
136Copy or symlink `bin/autocompletion.zsh` to
137`my/completions/_tldr`
138(note the filename).
139Then add the containing directory to your fpath:
140```
141fpath = (my/completions $fpath)
142```
143
144## FAQ
145
146#### Installation Issues
147
148- If you are trying to install as non-root user (`npm install -g tldr`) and get something like -
149
150 ```
151 Error: EACCES: permission denied, access '/usr/local/lib/node_modules/tldr'
152 ```
153
154 Then most probably your npm's default installation directory has improper permissions. You can resolve it by clicking [here](https://docs.npmjs.com/getting-started/fixing-npm-permissions)
155
156- If you are trying to install as a root user (`sudo npm install -g tldr`) and get something like -
157
158```
159as root ->
160gyp WARN EACCES attempting to reinstall using temporary dev dir "/usr/local/lib/node_modules/tldr/node_modules/webworker-threads/.node-gyp"
161gyp 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"
162```
163
164You 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.
165
166- If you see an error related to `webworker-threads` like -
167
168```
169/usr/local/lib/node_modules/tldr/node_modules/natural/lib/natural/classifiers/classifier.js:32
170 if (e.code !== 'MODULE_NOT_FOUND') throw e;
171```
172Most probably you need to reinstall `node-gyp` and `webworker-threads`. Try this -
173
174```
175sudo -H npm uninstall -g tldr
176sudo -H npm uninstall -g webworker-threads
177npm install -g node-gyp
178npm install -g webworker-threads
179npm install -g tldr
180```
181For further context, take a look at this [issue](https://github.com/tldr-pages/tldr-node-client/issues/179)
182
183#### Colors under Cygwin
184
185Colors can't be shown under Mintty or PuTTY, because the dependency `colors.js` has a bug.
186Please show support to [this pull request](https://github.com/Marak/colors.js/pull/154), so it can be merged.
187
188Meanwhile, you can do one of the following to fix this issue:
189
190* Add the following script to your shell's rc file (`.zshrc`, `.bashrc`, etc.): (RECOMMENDED)
191
192```bash
193tldr_path="$(which tldr)"
194function tldr() {
195 eval "$tldr_path" $@ "--color"
196}
197```
198* Add `alias tldr="tldr --color=true"` to your shell's rc file.
199* Prepend `process.stdout.isTTY = true;` to `tldr.js` (NOT RECOMMENDED)
200* Fix `colors.js`'s logic (NOT RECOMMENDED)
201 * Go to `%appdata%\npm\node_modules\tldr\node_modules\colors\lib\system\`
202 * Overwrite `supports-colors.js` with [supports-colors.js](https://raw.githubusercontent.com/RShadowhand/colors.js/master/lib/system/supports-colors.js) from my repo.
203* Use `CMD.exe`.
204
205## Contributing
206
207Contribution are most welcome!
208Have a look [over here](https://github.com/tldr-pages/tldr-node-client/blob/master/.github/CONTRIBUTING.md)
209for a few rough guidelines.
210
211[npm-url]: https://www.npmjs.com/package/tldr
212[npm-image]: https://img.shields.io/npm/v/tldr.svg
213
214[travis-url]: https://travis-ci.org/tldr-pages/tldr-node-client
215[travis-image]: https://img.shields.io/travis/tldr-pages/tldr-node-client.svg?label=linux
216
217[appveyor-image]: https://img.shields.io/appveyor/ci/igorshubovych/tldr-node-client-bnut4.svg?label=windows
218[appveyor-url]: https://ci.appveyor.com/project/igorshubovych/tldr-node-client-bnut4
219
220[dep-url]: https://david-dm.org/tldr-pages/tldr-node-client
221[dep-image]: https://david-dm.org/tldr-pages/tldr-node-client.svg?theme=shields.io
222
223[dev-dep-url]: https://david-dm.org/tldr-pages/tldr-node-client#info=devDependencies
224[dev-dep-image]: https://david-dm.org/tldr-pages/tldr-node-client/dev-status.svg?theme=shields.io
225
226[gitter-url]: https://gitter.im/tldr-pages/tldr
227[gitter-image]: https://badges.gitter.im/tldr-pages/tldr.png