jimkit-completion

Generate shell completion scripts (bash, zsh, fish) from declarative command definitions.

Install

pnpm add jimkit-completion

Usage

import {
  generateBashCompletion,
  generateZshCompletion,
  generateFishCompletion,
  type CompletionConfig,
} from "jimkit-completion";

const config: CompletionConfig = {
  names: {
    cmd: "myapp",           // bare command name
    fnPrefix: "_myapp",     // bash/zsh function prefix, fish variable prefix
    varPrefix: "_MYAPP",    // bash uppercase variable prefix
    fishFnPrefix: "__myapp", // fish function prefix
  },
  commands: [
    {
      name: "list",
      description: "List items",
      options: [
        { flags: "-f, --format <fmt>", description: "Output format", completeWith: "formats" },
        { flags: "-a, --all", description: "Show all" },
      ],
    },
    {
      name: "add",
      description: "Add an item",
      args: [{ name: "<title>", description: "Item title" }],
      options: [
        { flags: "-t, --tag <tag...>", description: "Tags", completeWith: "tags" },
      ],
    },
    {
      name: "group",
      description: "Manage groups",
      subcommands: [
        { name: "add", description: "Add a group", args: [{ name: "<name>", description: "Group name" }] },
        { name: "list", description: "List groups" },
      ],
    },
  ],
  dynamicCompleters: {
    tags: {
      cmd: "myapp tag list --plain 2>/dev/null",
      label: "tag",
      escapeColons: true,    // for zsh _describe with colon-containing values
      extra: {               // per-shell extras appended after cmd output
        fish: 'echo -e "all\\tall tags"',
      },
    },
  },
  staticCompleters: {
    formats: ["json", "text", "csv"],
  },
  globalOptions: [
    { long: "dir", description: "Override base directory", takesArg: true, argName: "path", zshCompleter: "_files -/" },
    { long: "help", description: "Show help" },
    { long: "version", description: "Show version" },
  ],
};

// Generate and wire up in your CLI:
//   eval "$(myapp completions bash)"
//   eval "$(myapp completions zsh)"
//   myapp completions fish > ~/.config/fish/completions/myapp.fish
const bash = generateBashCompletion(config);
const zsh = generateZshCompletion(config);
const fish = generateFishCompletion(config);

API

generateBashCompletion(config: CompletionConfig): string

Generates a bash completion script. Requires bash-completion (_init_completion).

generateZshCompletion(config: CompletionConfig): string

Generates a zsh completion script using _arguments and _values.

generateFishCompletion(config: CompletionConfig): string

Generates a fish completion script using complete -c.

Types

| Type | Description | |---|---| | CompletionConfig | Top-level config: names, commands, completers, global options | | CompletionNames | Name variants used in generated scripts | | CommandDef | Command with args, options, optional subcommands | | SubcommandDef | Subcommand with args and options | | ArgDef | Positional argument (supports variadic) | | OptionDef | Flag/option definition | | GlobalOption | Option available before any command | | DynamicCompleter | Shell command that produces completion values at runtime | | CompletionSource | string \| string[] — key into completers or inline values |

Design

The generators use data injection: command definitions are compiled into shell lookup tables (bash associative arrays, fish arrays, zsh _arguments specs), and the completion logic is static shell code that reads from those tables at runtime. This keeps the generated scripts simple and debuggable.

CompletionConfig.names controls all identifier prefixes in the generated scripts, so multiple CLIs can coexist without collisions.