Add dynamic shell completion to the aenv CLI

[LSX-s-Software]

Summary

Add first-class shell completion support to the native aenv CLI for Bash, Zsh, and Fish.

In addition to completing commands and flags, the CLI should dynamically complete AgentENV resources such as sandbox IDs and template/snapshot names.

Motivation

The CLI contains nested commands, aliases, and resource identifiers that are difficult to enter manually:

aenv snapshot create <sandbox-id>
aenv template watch <template>
aenv resume <sandbox-id>

Sandbox IDs are UUIDs, while templates and snapshots may be referenced by either names or IDs. As the number of resources grows, users currently need to run a list command, copy a value, and paste it into the next command.

Shell completion would make interactive CLI use faster and reduce invalid commands caused by stale or mistyped identifiers.

Proposed interface

Add a command that emits completion registration code:

aenv completion bash
aenv completion zsh
aenv completion fish

The generated registration should call back into the current aenv binary when completion is requested, allowing it to provide both static and dynamic candidates.

Static completion should cover:

• top-level and nested subcommands;
• command aliases such as ls, rm, cn, and snap;
• flags and option values;
• enum values such as --output table|json;
• local paths such as the Dockerfile argument to aenv build.

Dynamic resource completion

Sandboxes

Commands accepting a sandbox ID should query the sandbox list and filter candidates by the states accepted by the command:

• pause, exec, timeout, and snapshot create: running sandboxes;
• resume: paused sandboxes;
• connect, delete, and snapshot list --sandbox-id: running and paused sandboxes.

The inserted value should be the sandbox ID. When supported by the shell, the candidate description should include the sandbox's template and state.

Templates and snapshots

Commands accepting a template or snapshot should complete human-readable names or aliases first, with IDs available as fallback candidates:

• aenv start <target>;
• aenv template watch <template>;
• aenv template delete <template>.

aenv start --cold should not query template or snapshot candidates because its target is an OCI image reference.

Candidate descriptions should distinguish templates from snapshots and include the underlying ID and build status where available.

Failure and performance behavior

Dynamic completion is an interactive, best-effort feature and must not make the shell feel blocked.

• Use short connection and request timeouts.
• Limit and deduplicate returned candidates.
• Filter candidates by the prefix already entered.
• If credentials are missing, the server is unavailable, or a request times out, silently return no dynamic candidates.
• Static command and flag completion must continue to work when dynamic lookup fails.
• Completion must not print diagnostic errors into the user's command line.

Installation

The existing installation paths should install lightweight completion loaders for Bash, Zsh, and Fish:

• make install-aenv;
• scripts/install-cli.sh;
• the full AgentENV installer.

The loaders should generate registration code from the installed aenv binary when a shell starts, so CLI upgrades do not leave incompatible cached completion scripts behind.

Installers should use standard completion directories and must not modify .bashrc, .zshrc, or Fish configuration files automatically. If additional shell configuration is required, the installer should print an actionable message.

make uninstall-aenv should remove the installed completion loaders.

Documentation

Document automatic installation and manual activation:

source <(aenv completion bash)
source <(aenv completion zsh)
aenv completion fish | source

Acceptance criteria

• Bash, Zsh, and Fish complete all current aenv commands, aliases, flags, and enum values.
• Sandbox arguments are dynamically completed and filtered according to command-compatible states.
• Template and snapshot names are completed for commands that accept them.
• aenv start --cold does not return template or snapshot candidates.
• Completion remains responsive and silent when authentication or the AgentENV server is unavailable.
• Source builds and release installers install completion loaders without editing users' shell configuration.
• CLI and installer tests cover script generation, candidate filtering, failure fallback, installation, upgrades, and removal.

Non-goals

• PowerShell and Elvish support in the initial version.
• Server-side API changes specifically for completion.
• Persistent cross-process completion caches.
• Automatically editing users' shell startup files.

[rbalachandar]

Step 1 (static completion scaffolding — commands, aliases, flags, the --output enum, and path arguments) is up in #89. This note is about step 2: dynamic resource completion (sandbox IDs filtered by command-applicable state, template/snapshot names, and the start --cold OCI-ref exception).

One mechanism decision before starting it: clap_complete's dynamic completion is gated behind its unstable-dynamic feature (and requires clap/unstable-ext) as of 4.6.x, so it's explicitly unstable. The realistic options are:

• adopt clap_complete's dynamic API — least code, but an unstable surface that may shift between clap releases, or
• a small hand-rolled aenv __complete callback that the generated scripts invoke — a bit more code, but stable and self-contained.

I'd lean toward the hand-rolled callback to avoid pinning the CLI to an unstable clap feature, but happy to go either way.

[NickNYU]

Hi
I’d like to contribute to this issue.

After reviewing the current aenv command tree, I’m interested in taking the
sandbox-ID dynamic completion subtask for:

• connect
• exec
• upload
• download
• pause
• resume
• delete
• timeout
• snapshot create
• snapshot list --sandbox-id

The scope would be querying the configured AgentENV API for available
sandboxes, completing sandbox IDs (optionally with state/alias descriptions),
handling API/auth errors gracefully, and adding focused tests.

Is this part still unclaimed, and does it fit the completion design currently
being implemented?

[LSX-s-Software]

@NickNYU Thanks for your interest in working on this!

You’re welcome to take a stab at it and open a PR. It would be great if you could briefly outline your approach here before implementing, just to make sure we’re aligned on the direction.

Let us know if you run into any questions along the way.

[NickNYU]

@LSX-s-Software Thanks for the clarification. I reviewed the current CLI implementation, PR #89， and a few related industry approaches such as Docker and K8S(kubectl) completion.

My understanding is (please correct me if I'm wrong) that PR #89 already provides the static completion foundation for commands by leveraging the clap framework.

Meaningful

The remaining useful part of this issue is dynamic completion of runtime resources.

I would like to propose taking the following first slice:

Dynamic sandbox-ID completion

Commands and arguments:

• aenv connect <sandbox-id>
• aenv exec <sandbox-id> ...
• aenv upload <sandbox-id> ...
• aenv download <sandbox-id> ...
• aenv pause <sandbox-id>
• aenv resume <sandbox-id>
• aenv delete <sandbox-id>
• aenv timeout <sandbox-id> ...
• aenv snapshot create <sandbox-id>
• aenv snapshot list --sandbox-id <sandbox-id>

The proposed implementation would:

1. Reuse the existing /v2/sandboxes API. (No new API is introduced)
2. Filter candidates by the command's valid sandbox state.
3. Filter by the prefix currently typed by the user.
4. Return a machine-readable candidate format, optionally including descriptions such as alias/template and state.
5. Use a completion-specific short timeout.
6. Fail silently with no candidates when credentials, the server, or the network are unavailable.
7. Avoid adding a new server API.

Possible implementation approaches

Option A: Use Clap's dynamic completion support

Use clap_complete's unstable-dynamic APIs, such as CompleteEnv, ArgValueCandidates, or ArgValueCompleter.

Pros:

• More integrated with the existing Clap/clap_complete design.
• Less shell-specific completion glue code.
• Dynamic argument completion can be declared close to the relevant CLI argument.

Cons:

• The API is currently marked unstable-dynamic.
• The generated shell script and binary communicate through an unstable interface.
• Version mismatches between the generated script and CLI may cause completion failures.
• We would need to follow the framework's completion protocol and lifecycle.

Option B: Add an AgentENV-owned internal completion hook

Add an internal command or protocol such as:

 aenv __complete ...

The generated Bash/Zsh/Fish scripts would invoke it only at supported sandbox-ID argument positions.

Pros:

• Keeps the dynamic protocol under AgentENV's control.
• Allows custom short timeouts and silent failure behavior.
• Keeps authentication, API access, JSON parsing, and filtering in Rust.
• Easier to test independently from shell-specific scripts.
• Does not depend on Clap's unstable dynamic-completion API.

Cons:

• Requires a small amount of shell-specific integration.
• Requires us to define and maintain an internal completion protocol.
• The generated static scripts may need customization or a post-generation hook.

Summary

Both options should reuse the existing CLI client and /v2/sandboxes endpoint. No new server-side completion API should be needed.

I would intentionally leave the following for later follow-up work:

• template-name and template-ID completion;
• snapshot-name and snapshot-ID completion;
• installer or shell startup-file integration;
• persistent completion caching;
• changes to the AgentENV server API.

The first implementation would include focused tests for command/argument recognition, state filtering, prefix filtering, stable ordering, successful API lookup, and silent failure behavior.

Would maintainers and other contributors be willing to weigh in on Option A vs. Option B, and whether this sandbox-ID-only scope is appropriate for the first slice?

Thanks

[NickNYU]

I implemented the two proposed approaches as separate experimental PRs so we can compare them without conflating the designs:

1. PR #163 — clap_complete unstable-dynamic

   • Uses CompleteEnv and ArgValueCandidates.
   • Dynamic sandbox IDs come from the existing sandbox list API.
   • Short timeouts and silent failure keep completion non-blocking.
   • Lower AgentENV maintenance cost, but depends on clap_complete’s unstable dynamic shell protocol.

2. PR #164 — AgentENV-owned aenv __complete

   • Keeps the static generator and appends Bash/Zsh/Fish adapters.
   • Adapters call aenv __complete --index ... -- <words...>.
   • The protocol and cursor interpretation are owned by AgentENV, but we maintain three shell adapters.

These PRs are intentionally alternatives, not additions to merge together. Please review the API/maintenance trade-off and let me know which direction is preferable for #37. The existing static aenv completion <shell> behavior is preserved in both branches.