### install

Source: https://github.com/mklabs/tabtab/blob/master/api/installer.js.md

The main installation method. It writes to the shell config file, creates or edits the Tabtab internal script, and creates the actual completion script for the package.

```APIDOC
## install(options)

### Description
Top level install method. Does three things: Writes to SHELL config file, adding a new line to tabtab internal script. Creates or edit tabtab internal script. Creates the actual completion script for this package.

### Method
N/A (This appears to be a utility function, not a direct API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **name** (String) - Required - The program name to complete.
- **completer** (String) - Required - The actual program or binary that will act as the completer for the `name` program. Can be the same.
- **location** (String) - Required - The SHELL script config location (~/.bashrc, ~/.zshrc or ~/.config/fish/config.fish).

### Request Example
```json
{
  "name": "my-package",
  "completer": "my-package-cli",
  "location": "~/.zshrc"
}
```

### Response
#### Success Response (200)
N/A (This function likely performs file operations and may not return specific data upon success).

#### Response Example
N/A
```

--------------------------------

### Basic tabtab Completion Example in Node.js

Source: https://github.com/mklabs/tabtab/blob/master/readme.md

Demonstrates a basic implementation of tabtab completion in a Node.js script. It uses minimist for argument parsing and tabtab.log to output completion suggestions based on previous input. This example covers installing and uninstalling completions, and handling the completion environment.

```javascript
#! /usr/bin/env node

const tabtab = require('tabtab');
const opts = require('minimist')(process.argv.slice(2), {
  string: ['foo', 'bar'],
  boolean: ['help', 'version', 'loglevel']
});

const args = opts._;
const completion = env => {
  if (!env.complete) return;

  // Write your completions there

  if (env.prev === 'foo') {
    return tabtab.log(['is', 'this', 'the', 'real', 'life']);
  }

  if (env.prev === 'bar') {
    return tabtab.log(['is', 'this', 'just', 'fantasy']);
  }

  if (env.prev === '--loglevel') {
    return tabtab.log(['error', 'warn', 'info', 'notice', 'verbose']);
  }

  return tabtab.log([
    '--help',
    '--version',
    '--loglevel',
    'foo',
    'bar',
    'install-completion',
    'completion',
    'someCommand:someCommand is some kind of command with a description',
    {
      name: 'someOtherCommand:hey',
      description: 'You must add a description for items with ":" in them'
    },
    'anotherOne'
  ]);
};

const run = async () => {
  const cmd = args[0];

  // Write your CLI there

  // Here we install for the program `tabtab-test` (this file), with
  // completer being the same program. Sometimes, you want to complete
  // another program that's where the `completer` option might come handy.
  if (cmd === 'install-completion') {
    await tabtab
      .install({
        name: 'tabtab-test',
        completer: 'tabtab-test'
      })
      .catch(err => console.error('INSTALL ERROR', err));

    return;
  }

  if (cmd === 'uninstall-completion') {
    // Here we uninstall for the program `tabtab-test` (this file).
    await tabtab
      .uninstall({
        name: 'tabtab-test'
      })
      .catch(err => console.error('UNINSTALL ERROR', err));

    return;
  }

  // The completion command is added automatically by tabtab when the program
  // is completed.
  if (cmd === 'completion') {
    const env = tabtab.parseEnv(process.env);
    return completion(env);
  }
};

run();

```

--------------------------------

### Install Function

Source: https://github.com/mklabs/tabtab/blob/master/api/index.js.md

The `install` function is used to set up and enable shell completion for users. It prompts for the shell type (bash, zsh, or fish) and the path to the shell script.

```APIDOC
## install(Options)

### Description
Install and enable completion on user system. It'll ask for:

- SHELL (bash, zsh or fish)
- Path to shell script (with sensible defaults)

### Method
GLOBAL FUNCTION

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **Options** (Object) - Required - Options to use with namely `name` and `completer`

### Request Example
```json
{
  "Options": {
    "name": "my-cli-command",
    "completer": "/path/to/your/completer/script"
  }
}
```

### Response
#### Success Response (200)
No specific success response documented, implies successful execution.

#### Response Example
None provided.
```

--------------------------------

### Install Tabtab Completion for CLI Program (Node.js)

Source: https://context7.com/mklabs/tabtab/llms.txt

Installs tab completion for a specified CLI program. It prompts the user for their shell type and creates necessary configuration files. This function is typically called during the CLI program's installation or setup process.

```javascript
const tabtab = require('tabtab');

// Install completion for a program
await tabtab.install({
  name: 'my-cli',
  completer: 'my-cli'
})
.then(() => console.log('Completion installed successfully'))
.catch(err => console.error('Installation failed:', err));

// In your CLI program's entry point
if (process.argv[2] === 'install-completion') {
  await tabtab.install({
    name: 'my-cli',
    completer: 'my-cli'
  });
}
```

--------------------------------

### Install Shell Completion with tabtab

Source: https://github.com/mklabs/tabtab/blob/master/api/index.js.md

The `install` function is used to set up and enable shell autocompletion on a user's system. It prompts the user to select a shell (bash, zsh, or fish) and specifies the path to the shell script, with default values provided.

```javascript
/**
 * Installs and enables completion on user system.
 * @param {object} Options - Options to use with namely `name` and `completer`.
 */
function install(Options) {
  // Implementation details for installing completion
}
```

--------------------------------

### npm Completion Script Example (Bash/Zsh)

Source: https://github.com/mklabs/tabtab/blob/master/readme.md

This is a conceptual example of how npm's completion script works for bash and zsh. It illustrates dumping a script to the console that maps completion functions to the npm executable, enabling command-line tab completion using Node.js and JavaScript.

```bash
npm completion
```

--------------------------------

### Install Command-Line Completions with tabtab.install()

Source: https://github.com/mklabs/tabtab/blob/master/readme.md

Installs shell completion for a specified program. It prompts the user for their shell and optionally a path to write the completion script. This function returns a promise and can be used with async/await.

```javascript
tabtab.install({
  name: 'tabtab-test',
  completer: 'tabtab-test'
})
  .then(() => console.log('Completion installed'))
  .catch(err => console.error(err))
```

--------------------------------

### Install tabtab Node.js Package

Source: https://github.com/mklabs/tabtab/blob/master/readme.md

Installs the tabtab package using npm. This is the initial step to integrate tabtab into your project for managing command-line completions.

```bash
npm install tabtab
```

--------------------------------

### Programmatic Installation of tabtab Completion (JavaScript)

Source: https://context7.com/mklabs/tabtab/llms.txt

Demonstrates how to programmatically install tabtab completion for a CLI application using Node.js. The 'tabtab.install' function handles the necessary steps, including modifying shell configuration files and creating completion scripts. It logs success or failure messages and provides instructions for reloading the shell.

```javascript
const tabtab = require('tabtab');

// Installation creates three things:
// 1. Adds source line to ~/.bashrc (or ~/.zshrc, ~/.config/fish/config.fish)
//    [ -f ~/.config/tabtab/__tabtab.bash ] && . ~/.config/tabtab/__tabtab.bash || true
//
// 2. Creates/updates ~/.config/tabtab/__tabtab.bash with:
//    [ -f ~/.config/tabtab/my-cli.bash ] && . ~/.config/tabtab/my-cli.bash || true
//
// 3. Creates ~/.config/tabtab/my-cli.bash with shell-specific completion function

// Programmatic installation
const installCompletion = async () => {
  try {
    await tabtab.install({
      name: 'my-cli',      // Program to complete
      completer: 'my-cli'  // Program that provides completions
    });
    console.log('Installation complete. Reload your shell:');
    console.log('  source ~/.bashrc    # for bash');
    console.log('  source ~/.zshrc     # for zsh');
    console.log('  source ~/.config/fish/config.fish  # for fish');
  } catch (err) {
    console.error('Installation failed:', err);
  }
};

```

--------------------------------

### Bash Shell Script Template for tabtab Completion

Source: https://context7.com/mklabs/tabtab/llms.txt

An example of a Bash completion script generated by tabtab. This script defines a completion function that interacts with the CLI program to get completion suggestions and configures the 'complete' command to use this function for the 'my-cli' command.

```bash
# Generated completion script for Bash
###-begin-my-cli-completion-###
if type complete &>/dev/null; then
  _my-cli_completion () {
    local words cword
    if type _get_comp_words_by_ref &>/dev/null; then
      _get_comp_words_by_ref -n = -n @ -n : -w words -i cword
    else
      cword="$COMP_CWORD"
      words=("${COMP_WORDS[@]}")
    fi

    local si="$IFS"
    IFS=$'\n' COMPREPLY=($(COMP_CWORD="$cword" \
                           COMP_LINE="$COMP_LINE" \
                           COMP_POINT="$COMP_POINT" \
                           my-cli completion -- "${words[@]}" \
                           2>/dev/null)) || return $?
    IFS="$si"
    if type __ltrim_colon_completions &>/dev/null; then
      __ltrim_colon_completions "${words[cword]}"
    fi
  }
  complete -o default -F _my-cli_completion my-cli
fi
###-end-my-cli-completion-###

```

--------------------------------

### Install Tabtab Bash Completion

Source: https://github.com/mklabs/tabtab/blob/master/readme.md

This snippet shows how to add Tabtab completion to your ~/.bashrc file. It sources a main Tabtab bash script, which in turn loads individual package completion scripts. This method consolidates completion sources into a single line for cleaner shell configuration.

```bash
# tabtab source for packages
# uninstall by removing these lines
[ -f ~/.config/tabtab/__tabtab.bash ] && . ~/.config/tabtab/__tabtab.bash || true

# tabtab source for foo package
# uninstall by removing these lines
[ -f ~/.config/tabtab/foo.bash ] && . ~/.config/tabtab/foo.bash || true

# tabtab source for tabtab-test package
# uninstall by removing these lines
[ -f ~/.config/tabtab/tabtab-test.bash ] && . ~/.config/tabtab/tabtab-test.bash || true
```

--------------------------------

### Bash Completion Script Generated by Tabtab

Source: https://github.com/mklabs/tabtab/blob/master/readme.md

An example of a Bash completion script generated by tabtab. This script defines a function that is invoked when tab completion is triggered for a specific program, and it calls the program's completion command.

```bash
###-begin-tabtab-test-completion-###
if type complete &>/dev/null; then
  _tabtab-test_completion () {
    local words cword
    if type _get_comp_words_by_ref &>/dev/null;
 then
      _get_comp_words_by_ref -n = -n @ -n : -w words -i cword
    else
      cword="$COMP_CWORD"
      words=("${COMP_WORDS[@]}")
    fi

    local si="$IFS"
    IFS=$'\n' COMPREPLY=($(COMP_CWORD="$cword"
                           COMP_LINE="$COMP_LINE"
                           COMP_POINT="$COMP_POINT"
                           tabtab-test completion -- "${words[@]}" \
                           2>/dev/null)) || return $?
    IFS="$si"
    if type __ltrim_colon_completions &>/dev/null;
 then
      __ltrim_colon_completions "${words[cword]}"
    fi
  }
  complete -o default -F _tabtab-test_completion tabtab-test
fi
###-end-tabtab-test-completion-###
```

--------------------------------

### uninstall

Source: https://github.com/mklabs/tabtab/blob/master/api/installer.js.md

Uninstalls a given package's completion from internal Tabtab scripts and/or the shell configuration. It also removes relevant scripts if no more completions are installed.

```APIDOC
## uninstall(options)

### Description
Here the idea is to uninstall a given package completion from internal tabtab scripts and / or the SHELL config. It also removes the relevant scripts if no more completion are installed on the system.

### Method
N/A (This appears to be a utility function, not a direct API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **name** (String) - Required - The package name to look for.

### Request Example
```json
{
  "name": "my-package"
}
```

### Response
#### Success Response (200)
N/A (This function likely performs file operations and may not return specific data upon success).

#### Response Example
N/A
```

--------------------------------

### Complete CLI Autocompletion with tabtab (JavaScript)

Source: https://context7.com/mklabs/tabtab/llms.txt

A full example of integrating tabtab into a Node.js CLI program. It handles command parsing using minimist and defines a completion handler for flags, subcommands, and default options. Dependencies include 'tabtab' for completion logic and 'minimist' for argument parsing.

```javascript
#!/usr/bin/env node
const tabtab = require('tabtab');
const minimist = require('minimist');

const opts = minimist(process.argv.slice(2), {
  string: ['config', 'output'],
  boolean: ['help', 'version', 'verbose']
});

const args = opts._;

// Completion handler
const completion = env => {
  if (!env.complete) return;

  // Complete for --config flag
  if (env.prev === '--config') {
    return tabtab.log(['development.json', 'production.json', 'test.json']);
  }

  // Complete for --output flag
  if (env.prev === '--output') {
    return tabtab.log(['json', 'yaml', 'xml']);
  }

  // Complete subcommands for 'build' command
  if (env.prev === 'build') {
    return tabtab.log([
      'client:Build client application',
      'server:Build server application',
      'all:Build everything'
    ]);
  }

  // Default completions
  return tabtab.log([
    '--help',
    '--version',
    '--config',
    '--output',
    '--verbose',
    'build:Build the project',
    'test:Run tests',
    'deploy:Deploy application'
  ]);
};

const run = async () => {
  const cmd = args[0];

  // Handle installation
  if (cmd === 'install-completion') {
    await tabtab.install({
      name: 'my-cli',
      completer: 'my-cli'
    }).catch(err => console.error('Install error:', err));
    return;
  }

  // Handle uninstallation
  if (cmd === 'uninstall-completion') {
    await tabtab.uninstall({
      name: 'my-cli'
    }).catch(err => console.error('Uninstall error:', err));
    return;
  }

  // Handle completion
  if (cmd === 'completion') {
    const env = tabtab.parseEnv(process.env);
    return completion(env);
  }

  // Regular CLI logic
  if (opts.help) {
    console.log('Usage: my-cli [options] <command>');
    return;
  }

  if (cmd === 'build') {
    console.log('Building project...');
  }
};

run();

```

--------------------------------

### Enable Tabtab Debug Logging in Bash

Source: https://github.com/mklabs/tabtab/blob/master/readme.md

This example shows how to set the TABTAB_DEBUG environment variable in bash to redirect Tabtab's internal logs to a file, '/tmp/tabtab.log'. This is useful for diagnosing completion issues by inspecting the log file while triggering completions in another shell.

```bash
export TABTAB_DEBUG="/tmp/tabtab.log"
tail -f /tmp/tabtab.log

# in another shell
tabtab-test <tab>
```

--------------------------------

### tabtab.install()

Source: https://context7.com/mklabs/tabtab/llms.txt

Enables tab completion for a CLI program by prompting the user for their shell type and creating necessary configuration files.

```APIDOC
## tabtab.install()

### Description
Enables tab completion for a CLI program by prompting the user for their shell type and creating necessary configuration files in `~/.config/tabtab/`. This function writes completion scripts and adds source lines to shell configuration files.

### Method
Asynchronous function (Promise-based)

### Parameters
#### Request Body
- **name** (string) - Required - The name of the CLI program.
- **completer** (string) - Required - The name of the completer script to use.

### Request Example
```js
const tabtab = require('tabtab');

// Install completion for a program
await tabtab.install({
  name: 'my-cli',
  completer: 'my-cli'
})
.then(() => console.log('Completion installed successfully'))
.catch(err => console.error('Installation failed:', err));
```

### Response
#### Success Response (Promise resolves)
Indicates successful installation.

#### Response Example
```
Completion installed successfully
```

#### Error Response
Rejects the promise with an error object if installation fails.
```

--------------------------------

### writeToCompletionScript

Source: https://github.com/mklabs/tabtab/blob/master/api/installer.js.md

Writes a new completion script to the internal `~/.config/tabtab` directory. The script created varies depending on the shell used.

```APIDOC
## writeToCompletionScript(options)

### Description
This writes a new completion script in the internal `~/.config/tabtab` directory. Depending on the SHELL used, a different script is created for the given SHELL.

### Method
N/A (This appears to be a utility function, not a direct API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **name** (String) - Required - The package name to complete.
- **completer** (String) - Required - The binary that will act as the completer for the `name` program.

### Request Example
```json
{
  "name": "my-package",
  "completer": "my-package-cli"
}
```

### Response
#### Success Response (200)
N/A (This function likely performs a file operation and may not return specific data upon success).

#### Response Example
N/A
```

--------------------------------

### Log Completion Suggestions with tabtab.log()

Source: https://github.com/mklabs/tabtab/blob/master/readme.md

Logs completion suggestions to standard output. It can accept an array of strings or an array of objects with 'name' and 'description' properties for richer completions in shells that support them.

```javascript
tabtab.log([
  '--help',
  '--version',
  'command'
  'command-two'
]);
```

```javascript
tabtab.log([
  { name: 'command', description: 'Description for command' },
  'command-two:Description for command-two'
]);
```

--------------------------------

### Parse Environment Variables for Intelligent Completion with tabtab.parseEnv()

Source: https://github.com/mklabs/tabtab/blob/master/readme.md

Parses environment variables to provide context for intelligent completions. It returns an object containing details about the current completion request, such as the input line, cursor position, and previous words.

```javascript
const env = tabtab.parseEnv(process.env);
// env:
//
// - complete    A Boolean indicating whether we act in "plumbing mode" or not
// - words       The Number of words in the completed line
// - point       A Number indicating cursor position
// - line        The String input line
// - partial     The String part of line preceding cursor position
// - last        The last String word of the line
// - lastPartial The last word String of partial
// - prev        The String word preceding last
```

```javascript
if (env.prev === '--loglevel') {
  tabtab.log(['error', 'warn', 'info', 'notice', 'verbose']);
}
```

--------------------------------

### Completion Item Normalization

Source: https://github.com/mklabs/tabtab/blob/master/api/index.js.md

The `completionItem` function serves as a helper to normalize completion suggestions, accepting either strings or objects with `name` and `description` properties.

```APIDOC
## completionItem(item)

### Description
Helper to normalize String and Objects with { name, description } when logging out.

### Method
GLOBAL FUNCTION

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **item** (String | Object) - Required - Item to normalize. If an object, it should have `name` and `description` properties.

### Request Example
```javascript
const normalizedItem = tabtab.completionItem({ name: 'option1', description: 'First option' });
// or
const normalizedItemString = tabtab.completionItem('option2');
```

### Response
#### Success Response (200)
Returns the normalized item, typically an object with `name` and `description` properties.

#### Response Example
```json
{
  "name": "option1",
  "description": "First option"
}
```
```

--------------------------------

### writeToShellConfig

Source: https://github.com/mklabs/tabtab/blob/master/api/installer.js.md

Writes a new line to the specified shell configuration file, ensuring Tabtab works for the given shell.

```APIDOC
## writeToShellConfig(options)

### Description
Writes to SHELL config file adding a new line, but only one, to the SHELL config script. This enables tabtab to work for the given SHELL.

### Method
N/A (This appears to be a utility function, not a direct API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **location** (String) - Required - The SHELL script location (~/.bashrc, ~/.zshrc or ~/.config/fish/config.fish).
- **name** (String) - Required - The package configured for completion.

### Request Example
```json
{
  "location": "~/.bashrc",
  "name": "my-package"
}
```

### Response
#### Success Response (200)
N/A (This function likely performs a file operation and may not return specific data upon success).

#### Response Example
N/A
```

--------------------------------

### Log Completion Arguments with tabtab

Source: https://github.com/mklabs/tabtab/blob/master/api/index.js.md

The `log` function is the primary utility for outputting completion suggestions to standard output. Each suggestion is printed on a new line. Note that Bash requires additional filtering for this to work correctly, while zsh and fish do not.

```javascript
/**
 * Main logging utility to pass completion items.
 *
 * This is simply an helper to log to stdout with each item separated by a new
 * line.
 *
 * Bash needs in addition to filter out the args for the completion to work
 * (zsh, fish don't need this).
 *
 * @param {Array} Arguments - to log, Strings or Objects with name and description property.
 */
function log(Arguments) {
  Arguments.forEach(item => {
    // Normalize item if necessary, e.g., using completionItem helper
    const normalizedItem = typeof item === 'object' && item !== null ? item : { name: item };
    console.log(normalizedItem.name);
    // Potentially log description for shells that support it
    // if (normalizedItem.description) {
    //   console.log(`${normalizedItem.name}\t${normalizedItem.description}`);
    // }
  });
}
```

--------------------------------

### tabtab.log()

Source: https://context7.com/mklabs/tabtab/llms.txt

Outputs completion suggestions to stdout in a shell-appropriate format.

```APIDOC
## tabtab.log()

### Description
Outputs completion suggestions to stdout in a shell-appropriate format. Accepts strings or objects with name and description properties. Handles shell-specific formatting automatically.

### Method
Synchronous function

### Parameters
#### Request Body
- **suggestions** (array) - Required - An array of strings or objects representing completion suggestions.
  - Each string can be a simple suggestion or in the format 'name:description'.
  - Each object should have `name` (string) and optionally `description` (string) properties.

### Request Example
```js
const tabtab = require('tabtab');

// Simple string completions
tabtab.log(['--help', '--version', 'start', 'stop']);

// Completions with descriptions (for zsh/fish)
tabtab.log([
  { name: 'start', description: 'Start the server' },
  { name: 'stop', description: 'Stop the server' }
]);

// Shorthand syntax with colon separator
tabtab.log([
  'start:Start the server',
  'stop:Stop the server',
  'restart:Restart the server'
]);
```

### Response
This function writes to stdout and does not return a value.
```

--------------------------------

### Parse Shell Environment Variables for Tab Completion Context (Node.js)

Source: https://context7.com/mklabs/tabtab/llms.txt

Parses shell completion environment variables to extract context about the current completion request. It returns an object containing information such as cursor position, partial input, and surrounding words, enabling context-aware completions.

```javascript
const tabtab = require('tabtab');

// Parse completion environment
const env = tabtab.parseEnv(process.env);

// env contains:
// {
//   complete: true,           // Boolean indicating completion mode
//   words: 2,                 // Number of words in line
//   point: 15,                // Cursor position
//   line: 'my-cli foo --',    // Full input line
//   partial: 'my-cli foo --', // Line before cursor
//   last: '--',               // Last word
//   lastPartial: '--',        // Last word in partial
//   prev: 'foo'               // Previous word
// }

// Use env to provide context-aware completions
if (env.prev === '--config') {
  tabtab.log(['development', 'production', 'test']);
}
```

--------------------------------

### tabtab.parseEnv()

Source: https://context7.com/mklabs/tabtab/llms.txt

Parses shell completion environment variables to extract context about the current completion request.

```APIDOC
## tabtab.parseEnv()

### Description
Parses shell completion environment variables to extract context about the current completion request. Returns an object with information about cursor position, partial input, and surrounding words.

### Method
Synchronous function

### Parameters
#### Request Body
- **process.env** (object) - Required - The environment variables object from Node.js `process.env`.

### Request Example
```js
const tabtab = require('tabtab');

// Parse completion environment
const env = tabtab.parseEnv(process.env);

// env contains:
// {
//   complete: true,           // Boolean indicating completion mode
//   words: 2,                 // Number of words in line
//   point: 15,                // Cursor position
//   line: 'my-cli foo --',    // Full input line
//   partial: 'my-cli foo --', // Line before cursor
//   last: '--',               // Last word
//   lastPartial: '--',        // Last word in partial
//   prev: 'foo'               // Previous word
// }
```

### Response
#### Success Response (Object)
An object containing completion context.

#### Response Example
```json
{
  "complete": true,
  "words": 2,
  "point": 15,
  "line": "my-cli foo --",
  "partial": "my-cli foo --",
  "last": "--",
  "lastPartial": "--",
  "prev": "foo"
}
```
```

--------------------------------

### writeLineToFilename

Source: https://github.com/mklabs/tabtab/blob/master/api/installer.js.md

Opens a file and adds a new source line for the given script name. This function is used for both shell scripts and Tabtab's internal scripts.

```APIDOC
## writeLineToFilename(options)

### Description
Opens a file for modification adding a new `source` line for the given SHELL. Used for both SHELL script and tabtab internal one.

### Method
N/A (This appears to be a utility function, not a direct API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **filename** (String) - Required - The file to modify.
- **scriptname** (String) - Required - The line to add sourcing this file.
- **name** (String) - Required - The package being configured.

### Request Example
```json
{
  "filename": "~/.bashrc",
  "scriptname": "source ~/.tabtab/completions/my-package",
  "name": "my-package"
}
```

### Response
#### Success Response (200)
N/A (This function likely performs a file operation and may not return specific data upon success).

#### Response Example
N/A
```

--------------------------------

### Parse Environment Function

Source: https://github.com/mklabs/tabtab/blob/master/api/index.js.md

The `parseEnv` function is a public utility that extracts information from command-line arguments and environment variables, specifically designed for command completion in 'plumbing' mode.

```APIDOC
## parseEnv()

### Description
Public: Main utility to extract information from command line arguments and
Environment variables, namely COMP args in "plumbing" mode.

### Method
GLOBAL FUNCTION

### Endpoint
None

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (Object) - Optional - The options hash as parsed by minimist, plus an env property representing user environment (default: { env: process.env })
- **_** (Array) - Optional - The arguments Array parsed by minimist (positional arguments)
- **env** (Object) - Optional - The environment Object that holds COMP args (default: process.env)

### Request Example
```javascript
const env = tabtab.parseEnv();
```

### Response
#### Success Response (200)
- **complete** (Boolean) - Indicates whether we act in "plumbing mode" or not
- **words** (Number) - The Number of words in the completed line
- **point** (Number) - A Number indicating cursor position
- **line** (String) - The String input line
- **partial** (String) - The String part of line preceding cursor position
- **last** (String) - The last String word of the line
- **lastPartial** (String) - The last word String of partial
- **prev** (String) - The String word preceding last

#### Response Example
```json
{
  "complete": true,
  "words": 5,
  "point": 10,
  "line": "node my_script.js --option=",
  "partial": "node my_script.js --option=",
  "last": "--option=",
  "lastPartial": "--option=",
  "prev": "node"
}
```
```

--------------------------------

### writeToTabtabScript

Source: https://github.com/mklabs/tabtab/blob/master/api/installer.js.md

Writes to Tabtab's internal script, which acts as a frontend router for the completion mechanism. Every completion is added to this file.

```APIDOC
## writeToTabtabScript(options)

### Description
Writes to tabtab internal script that acts as a frontend router for the completion mechanism, in the internal ~/.config/tabtab directory. Every completion is added to this file.

### Method
N/A (This appears to be a utility function, not a direct API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **name** (String) - Required - The package configured for completion.

### Request Example
```json
{
  "name": "my-package"
}
```

### Response
#### Success Response (200)
N/A (This function likely performs a file operation and may not return specific data upon success).

#### Response Example
N/A
```

--------------------------------

### tabtab.uninstall()

Source: https://context7.com/mklabs/tabtab/llms.txt

Removes tab completion for a CLI program by deleting completion scripts and cleaning up shell configuration files.

```APIDOC
## tabtab.uninstall()

### Description
Removes tab completion for a CLI program by deleting completion scripts and cleaning up shell configuration files. If no other tabtab completions remain, it removes all tabtab source lines.

### Method
Asynchronous function (Promise-based)

### Parameters
#### Request Body
- **name** (string) - Required - The name of the CLI program.

### Request Example
```js
const tabtab = require('tabtab');

// Uninstall completion for a program
await tabtab.uninstall({
  name: 'my-cli'
})
.then(() => console.log('Completion uninstalled successfully'))
.catch(err => console.error('Uninstallation failed:', err));
```

### Response
#### Success Response (Promise resolves)
Indicates successful uninstallation.

#### Response Example
```
Completion uninstalled successfully
```

#### Error Response
Rejects the promise with an error object if uninstallation fails.
```

--------------------------------

### Uninstall Tabtab Completion using JavaScript API

Source: https://github.com/mklabs/tabtab/blob/master/readme.md

This JavaScript code demonstrates how to programmatically uninstall Tabtab completion for a specific program, 'tabtab-test', using the tabtab.uninstall() method. It includes basic error handling.

```javascript
if (cmd === 'uninstall-completion') {
  // Here we uninstall for the program `tabtab-test`
  await tabtab
    .uninstall({
      name: 'tabtab-test'
    })
    .catch(err => console.error('UNINSTALL ERROR', err));

  return;
}
```

--------------------------------

### Normalize Completion Item with tabtab

Source: https://github.com/mklabs/tabtab/blob/master/api/index.js.md

The `completionItem` function serves as a helper to standardize the format of completion suggestions. It takes either a string or an object with `name` and `description` properties and normalizes it for consistent output.

```javascript
/**
 * Helper to normalize String and Objects with { name, description } when logging out.
 * @param {String|Object} item - Item to normalize.
 * @returns {Object} The normalized completion item.
 */
function completionItem(item) {
  // Implementation details for normalizing items
  if (typeof item === 'string') {
    return { name: item };
  } else if (typeof item === 'object' && item !== null) {
    return item;
  }
  return {}; // Or throw an error for invalid input
}
```

--------------------------------

### Parse Environment Variables with tabtab

Source: https://github.com/mklabs/tabtab/blob/master/api/index.js.md

The `parseEnv` function is a public utility for extracting information from command-line arguments and environment variables, specifically for completion arguments in 'plumbing' mode. It returns an object containing details about the completion context, such as the number of words, cursor position, and the input line.

```javascript
/**
 * Public: Main utility to extract information from command line arguments and
 * Environment variables, namely COMP args in "plumbing" mode.
 *
 * options - The options hash as parsed by minimist, plus an env property
 *           representing user environment (default: { env: process.env })
 *  :_      - The arguments Array parsed by minimist (positional arguments)
 *  :env    - The environment Object that holds COMP args (default: process.env)
 *
 * Returns the data env object.
 */
function parseEnv() {
  // Implementation details for parsing environment variables
  const env = {};
  // ... logic to populate env object based on process.env and arguments
  return env;
}

// Example usage:
// const completionEnv = tabtab.parseEnv();
// console.log(completionEnv);

```

--------------------------------

### Log Function

Source: https://github.com/mklabs/tabtab/blob/master/api/index.js.md

The `log` function is the main utility for outputting completion items to standard output. Each item is separated by a newline character. Bash may require additional filtering for completion to function correctly.

```APIDOC
## log(Arguments)

### Description
Main logging utility to pass completion items.

This is simply an helper to log to stdout with each item separated by a new
line.

Bash needs in addition to filter out the args for the completion to work
(zsh, fish don't need this).

### Method
GLOBAL FUNCTION

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **Arguments** (Array) - Required - Array of items to log. Items can be strings or objects with `name` and `description` properties.

### Request Example
```javascript
tabtab.log(['option1', { name: 'option2', description: 'Second option' }]);
```

### Response
#### Success Response (200)
Outputs completion items to stdout, each on a new line.

#### Response Example
```
option1
option2: Second option
```
```

--------------------------------

### Uninstall Tabtab Completion for CLI Program (Node.js)

Source: https://context7.com/mklabs/tabtab/llms.txt

Removes tab completion for a specified CLI program. It deletes completion scripts and cleans up shell configuration files. If no other tabtab completions exist, it also removes tabtab source lines from shell configurations.

```javascript
const tabtab = require('tabtab');

// Uninstall completion for a program
await tabtab.uninstall({
  name: 'my-cli'
})
.then(() => console.log('Completion uninstalled successfully'))
.catch(err => console.error('Uninstallation failed:', err));

// In your CLI program
if (process.argv[2] === 'uninstall-completion') {
  await tabtab.uninstall({
    name: 'my-cli'
  });
}
```

--------------------------------

### removeLinesFromFilename

Source: https://github.com/mklabs/tabtab/blob/master/api/installer.js.md

Removes three specific lines from a given file based on the provided package name. This is used during uninstallation.

```APIDOC
## removeLinesFromFilename(filename, name)

### Description
Removes the 3 relevant lines from provided filename, based on the package name passed in.

### Method
N/A (This appears to be a utility function, not a direct API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```json
{
  "filename": "~/.bashrc",
  "name": "my-package"
}
```

### Response
#### Success Response (200)
N/A (This function likely performs a file operation and may not return specific data upon success).

#### Response Example
N/A
```

--------------------------------

### checkFilenameForLine

Source: https://github.com/mklabs/tabtab/blob/master/api/installer.js.md

Checks if a specific line exists within a given file. This is primarily used to prevent duplicate completion sources from being added to shell scripts.

```APIDOC
## checkFilenameForLine(filename, line)

### Description
Checks a given file for the existence of a specific line. Used to prevent adding multiple completion source to SHELL scripts.

### Method
N/A (This appears to be a utility function, not a direct API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **return value** (Boolean) - true if the line is present, false otherwise.

#### Response Example
```json
true
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.