Shell Completion

pok generates shell completion scripts for bash, zsh, and fish. The completion command returns command names, subcommands, flags, and enum or boolean flag values for the current argument position.

Installation

Generate and install the completion script for your shell:

Bash

Add to your ~/.bashrc or ~/.bash_profile:

source <(mycli completion bash)

Then reload your shell:

source ~/.bashrc

Zsh

Add to your ~/.zshrc:

source <(mycli completion zsh)

Then reload your shell:

source ~/.zshrc

Fish

Run once to install:

mycli completion fish > ~/.config/fish/completions/mycli.fish

Interactive use

Once installed, press Tab to complete:

# Complete commands
mycli d<Tab>
# → deploy, dev, db

# Complete subcommands
mycli db <Tab>
# → migrate, seed, reset

# Complete flags
mycli deploy --<Tab>
# → --env, --dry-run, --help

# Complete flag values (for enums)
mycli deploy --env <Tab>
# → dev, staging, prod

Completion protocol

pok uses a hidden __complete command to generate completions dynamically. When you press Tab, your shell calls:

mycli __complete <current-args>

The CLI returns matching completions from:

  1. Commands: available commands at the current level.
  2. Aliases: command aliases defined on the current command.
  3. Flags: context flags defined on the command.
  4. Flag values: enum choices and boolean values.

Completion surfaces

Command Completions

Top-level and nested commands are completed:

mycli <Tab>          # Shows: build, deploy, db, dev
mycli db <Tab>       # Shows: migrate, seed, reset, all

Alias Completions

Command aliases appear alongside command names:

// commands/deploy.ts
export const command = defineCommand({
  label: 'Deploy to environment',
  aliases: ['d', 'dep'],
  // ...
});
mycli <Tab>  # Shows: deploy, d, dep, build, ...

Flag Completions

Flags are completed when typing --:

mycli deploy --<Tab>  # Shows: --env, --dry-run, --verbose

Flag Value Completions

For enum and boolean flags, possible values are suggested:

context: {
  env: {
    from: 'flag',
    schema: z.enum(['dev', 'staging', 'prod']),
  },
  dryRun: {
    from: 'flag',
    schema: z.boolean().default(false),
  },
}
mycli deploy --env <Tab>      # Shows: dev, staging, prod
mycli deploy --dry-run <Tab>  # Shows: true, false

Explicit Choices

You can provide explicit choices that override schema inference:

context: {
  region: {
    from: 'flag',
    schema: z.string(),
    choices: ['us-east-1', 'us-west-2', 'eu-west-1'],
  },
}

Detecting the Current Shell

pok can detect your shell from the $SHELL environment variable:

import { detectShell } from '@pokit/core';

const shell = detectShell(); // 'bash' | 'zsh' | 'fish'

Programmatic Script Generation

You can generate completion scripts programmatically:

import { generateCompletionScript } from '@pokit/core';

const bashScript = generateCompletionScript('mycli', 'bash');
const zshScript = generateCompletionScript('mycli', 'zsh');
const fishScript = generateCompletionScript('mycli', 'fish');

Troubleshooting

Completions not working

  1. Ensure the completion script is sourced in your shell config
  2. Open a new terminal or reload your shell config
  3. Verify with: type _mycli_completions (bash) or which _mycli (zsh)

Stale completions

Completions are generated dynamically, so they always reflect the current command structure. If completions seem stale, try:

# Reload shell config
source ~/.bashrc  # or ~/.zshrc

Fish completions not updating

For fish, regenerate the completions file:

mycli completion fish > ~/.config/fish/completions/mycli.fish
PreviousCommand HistoryNextTesting