Shell Completion Scripts

Note: The completion scripts are embedded in the compiled backlog binary. These files serve as reference documentation and are used during development (the CLI reads them first if available, otherwise uses the embedded versions).

Available Shells

Zsh

File: _backlog

Installation:

1. Automatic (recommended):

   backlog completion install --shell zsh
   

2. Manual:

   # Copy to a directory in your $fpath
   sudo cp _backlog /usr/local/share/zsh/site-functions/_backlog
   
   # Or add to your custom completions directory
   mkdir -p ~/.zsh/completions
   cp _backlog ~/.zsh/completions/_backlog
   
   # Add to ~/.zshrc if not already present:
   fpath=(~/.zsh/completions $fpath)
   autoload -Uz compinit && compinit
   

3. Testing without installation:

   # In your current zsh session
   fpath=(./completions $fpath)
   autoload -Uz compinit && compinit
   

Verification:

# Type and press TAB
backlog <TAB>
backlog task <TAB>

Bash

File: backlog.bash

Installation:

1. Automatic (recommended):

   backlog completion install --shell bash
   

2. Manual:

   # Copy to bash-completion directory
   sudo cp backlog.bash /etc/bash_completion.d/backlog
   
   # Or source in ~/.bashrc
   echo "source /path/to/backlog.bash" >> ~/.bashrc
   source ~/.bashrc
   

3. Testing without installation:

   # In your current bash session
   source ./completions/backlog.bash
   

Verification:

# Type and press TAB
backlog <TAB>
backlog task <TAB>

Fish

File: backlog.fish

Installation:

1. Automatic (recommended):

   backlog completion install --shell fish
   

2. Manual:

   # Copy to fish completions directory
   cp backlog.fish ~/.config/fish/completions/backlog.fish
   
   # Completions are automatically loaded in new fish sessions
   

3. Testing without installation:

   # In your current fish session
   source ./completions/backlog.fish
   

Verification:

# Type and press TAB
backlog <TAB>
backlog task <TAB>

How It Works

All completion scripts use the same backend:

1. The shell calls the completion function when TAB is pressed
2. The completion function invokes backlog completion __complete "$BUFFER" "$CURSOR"
3. The CLI returns a newline-separated list of completions
4. The shell presents these completions to the user

This architecture provides:

• Dynamic completions: Task IDs, labels, statuses are read from actual data
• Consistent behavior: All shells use the same completion logic
• Easy maintenance: Update completion logic once in TypeScript
• Embedded scripts: Scripts are built into the binary, no external files needed

Development

Testing Completions

Zsh:

# Run automated tests
zsh _backlog.test.zsh

# Or manually verify
zsh
source _backlog
which _backlog

Bash:

# Manually verify
bash
source backlog.bash
complete -p backlog

Fish:

# Run automated tests
fish backlog.test.fish

# Or manually verify
fish
source backlog.fish
complete -C'backlog '

Adding New Completions

Completions are generated by:

• /src/completions/helper.ts - Main completion logic
• /src/completions/command-structure.ts - Command parsing
• /src/completions/data-providers.ts - Dynamic data (task IDs, labels, etc.)
• /src/commands/completion.ts - Embedded shell scripts in getEmbeddedCompletionScript()

To update completion scripts:

1. Edit the embedded scripts in /src/commands/completion.ts
2. (Optional) Update the reference files in /completions/ for documentation
3. Rebuild: bun run build

Requirements

• Zsh: Version 5.x or higher
• Bash: Version 4.x or higher
• Fish: Version 3.x or higher

Troubleshooting

Completions not working

1. Verify the CLI is in your PATH:

   which backlog
   

2. Check completion function is loaded:

   # Zsh
   which _backlog
   
   # Bash
   complete -p backlog
   
   # Fish
   complete -C'backlog '
   

3. Test the completion backend directly:

   backlog completion __complete "backlog task " 13
   

   This should output available subcommands for backlog task.

4. Reload your shell configuration:

   # Zsh
   exec zsh
   
   # Bash
   exec bash
   
   # Fish
   exec fish
   

Slow completions

If completions feel slow, it may be because:

• Large number of tasks/documents in your backlog
• Network latency (if applicable)
• First completion triggers CLI initialization

The completion system is designed to be fast, but with very large datasets you may notice a slight delay.

Contributing

When adding new completion features:

1. Update the backend in /src/completions/
2. Test with backlog completion __complete
3. Verify each shell script still works
4. Update this README if behavior changes