Add bash-completion support for improved CLI UX

[rholmboe]

Problem

The phabfive CLI currently lacks shell completion support, which makes the tool less efficient to use, especially given its rich command structure with multiple subcommands, numerous options, and monogram shortcuts.

Benefits

Adding bash-completion would significantly improve user experience:

• Faster workflows: No need to type full commands or constantly check --help
• Fewer errors: Tab-completion prevents typos in command names and options
• Better discoverability: Users can explore available options without leaving the terminal
• Professional polish: Most modern CLI tools support shell completion

Scope

Commands to Complete

Main commands:

• passphrase, diffusion, maniphest, paste, repl, user

Monogram shortcuts:

• K<number> (Passphrase secret)
• P<number> (Paste text)
• R<number> (Diffusion repo)
• T<number> (Maniphest task)

Subcommands to Complete

maniphest:

• show, create, search, comment

diffusion:

• repo list, repo create
• uri list, uri create, uri edit
• branch list

paste:

• list, create, show

user:

• whoami, setup

Options to Complete

Global options:

• --log-level=LEVEL (completable levels)
• --format=FORMAT (rich, tree, strict)
• --ascii=WHEN (always, auto, never)
• --hyperlink=WHEN (always, auto, never)
• -h, --help, -V, --version

Command-specific options:

• maniphest create: --with=TEMPLATE (template names from templates/task-create/)
• diffusion: -u/--url, -c/--clone, -n/--new-uri, -i/--io, -d/--display, -c/--cred
• paste: -t/--tags, -s/--subscribers

Arguments to Complete (Dynamic)

Where applicable, dynamic completion would be valuable:

• Repository names/callsigns (e.g., for diffusion commands)
• Project names (e.g., for maniphest search <project_name>)
• Task IDs (e.g., for maniphest show T123)
• Template names (e.g., for maniphest create --with=TEMPLATE)
• Credential IDs (e.g., for diffusion uri edit -c K123)

Technical Approaches

Option 1: Built-in completion command (Recommended)

Add a phabfive completion subcommand that generates completion scripts:

# Generate bash completion
phabfive completion bash > /etc/bash_completion.d/phabfive
# or
phabfive completion bash > ~/.local/share/bash-completion/completions/phabfive

# Generate zsh completion
phabfive completion zsh > "${fpath[1]}/_phabfive"

Advantages:

• Single source of truth
• Easy to update
• Can support multiple shells (bash, zsh, fish)
• Can integrate dynamic completions via API calls

Libraries to consider:

• shtab - generates shell completion from argparse
• Custom implementation using docopt-ng's parsed structure

Option 2: Static completion script

Provide a pre-generated completion script in the repository:

# Install instructions in README
source /path/to/phabfive/contrib/completion.bash

Advantages:

• Simpler implementation
• No runtime dependency
• Easy to distribute via package managers

Disadvantages:

• Requires manual updates when CLI changes
• No dynamic completions

Option 3: Package manager integration

Integrate with package managers to auto-install completions:

Homebrew:

# in formula
bash_completion "#{prefix}/completions/phabfive.bash"

pip/setuptools:

# in setup.py or pyproject.toml
package_data={'': ['completions/*']}

Implementation Priorities

Phase 1: Basic completion (MVP)

• Static completion for main commands
• Static completion for subcommands
• Static completion for global options
• Document shell completion in README #158

Phase 2: Enhanced completion

• Static completion for command-specific options
• Completion for option values (e.g., --format={rich,tree,yaml,json}) #157
• Template name completion (read from templates/ directory)

Phase 3: Dynamic completion (Advanced)

• Dynamic repository name completion (via API)
• Dynamic project name completion (via API)
• Dynamic column name completion (via API) -- requires board context #166
• Dynamic status name completion (via API) -- querystatuses() #167
• Dynamic priority name completion (via API) #168
• Dynamic task ID completion (recent tasks)
• Caching for dynamic completions

Inspiration

Similar CLI tools with good completion support:

• gh - GitHub CLI (excellent dynamic completion)
• kubectl - Kubernetes CLI (dynamic resource completion)
• django-admin - Dynamic model/command completion
• click - Python CLI framework with built-in completion

Related

• This would complement the existing repl command for interactive workflows
• Could leverage existing Phabricator API integration for dynamic completions

Questions

• Should we support shells beyond bash? (zsh, fish, powershell)
• Should completion be opt-in (via install flag) or automatic?
• How do we handle completion for authenticated API calls (credentials, permissions)?

---

Note: This issue proposes a significant UX improvement that would make phabfive more competitive with other modern CLI tools. Given the complexity of the command structure (especially for maniphest and diffusion), completion would provide immediate value to users.

[holmboe]

We probably should convert from docopt to click to get shell completion for free. 🤔

[holmboe]

Shell completion for most sensible options and arguments is now implemented:

• PR feat: Add shell completion for all option values #162: Shell completion for all option values (log-level, format, ascii, hyperlink)
• Commit 4e603de: Smart completion for --priority, --status, --column with pattern syntax support

Some further corner case scenarios are being worked on:

• Dynamic column name completion (via API) -- requires board context #166: Dynamic column name completion (requires board context)

Keeping this issue open to track remaining edge cases.