# completarr

> Zero config autocompletions for yargs apps (bash, zsh, fish)

Latest version **0.2.2** (published 2019-06-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install completarr
pnpm add completarr
yarn add completarr
bun add completarr
```

Provides the commands `install-yargs-completion`, `uninstall-yargs-completion`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.2 |
| Published | 2019-06-05 |
| First published | 2018-07-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 9.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Florian Reuschel |
| Maintainers | loilo |
| Keywords | autocomplete, bash, complete, fish, omelette, yargs, zsh |

## Links

- npm: https://www.npmjs.com/package/completarr
- Repository: https://github.com/Loilo/completarr
- Homepage: https://github.com/Loilo/completarr#readme
- Issues: https://github.com/Loilo/completarr/issues
- npm.io page: https://npm.io/package/completarr

## Dependencies (3)

- [omelette](https://npm.io/package/omelette.md) ^0.4.11
- [string-argv](https://npm.io/package/string-argv.md) ^0.3.0
- [yargs-parser](https://npm.io/package/yargs-parser.md) ^13.1.0

## Recent versions

- 0.2.2 (latest) — 2019-06-05
- 0.2.1 — 2018-07-31
- 0.2.0 — 2018-07-31
- 0.1.3 — 2018-07-30
- 0.1.2 — 2018-07-30
- 0.1.1 — 2018-07-30
- 0.1.0 — 2018-07-30

## README

# Completarr

[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
[![npm](https://img.shields.io/npm/v/completarr.svg)](https://www.npmjs.com/package/completarr)

Completarr is a zero config way to add shell auto completion for your [yargs](https://yargs.js.org)-based CLI applications.

You may want to use this over yargs' [built-in solution](http://yargs.js.org/docs/#api-completioncmd-description-fn) if you need to support a wider range of shells (including zsh and fish).

## Installation
```
npm install --save completarr
```

## Usage
To use Completarr, perform the following rather simple steps:

1. Integrate it into your CLI app:

   ```javascript
   require('completarr')()

   // Your yargs-related code
   ```
2. Add install/uninstall hooks to your `package.json` to automatically attach the completion script the user's shell init file:

   ```json
   {
     "scripts": {
       "postinstall": "install-yargs-completion",
       "uninstall": "uninstall-yargs-completion"
     }
   }
   ```

### Caveats
There are some things to consider:

* Completarr is based on [omelette](https://github.com/f/omelette) and therefore does not support Windows. 😕
* Completarr only works with globally installed commands.
* Your yargs app needs to expose its help via [`.help()`](http://yargs.js.org/docs/#api-help) to make Completarr work.

### Configuration
Completarr should work without any config 99% of the time, but there might be some edge cases in your app you want to handle:

#### Command Name (Shell Script)
By default, Completarr adds completion for all commands it finds in your `package.json`'s `bin` field. If you got more commands there than you want completion for, you need to pass them to the install/uninstall hook explicitely:

```javascript
// Your CLI app's package.json
{
  // We got three binaries:
  "bin": {
    "a": "./src/a",
    "b": "./src/b"
    "c": "./src/c"
  },
  "scripts": {
    // But we only want to install completions for "b" and "c":
    "postinstall": "install-yargs-completion b c",
    "uninstall": "uninstall-yargs-completion b c"
  }
}
```

#### Command Name (Node)
Completarr needs to know the name of your yargs root command to provide completions. By default it derives that from the binary where Completarr is included:

```javascript
// file: src/hello
require('completarr')()

// Completarr assumes the command name is "hello"
```

However if for some reason your command name does not equal your file's name, you may pass Completarr the command name manually:

```javascript
// file: src/foo.js
require('completarr')({
  name: 'hello'
})
```

#### Help Option
By default, yargs' option for showing the help output is `--help`. However, should you decide to publish the help under a different option ([which yargs allows you to do](http://yargs.js.org/docs/#api-helpoption-boolean)) you'll have to tell Completarr about it:

```javascript
// We use --info instead of --help
require('completarr')({
  helpOption: 'info'
})

// yargs-related code
require('yargs')
  .help('info')
  // ...
```

---
_Source: https://npm.io/package/completarr · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._