feat(wrangler/cli): add @bomb.sh/tab completions

[AmirSa12]

This PR introduces tab completion functionality for the wrangler cli, improving developer experience by allowing shell(zsh, powershell, fish, bash) autocompletion for commands, options, values, and flags. This also comes with npm, pnpm, yarn and bun copmpletions! ( npm exec ... , pnpm ... ) With this PR, users can navigate available commands, options and values more efficiently and faster with speeding up workflow.

A small video of how this looks:

wrangler.mp4

---

• Tests
  • Tests included
  • Tests not necessary because:
• Public documentation
  • Cloudflare docs PR(s): Add shell tab completion to wrangler cloudflare-docs#27514
  • Documentation not necessary because:

Fixes #53

[changeset-bot]

🦋 Changeset detected

Latest commit: e8a27f9

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[dario-piotrowicz]

Awesome stuff, thanks so much @AmirSa12 🙏

I've left a comment regarding the completions setup, could you take a look? 😄

Also could you advise on how I can manually test this feature? 🙂
(is there a setup required, etc...)

[dario-piotrowicz]

I think that taking the values from the docs and using them here is a bit problematic (as we'd also need to keep them in sync, etc...)

Could you try to instead use the experimental_getWranglerCommands function to dynamically get the information you need and setup the completions from that? 🙂

[AmirSa12]

Hey @dario-piotrowicz ! Thanks for your review!
Yes, I will try to use the experimental_getWranglerCommands and let you know how it works with that!
I'll keep you posted!

[dario-piotrowicz]

Awesome! thanks! 🫶

[AmirSa12]

Awesome stuff, thanks so much @AmirSa12 🙏

I've left a comment regarding the completions setup, could you take a look? 😄

Also could you advise on how I can manually test this feature? 🙂 (is there a setup required, etc...)

Thank you, @dario-piotrowicz!
Yeah sure!
if you want to test the package manager completions, you can simply do that by first, isntalling tab: npm install -g @bomb.sh/tab and then source the script: source <(tab pnpm zsh) ( if you are using pnpm and zsh... npm, bun, and yarn are also supported ) then you can simply have tab completions and do pnpm <TAB>
the above works for your current shell session only, if you want to have that permanently, you would want to add it to ~/.zshrc

on top of this, if you have your own cli, you can have completions for that as well, and if your cli is executed through a package manager, and supports tab completions, lets assume wrangler does, the next example would also work: pnpm wrangler <TAB>

[dario-piotrowicz]

Awesome stuff, thanks so much @AmirSa12 🙏
I've left a comment regarding the completions setup, could you take a look? 😄
Also could you advise on how I can manually test this feature? 🙂 (is there a setup required, etc...)

Thank you, @dario-piotrowicz! Yeah sure! if you want to test the package manager completions, you can simply do that by first, isntalling tab: npm install -g @bomb.sh/tab and then source the script: source <(tab pnpm zsh) ( if you are using pnpm and zsh... npm, bun, and yarn are also supported ) then you can simply have tab completions and do pnpm <TAB> the above works for your current shell session only, if you want to have that permanently, you would want to add it to ~/.zshrc

on top of this, if you have your own cli, you can have completions for that as well, and if your cli is executed through a package manager, and supports tab completions, lets assume wrangler does, the next example would also work: pnpm wrangler <TAB>

Thanks @AmirSa12 😄

So... if I understand correctly for pnpm wrangler <TAB> to work I (and every wrangler user) need to globally install the @bomb.sh/tab package and enable it in my terminal?

[AmirSa12]

Awesome stuff, thanks so much @AmirSa12 🙏
I've left a comment regarding the completions setup, could you take a look? 😄
Also could you advise on how I can manually test this feature? 🙂 (is there a setup required, etc...)

Thank you, @dario-piotrowicz! Yeah sure! if you want to test the package manager completions, you can simply do that by first, isntalling tab: npm install -g @bomb.sh/tab and then source the script: source <(tab pnpm zsh) ( if you are using pnpm and zsh... npm, bun, and yarn are also supported ) then you can simply have tab completions and do pnpm <TAB> the above works for your current shell session only, if you want to have that permanently, you would want to add it to ~/.zshrc
on top of this, if you have your own cli, you can have completions for that as well, and if your cli is executed through a package manager, and supports tab completions, lets assume wrangler does, the next example would also work: pnpm wrangler <TAB>

Thanks @AmirSa12 😄

So... if I understand correctly for pnpm wrangler <TAB> to work I (and every wrangler user) need to globally install the @bomb.sh/tab package and enable it in my terminal?

@dario-piotrowicz, the whole tab package relies on shell scripts.. all the magic happens in the shell, so in-order to have the completions, we need a shell script ( think of it as a plugin ) to inject in our terminal. by installing tab, you are only injecting the shell script, in other ways this means you can directly do source <(npx '@bomb.sh/tab' pnpm zsh) without installing the package globally, but installing the package is recommended because tab completions would be faster that way! let me know if that makes sense to you or if you have feedback or any other questions!
Almost in most of the completion systems, this script injection is required.

[dario-piotrowicz]

dario-piotrowicz, the whole tab package relies on shell scripts.. all the magic happens in the shell, so in-order to have the completions, we need a shell script ( think of it as a plugin ) to inject in our terminal. by installing tab, you are only injecting the shell script, in other ways this means you can directly do source <(npx '@bomb.sh/tab' pnpm zsh) without installing the package globally, but installing the package is recommended because tab completions would be faster that way! let me know if that makes sense to you or if you have feedback or any other questions! Almost in most of the completion systems, this script injection is required.

I see, great! thanks for the clarification 😄🙏

[AmirSa12]

@dario-piotrowicz , I'm amazed by what I could achieve via the experimental_getWranglerCommands ! thank you for suggesting that! this is better now.
FYI NuxtCLI also follows a similar approach here: https://github.com/nuxt/cli/pull/1082/files#diff-985455627f7b91035ad2df15aeb5461a9da8da1305d47ef492654bf0b449c019R3

but one note, I noticed that, by using this function, we are only handling options that have explicit choices defined in the command args (like log-level) some option values (like --port values) are not included. let me know if you want to add common defaults for these common options (like port numbers: 8787, 8080, 3000, or protocols: http, https and ..)

[NuroDev]

Thank you for your contribution @AmirSa12, however we have decided to move forward with #11637 instead as it offers both a bit more in-house control of this feature and a test suite to match.

[AmirSa12]

Hey!
Thanks for checking the PR ❤️

I'd like to add some context and technical details regarding the approaches used in both this PR and #11637
one of the main strengths of bomb.sh/tab is that it provides package manager shell completions, which is something the other PR( #11637 ) approach does not currently address... This approach includes npm, pnpm, yarn and bun support which is a huge win for user experience! (pnpm wrangler <TAB>) and also package.json and fs completions!

On top of this, tab also supports Windows PowerShell... this is a notable advantage as PowerShell support is often missing or incomplete is many completions solutions!

from a quality and reliability standpoint, tests can be added for this PR as well.

tab library provides a simple api for defining completions in your cli tool... which includes commands, options, positional arguments, and custom handlers for dynamic suggestions!
tab also supports framework adapters (CAC, Citty, Commander.js), which makes it easier to integrate with many cli ecosystems.

If this approach is still not desired, I recommend an alternative to be the cli tool wrangler is using (yargs) as it provides completions. however it’s important to note that yargs completion also lacks package manager integration and powershell support.

Additionally, we're happy to add tests or address any missing features or gaps you think tab has as part of this work, so those improvements can be included here and benefit other users as well.

cc @dario-piotrowicz @NuroDev @ascorbic @dmmulroy

wrangler.mp4

[pkg-pr-new]

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@11113

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@11113

miniflare

npm i https://pkg.pr.new/miniflare@11113

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@11113

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@11113

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@11113

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@11113

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@11113

@cloudflare/workers-utils

npm i https://pkg.pr.new/@cloudflare/workers-utils@11113

wrangler

npm i https://pkg.pr.new/wrangler@11113

commit: 8c87c89

[NuroDev]

After discussing this internally and giving it another go I'm pretty happy to merge this.
Just a few small comments + 2 questions for you @AmirSa12:

1. Can we some tests to match #11637
2. Does @bomb.sh/tab not support completions for flags?

[NuroDev]

Is there a way we can instead make this follow the existing command format / structure.
That way we can have the wrangler complete command itself have:

• Auto completion
• Suggestions for shells it supports
• A help menu

We can also reference this code from another PR on how to implement this.

[AmirSa12]

After discussing this internally and giving it another go I'm pretty happy to merge this. Just a few small comments + 2 questions for you @AmirSa12:

Hey @NuroDev! Happy to hear that from you.

1. Can we some tests to match feat(wrangler): add shell completions (bash, zsh, fish) #11637

Sure, I'm adding tests, and also please do let me know if anything else is needed, will take care of that!

2. Does @bomb.sh/tab not support completions for flags?

It does support completions for flags! for more context, please read this comment that I shared with Dario in the current PR. when using the experimental_getWranglerCommands, we will have to add custom handlers for those options/flags, since they dont exist in the experimental_getWranglerCommands.
The approach would be similar to what NuxtCLI is doing(link is there in the comment).
Let me know if you want them, they can be added easily.

[dmmulroy]

@AmirSa12 @NuroDev I'd be in favor of adding that, we can also open another PR to make changes to experimental_getWranglerCommands if that would be a better approach (could follow this work)

[AmirSa12]

@AmirSa12 @NuroDev I'd be in favor of adding that, we can also open another PR to make changes to experimental_getWranglerCommands if that would be a better approach (could follow this work)

Both options work (custom handlers would be fine), but for consistency, especially since flags like log-level already provide value completions, I think updating experimental_getWranglerCommands is a cleaner solution.

[NuroDev]

Hey @AmirSa12!

Sure, I'm adding tests, and also please do let me know if anything else is needed, will take care of that!

Perfect, thank you! I approved a CI run just so we can check all the tests you added worked and look good. There's 2 small code formatting errors that need fixing and that should be it. I'll create a PR to add documentation for this feature that'll fix the CI / Checks workflow.

please read #11113 (comment) that I shared with Dario in the current PR.

Ah, my mistake. I missed that, sorry 😅

Let me know if you want them, they can be added easily.

I agree with @dmmulroy that it would be amazing to get that added so we could also support command flags out the gate. So if you are able to add that please feel free as it would be amazing. But if any issues come up I am more than happy to land this first iteration PR and revisit that in a future PR.

[NuroDev]

Hey @AmirSa12, is there anything else needed on this or do you need any help with anything? Happy to lend a hand to help get this over the line and merged 😄

[Aslemammad]

hey @NuroDev, sorry for the inactivity, we've had some personal issues on the side, i'll look into this and see if i can move it forward!

[Aslemammad]

ok i had a look, i think as you suggested, maybe we can merge this PR and open another PR later that can add more choices to those options not having them or adding custom handlers that handle those options.

It might take more work so splitting it up in another PR might be a quicker and cleaner way to do this. This way when @AmirSa12 is back, he can have a serious look at it too.

Let me know what you think @NuroDev, and again, really sorry for the delay!