feat(cli): add tab completions

[AmirSa12]

🔗 Linked issue

#1078

❓ Type of change

• 📖 Documentation (updates to the documentation or readme)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

This PR introduces tab completion functionality for the nuxt cli, improving developer experience by allowing shell(zsh, powershell, fish, bash) autocompletion for commands, options, values, and flags. 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 works:

nuxi.mp4

A small documentation of how CLIs can integrate tab ( in this case, I'm using the citty adapter )

import { defineCommand, createMain } from 'citty';
import tab from '@bomb.sh/tab/citty';

const main = defineCommand({
  meta: { name: 'my-cli', description: 'My CLI tool' },
  subCommands: {
    dev: defineCommand({
      meta: { name: 'dev', description: 'Start dev server' },
      args: {
        port: { type: 'string', description: 'Specify port' },
        host: { type: 'string', description: 'Specify host' },
      },
    }),
  },
});

// Initialize tab completions
const completion = await tab(main);

// Add custom completions
const devCommand = completion.commands.get('dev');
const portOption = devCommand?.options.get('port');
if (portOption) {
  portOption.handler = (complete) => {
    complete('3000', 'Development port');
    complete('8080', 'Production port');
  };
}

const cli = createMain(main);
cli();

[github-actions]

📦 Bundle Size Comparison

📈 nuxi

Metric	Base	Head	Diff
Rendered	4390.51 KB	4446.50 KB	+55.99 KB (+1.28%)

📈 nuxt-cli

Metric	Base	Head	Diff
Rendered	122.27 KB	124.27 KB	+2.00 KB (+1.63%)

📈 create-nuxt

Metric	Base	Head	Diff
Rendered	2420.71 KB	2460.91 KB	+40.19 KB (+1.66%)

[pkg-pr-new]

nuxt-cli-playground

npm i https://pkg.pr.new/create-nuxt@1082

npm i https://pkg.pr.new/nuxi@1082

npm i https://pkg.pr.new/@nuxt/cli@1082

commit: 44a49d1

[codspeed-hq]

CodSpeed Performance Report

Merging #1082 will not alter performance

_{Comparing AmirSa12:feat/tab-completions (44a49d1) with main (78f27f8)}

Summary

✅ 2 untouched

[danielroe]

this is looking very, very exciting!

[codecov-commenter]

Codecov Report

❌ Patch coverage is 3.20513% with 151 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@2b2b434). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
packages/nuxi/src/completions.ts	2.85%	68 Missing ⚠️
scripts/generate-completions-data.ts	2.12%	46 Missing ⚠️
packages/nuxi/src/completions-init.ts	4.34%	22 Missing ⚠️
packages/create-nuxt/src/main.ts	0.00%	6 Missing ⚠️
packages/nuxi/src/main.ts	0.00%	5 Missing ⚠️
packages/nuxt-cli/src/run.ts	20.00%	4 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1082   +/-   ##
=======================================
  Coverage        ?   24.88%           
=======================================
  Files           ?       85           
  Lines           ?     4388           
  Branches        ?      221           
=======================================
  Hits            ?     1092           
  Misses          ?     3266           
  Partials        ?       30           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[AmirSa12]

@danielroe, thank you for reporting the issue! I updated tab to version 0.0.8

[danielroe]

thank you!

CleanShot.2025-10-30.at.15.24.23.mp4

testing this after installing tab completions for pnpm, it doesn't seem to work, however.

am I missing anything?

[AmirSa12]

thank you!

CleanShot.2025-10-30.at.15.24.23.mp4
testing this after installing tab completions for pnpm, it doesn't seem to work, however.

am I missing anything?

I tested and it did work!

Did you source the script that tab generates?
Can you test with pnpm <TAB> and see if pnpm completions work in the first place?

[danielroe]

yes, no completions are printing at all.

CleanShot.2025-10-30.at.16.53.09.mp4

[danielroe]

@AmirSa12 investigated a bit more and the command embedded in bombshell completion script is failing:

    # Join the main command and the quoted arguments into a single string for eval
    requestComp="npx --yes @bomb.sh/tab pnpm complete -- ${quoted_args[*]}"

    __pnpm_debug "About to call: eval ${requestComp}"

    # Use eval to handle any environment variables and such

nuxt-app on  main [?] via  v24.5.0 took 10s
❯ npx --yes @bomb.sh/tab pnpm complete
sh: tab: command not found

the problem here is a missing @latest after @bomb.sh/tab.... and it's probably only relevant for me because I probably tried running bombshell early on and npm cached that version....

[AmirSa12]

@AmirSa12 investigated a bit more and the command embedded in bombshell completion script is failing:

    # Join the main command and the quoted arguments into a single string for eval
    requestComp="npx --yes @bomb.sh/tab pnpm complete -- ${quoted_args[*]}"

    __pnpm_debug "About to call: eval ${requestComp}"

    # Use eval to handle any environment variables and such

nuxt-app on  main [?] via  v24.5.0 took 10s
❯ npx --yes @bomb.sh/tab pnpm complete
sh: tab: command not found

the problem here is a missing @latest after @bomb.sh/tab.... and it's probably only relevant for me because I probably tried running bombshell early on and npm cached that version....

Hey @danielroe ! sorry for the delay, I was investigating this and I sent you a message on discord regarding this matter

[AmirSa12]

@AmirSa12 investigated a bit more and the command embedded in bombshell completion script is failing:

    # Join the main command and the quoted arguments into a single string for eval
    requestComp="npx --yes @bomb.sh/tab pnpm complete -- ${quoted_args[*]}"

    __pnpm_debug "About to call: eval ${requestComp}"

    # Use eval to handle any environment variables and such

nuxt-app on  main [?] via  v24.5.0 took 10s
❯ npx --yes @bomb.sh/tab pnpm complete
sh: tab: command not found

the problem here is a missing @latest after @bomb.sh/tab.... and it's probably only relevant for me because I probably tried running bombshell early on and npm cached that version....

with the new version, the requestComp="npx --yes @bomb.sh/tab pnpm complete -- ${quoted_args[*]}" has changed to using the installed version of tab direclty:
requestComp="tab pnpm complete -- ${quoted_args[*]}"
it's faster this way!

[danielroe]

spotted a bug (I think) where the last completion gets 'replayed' if you press tab a second time.

CleanShot.2025-11-04.at.16.35.14.mp4

(but that's not a reason not to merge this PR)

[AmirSa12]

spotted a bug (I think) where the last completion gets 'replayed' if you press tab a second time.

CleanShot.2025-11-04.at.16.35.14.mp4
(but that's not a reason not to merge this PR)

Oh! Thanks for letting me know. I will have a look!
Thank you, Daniel!