[GH-ISSUE #37] Add dynamic shell completion to the aenv CLI

bsakaguchi commented

2026-10-29 14:18:24 +00:00

Owner

Originally created by @LSX-s-Software on GitHub (Jul 28, 2026).
Original GitHub issue: https://github.com/kvcache-ai/AgentENV/issues/37

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.

Originally created by @LSX-s-Software on GitHub (Jul 28, 2026). Original GitHub issue: https://github.com/kvcache-ai/AgentENV/issues/37 ## 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: ```bash 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: ```bash 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: ```bash 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.

bsakaguchi

2026-10-29 14:18:24 +00:00

closed this issue
added the
enhancement
label

bsakaguchi commented

2026-10-29 14:18:25 +00:00

Author

Owner

@rbalachandar commented on GitHub (Jul 30, 2026):

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.

@rbalachandar commented on GitHub (Jul 30, 2026): 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.

bsakaguchi commented

2026-10-29 14:18:25 +00:00

Author

Owner

@NickNYU commented on GitHub (Aug 4, 2026):

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?

@NickNYU commented on GitHub (Aug 4, 2026): 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?

bsakaguchi commented

2026-10-29 14:18:26 +00:00

Author

Owner

@LSX-s-Software commented on GitHub (Aug 6, 2026):

@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.

@LSX-s-Software commented on GitHub (Aug 6, 2026): @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.

bsakaguchi commented

2026-10-29 14:18:26 +00:00

Author

Owner

@NickNYU commented on GitHub (Aug 11, 2026):

@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:

Reuse the existing /v2/sandboxes API. (No new API is introduced)
Filter candidates by the command's valid sandbox state.
Filter by the prefix currently typed by the user.
Return a machine-readable candidate format, optionally including descriptions such as alias/template and state.
Use a completion-specific short timeout.
Fail silently with no candidates when credentials, the server, or the network are unavailable.
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 commented on GitHub (Aug 11, 2026): @LSX-s-Software Thanks for the clarification. I reviewed the current CLI implementation, [PR #89](https://github.com/kvcache-ai/AgentENV/pull/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: ```shell 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

bsakaguchi commented

2026-10-29 14:18:26 +00:00

Author

Owner

@NickNYU commented on GitHub (Aug 12, 2026):

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

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.
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.

@NickNYU commented on GitHub (Aug 12, 2026): 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](https://github.com/kvcache-ai/AgentENV/pull/163) - 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`](https://github.com/kvcache-ai/AgentENV/pull/164) - 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.

bsakaguchi commented

2026-10-29 14:18:26 +00:00

Author

Owner

@LSX-s-Software commented on GitHub (Aug 22, 2026):

This issue is not yet completed. We should at least add back the document removed by c890d29 or implement auto installation.

@LSX-s-Software commented on GitHub (Aug 22, 2026): This issue is not yet completed. We should at least add back the document removed by c890d29 or implement auto installation.

bsakaguchi commented

2026-10-29 14:18:26 +00:00

Author

Owner

@NickNYU commented on GitHub (Sep 3, 2026):

Hi
As the issue has been opened for several days, I try to summarize things and see if it fits the fact:

Where things stand

Static scaffolding — #89 (merged).
Dynamic sandbox-ID completion — #163 (merged): CompleteEnv + ArgValueCandidates, wired into connect / exec / upload / download / pause / resume / delete / timeout / snapshot create.
The documentation removed by c890d29 — restored in #231 (merged 2026-08-30). docs/src/getting-started/aenv-cli.md again covers aenv completion , the per-shell install locations, and source <(aenv completion bash)-style manual activation.

What might be the Next

as @LSX-s-Software has mentioned previously in 08-22's note: "at least the document back, or auto installation", it might be good to do

Auto installation of completion loaders (make install-aenv, scripts/install-cli.sh, scripts/install.sh, plus removal from make uninstall-aenv). None of these touch completion today. #115 covered exactly this, but it was closed on 08-28 without review — Hi @rbalachandar, are you still planning to merge it, so that we don't need to duplicate the work
Template / snapshot name completion for aenv start <target>, aenv template watch, aenv template delete, including the start --cold OCI-reference exception.

Proposal

I'd like to pick up (1) if no one is trying to do it

One loader per shell in the standard directories, with no shell-rc edits:
- bash: /share/bash-completion/completions/aenv (user-local: ~/.local/share/...)
- zsh: /share/zsh/site-functions/_aenv
- fish: /share/fish/vendor_completions.d/aenv.fish (user-local: ~/.config/fish/completions/aenv.fish)
The loader is a small shim that regenerates the registration from the installed binary at shell start / first completion, so a CLI upgrade can't leave a stale cached script behind — matching this issue's "generate registration code from the installed aenv binary when a shell starts".
Only ever write or remove files we own (marker line): pre-existing unmanaged files and symlinks are left untouched, and any failure degrades to a warning rather than aborting the CLI install.
make uninstall-aenv removes only managed loaders.
For user-local installs, print actionable zsh fpath / compinit guidance instead of editing .zshrc.
Tests: a shellcheck-clean script covering install, managed upgrade, unmanaged-file preservation, symlink preservation, user vs system mode, and uninstall.

Waiting for your news, thanks!

@NickNYU commented on GitHub (Sep 3, 2026): Hi As the issue has been opened for several days, I try to summarize things and see if it fits the fact: ### Where things stand - Static scaffolding — #89 (merged). - Dynamic sandbox-ID completion — #163 (merged): CompleteEnv + ArgValueCandidates, wired into connect / exec / upload / download / pause / resume / delete / timeout / snapshot create. - The documentation removed by c890d29 — restored in #231 (merged 2026-08-30). docs/src/getting-started/aenv-cli.md again covers aenv completion <shell>, the per-shell install locations, and source <(aenv completion bash)-style manual activation. ### What might be the **Next** as @LSX-s-Software has mentioned previously in 08-22's note: "at least the document back, or auto installation", it might be good to do 1. Auto installation of completion loaders (`make install-aenv`, `scripts/install-cli.sh`, `scripts/install.sh`, plus removal from `make uninstall-aenv`). None of these touch completion today. #115 covered exactly this, but it was closed on 08-28 without review — Hi @rbalachandar, are you still planning to merge it, so that we don't need to duplicate the work 2. Template / snapshot name completion for `aenv start <target>`, `aenv template watch`, `aenv template delete`, including the `start --cold` OCI-reference exception. ### Proposal I'd like to pick up (1) if no one is trying to do it - One loader per shell in the standard directories, with no shell-rc edits: - bash: <prefix>/share/bash-completion/completions/aenv (user-local: ~/.local/share/...) - zsh: <prefix>/share/zsh/site-functions/_aenv - fish: <prefix>/share/fish/vendor_completions.d/aenv.fish (user-local: ~/.config/fish/completions/aenv.fish) - The loader is a small shim that regenerates the registration from the installed binary at shell start / first completion, so a CLI upgrade can't leave a stale cached script behind — matching this issue's "generate registration code from the installed aenv binary when a shell starts". - Only ever write or remove files we own (marker line): pre-existing unmanaged files and symlinks are left untouched, and any failure degrades to a warning rather than aborting the CLI install. - make uninstall-aenv removes only managed loaders. - For user-local installs, print actionable zsh fpath / compinit guidance instead of editing .zshrc. - Tests: a shellcheck-clean script covering install, managed upgrade, unmanaged-file preservation, symlink preservation, user vs system mode, and uninstall. Waiting for your news, thanks!

bsakaguchi commented

2026-10-29 14:18:27 +00:00

Author

Owner

@rbalachandar commented on GitHub (Sep 3, 2026):

as @LSX-s-Software has mentioned previously in 08-22's note: "at least the document back, or auto installation", it might be good to do

Auto installation of completion loaders (make install-aenv, scripts/install-cli.sh, scripts/install.sh, plus removal from make uninstall-aenv). None of these touch completion today. feat(cli): install shell completion loaders #115 covered exactly this, but it was closed on 08-28 without review — Hi @rbalachandar, are you still planning to merge it, so that we don't need to duplicate the work

Thought different approach was taken. I can reopen the PR if the approach sounds good.

@rbalachandar commented on GitHub (Sep 3, 2026): > as [@LSX-s-Software](https://github.com/LSX-s-Software) has mentioned previously in 08-22's note: "at least the document back, or auto installation", it might be good to do > > 1. Auto installation of completion loaders (`make install-aenv`, `scripts/install-cli.sh`, `scripts/install.sh`, plus removal from `make uninstall-aenv`). None of these touch completion today. [feat(cli): install shell completion loaders #115](https://github.com/kvcache-ai/AgentENV/pull/115) covered exactly this, but it was closed on 08-28 without review — Hi [@rbalachandar](https://github.com/rbalachandar), are you still planning to merge it, so that we don't need to duplicate the work Thought different approach was taken. I can reopen the PR if the approach sounds good.

bsakaguchi commented

2026-10-29 14:18:27 +00:00

Author

Owner

@NickNYU commented on GitHub (Sep 4, 2026):

Hi @rbalachandar, thanks for the reply! Yes, #115's approach (auto-install loaders, no shell-rc edits, only touch managed files) still matches what this issue needs — what merged later (#163, dynamic completion via the COMPLETE= callback) is on a different layer and shouldn't conflict. Please go ahead and reopen #115, and I'm happy to review it against current main.

Then I'll take the remaining slice: template/snapshot name completion for aenv start <target>, aenv template watch, aenv template delete, with the start --cold OCI-reference exception.

@LSX-s-Software does this split sound good?

@NickNYU commented on GitHub (Sep 4, 2026): Hi @rbalachandar, thanks for the reply! Yes, #115's approach (auto-install loaders, no shell-rc edits, only touch managed files) still matches what this issue needs — what merged later (#163, dynamic completion via the `COMPLETE=` callback) is on a different layer and shouldn't conflict. Please go ahead and reopen #115, and I'm happy to review it against current main. Then I'll take the remaining slice: template/snapshot name completion for `aenv start <target>`, `aenv template watch`, `aenv template delete`, with the `start --cold` OCI-reference exception. @LSX-s-Software does this split sound good?

bsakaguchi commented

2026-10-29 14:18:27 +00:00

Author

Owner

@NickNYU commented on GitHub (Sep 6, 2026):

Hi, an update on the remaining dynamic-completion part.

I've implemented (2) — template / snapshot name completion — and opened #250. What's in it:

aenv start <TAB> completes template and snapshot names, then IDs as a fallback.
aenv template watch / aenv template delete complete template names, then IDs.
aenv start --cold <TAB> offers nothing, since the target is an OCI image reference. It returns before any credential or network access, so a cold start costs no API call.
Descriptions distinguish templates from snapshots and carry the ID plus build status.
Reuses /v2/templates and /snapshots; no new server API, and the same short timeouts and silent-failure behavior as #163.

Two small things I ran into and fixed along the way:

snapshot list --sandbox-id had no sandbox completion, although it's listed in this issue under the sandbox states table.
The docs said sandbox candidates carry a template/state description, but no description was actually attached. It's real now — sandbox IDs are UUIDs, so the description is what tells two candidates apart.

@rbalachandar — for (1), please go ahead and reopen #115 whenever you like, it doesn't conflict with this PR. I'm happy to review it.

That would leave this issue fully covered: static scaffolding (#89), dynamic sandbox IDs (#163), docs (#231), template/snapshot names (#250), auto installation (#115).

@NickNYU commented on GitHub (Sep 6, 2026): Hi, an update on the remaining dynamic-completion part. I've implemented (2) — template / snapshot name completion — and opened #250. What's in it: - `aenv start <TAB>` completes template and snapshot names, then IDs as a fallback. - `aenv template watch` / `aenv template delete` complete template names, then IDs. - `aenv start --cold <TAB>` offers nothing, since the target is an OCI image reference. It returns before any credential or network access, so a cold start costs no API call. - Descriptions distinguish templates from snapshots and carry the ID plus build status. - Reuses `/v2/templates` and `/snapshots`; no new server API, and the same short timeouts and silent-failure behavior as #163. Two small things I ran into and fixed along the way: - `snapshot list --sandbox-id` had no sandbox completion, although it's listed in this issue under the sandbox states table. - The docs said sandbox candidates carry a template/state description, but no description was actually attached. It's real now — sandbox IDs are UUIDs, so the description is what tells two candidates apart. @rbalachandar — for (1), please go ahead and reopen #115 whenever you like, it doesn't conflict with this PR. I'm happy to review it. That would leave this issue fully covered: static scaffolding (#89), dynamic sandbox IDs (#163), docs (#231), template/snapshot names (#250), auto installation (#115).

bsakaguchi referenced this issue

2026-10-29 14:19:55 +00:00

[PR #17] [MERGED] Optimize Docker cache for GitHub-hosted runners #120

Rows
Columns

[GH-ISSUE #37] Add dynamic shell completion to the aenv CLI #17

Summary

Motivation

Proposed interface

Dynamic resource completion

Sandboxes

Templates and snapshots

Failure and performance behavior

Installation

Documentation

Acceptance criteria

Non-goals

Meaningful

Dynamic sandbox-ID completion

Possible implementation approaches

Option A: Use Clap's dynamic completion support

Option B: Add an AgentENV-owned internal completion hook

Summary

Where things stand

What might be the Next

Proposal