microsoft / microsoft/aspire

[CLI] Add shell completions and configure them during installation

Open
#20,000 2 comments 0 reactions 0 assignees View on GitHub
area-cli enhancement triage:bot-seen
Dominant language
C#
Stars
6.3k
Forks
991
Avg merge
2d 15h
Merged PRs (30d)
196

Description

More information on our issue management policies can be found here: https://aka.ms/aspnet/issue-policies

### Is there an existing issue for this?

- [x] I have searched the existing issues

### Is your feature request related to a problem? Please describe the problem.

The `aspire` CLI should support shell tab completion so users can discover and enter commands, subcommands, options, and supported argument/option values without repeatedly consulting help. Where possible, installing the CLI should also enable completions rather than require a separate manual setup step.

### Describe the solution you'd like

Add built-in shell completion support similar to [the CLI repo template's shell completion support](https://github.com/DamianEdwards/cli-repo-template#shell-completion).

**Completion support**

- Support Bash, Zsh, Fish, and PowerShell (`pwsh`).
- Provide a command that emits a completion script for a selected shell, for example `aspire completions script [bash|fish|pwsh|zsh]`. Consider detecting the current shell when no shell is specified, following the reference implementation.
- Have shell hooks query the CLI's command model for completions, keeping suggestions aligned with available commands, options, and completion-enabled values. The reference uses `System.CommandLine`'s `[suggest:]` support without requiring `dotnet-suggest` or another separately installed helper.
- Keep completion requests fast and side-effect-free; pressing Tab should not start an AppHost or perform normal command execution.
- Provide documented manual setup for each supported shell, including how to enable completions in the current session and persist them for future sessions.

**Installation integration**

Update installation mechanisms to configure completions automatically on first install wherever this is supported and appropriate:

| Installation mechanism | Proposed work |
| --- | --- |
| Custom shell/PowerShell install scripts | Generate/install the appropriate completion script and register it through the shell's standard completion location or a profile entry. |
| WinGet | Investigate supported installer/package integration and whether completions can be configured reliably in the installing user's shell context. Implement automatic setup if supported. |
| npm | Investigate package lifecycle and shell-integration options, including global versus local installs and installations with lifecycle scripts disabled. Implement automatic setup where reliable. |
| .NET tools | Investigate supported integration for global/local tool installs and whether automatic registration is possible. Implement it where supported. |

Do not assume every package manager exposes a suitable post-install hook or can safely modify a user's shell profile. Where automatic setup is unavailable, provide clear manual instructions and, where feasible, surface them at installation time.

Automatic setup should be idempotent across reinstalls/upgrades, preserve existing profile content, handle paths containing spaces and shell quoting correctly, and offer an opt-out for scripted or managed installations. Document when a new shell or explicitly sourcing the script is needed, and how to remove the registration. Ensure installed completion scripts remain compatible as the CLI is updated.

Include focused coverage for script generation, completion behavior, and installer registration, including repeated installation and shell-profile handling.

### Additional context

Reference: https://github.com/DamianEdwards/cli-repo-template#shell-completion

The reference emits standalone shell integration scripts, has those scripts query the CLI for suggestions, and configures completion automatically in its custom installers by placing a script alongside the binary and adding shell-profile integration. It also documents manual setup for Bash, Zsh, Fish, and PowerShell. `cmd.exe` is outside the supported shell set in that implementation.

The WinGet, npm, and .NET tool integration details above are investigation items, not claims that these installation mechanisms support automatic registration today.

Contributor guide

Open the contributing guide

Research direction

No repository files or tests are named. Start by reading the referenced CLI repo template, then locate Aspire's CLI command model and custom installer entry points. Done means supported completion scripts, focused generation and installer tests, documented manual setup, and reliable handling of registration, upgrades, and opt-out behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
bash, csharp, fish, powershell, zsh
Domain
cli, documentation, release, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.