feat(cli): add tab completions #1082

AmirSa12 · 2025-10-11T11:32:39Z

🔗 Linked issue

❓ 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 · 2025-10-11T11:34:12Z

📦 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 · 2025-10-11T11:34:30Z

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 · 2025-10-11T11:38:49Z

CodSpeed Performance Report

Merging #1082 will not alter performance

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

Summary

✅ 2 untouched

README.md

packages/nuxi/package.json

packages/nuxi/src/main.ts

danielroe

this is looking very, very exciting!

packages/nuxi/package.json

README.md

packages/nuxi/src/completions.ts

scripts/generate-completions-data.ts

packages/nuxi/package.json

codecov-commenter · 2025-10-30T12:21:15Z

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.

README.md

AmirSa12 · 2025-10-30T14:05:59Z

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

danielroe · 2025-10-30T15:25:09Z

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 · 2025-10-30T15:47:24Z

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 · 2025-10-30T16:53:48Z

yes, no completions are printing at all.

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

danielroe · 2025-11-03T12:37:50Z

@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 · 2025-11-04T08:42:17Z

@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 · 2025-11-04T08:45:18Z

@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 · 2025-11-04T16:45:39Z

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 · 2025-11-05T07:08:49Z

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!

Aslemammad suggested changes Oct 11, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

packages/nuxi/package.json Outdated Show resolved Hide resolved

packages/nuxi/src/main.ts Outdated Show resolved Hide resolved

AmirSa12 force-pushed the feat/tab-completions branch 2 times, most recently from 3fab8fe to 911f4b4 Compare October 13, 2025 09:08

AmirSa12 marked this pull request as ready for review October 13, 2025 09:17

AmirSa12 requested a review from danielroe as a code owner October 13, 2025 09:17

danielroe reviewed Oct 13, 2025

View reviewed changes

AmirSa12 and others added 8 commits October 17, 2025 14:29

feat(cli): add tab completions

3ce4f79

readme

447e1a3

[autofix.ci] apply automated fixes

0461d5c

update

394e3bc

bombshell v0.0.5

2bf2b6c

types

22fc13c

update

8877baa

updates

81e36cf

AmirSa12 force-pushed the feat/tab-completions branch from b605055 to 81e36cf Compare October 17, 2025 11:01

use node module resolution

d1babb4

AmirSa12 commented Oct 17, 2025

View reviewed changes

scripts/generate-completions-data.ts Show resolved Hide resolved

danielroe added 2 commits October 21, 2025 21:25

Merge remote-tracking branch 'origin/main' into feat/tab-completions

632781d

refactor: use native node to run completions data

2252472

AmirSa12 commented Oct 23, 2025

View reviewed changes

packages/nuxi/package.json Outdated Show resolved Hide resolved

AmirSa12 added 2 commits October 23, 2025 13:15

chore: update tab to version 0.0.7

87e58f9

chore: readme

1860f10

AmirSa12 requested a review from danielroe October 28, 2025 08:28

danielroe added 4 commits October 30, 2025 11:59

Merge remote-tracking branch 'origin/main' into feat/tab-completions

63b2c8b

chore: move into build script

d4213cd

chore: suppress lint

d64d259

chore: lint

c7352b5

danielroe added 2 commits October 30, 2025 12:08

build: also for create nuxt

4e7d9bc

build: move back to postinstall

6325654

docs: remove global installation instructions

f15c787

danielroe reviewed Oct 30, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

danielroe mentioned this pull request Oct 30, 2025

npx @bomb.sh/tab throws with missing cac package bombshell-dev/tab#79

Closed

danielroe and others added 3 commits October 30, 2025 12:34

chore: knip update

1ede8e8

chore: use file url for output path

c1c28d0

chore: update tab to version 0.0.8

243bf65

AmirSa12 added 2 commits November 4, 2025 11:40

update tab to version 0.0.9

c016105

Merge remote-tracking branch 'upstream/main' into feat/tab-completions

590290c

AmirSa12 requested a review from danielroe November 4, 2025 09:03

Merge remote-tracking branch 'upstream/main' into feat/tab-completions

d37a720

danielroe added 3 commits November 4, 2025 16:46

Merge remote-tracking branch 'origin/main' into feat/tab-completions

166246a

build: use module url for import

c9c8bf7

chore: dance, dance little man

44a49d1

danielroe approved these changes Nov 4, 2025

View reviewed changes

danielroe merged commit fd1747f into nuxt:main Nov 4, 2025
12 checks passed

github-actions bot mentioned this pull request Nov 4, 2025

v3.31.0 #1119

Open

feat(cli): add tab completions #1082

feat(cli): add tab completions #1082

Uh oh!

Conversation

AmirSa12 commented Oct 11, 2025 • edited by danielroe Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔗 Linked issue

❓ Type of change

📚 Description

Uh oh!

github-actions bot commented Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 Bundle Size Comparison

📈 nuxi

📈 nuxt-cli

📈 create-nuxt

Uh oh!

pkg-pr-new bot commented Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codspeed-hq bot commented Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CodSpeed Performance Report

Merging #1082 will not alter performance

Summary

Uh oh!

Uh oh!

Uh oh!

Uh oh!

danielroe left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov-commenter commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

AmirSa12 commented Oct 30, 2025

Uh oh!

danielroe commented Oct 30, 2025

Uh oh!

AmirSa12 commented Oct 30, 2025

Uh oh!

danielroe commented Oct 30, 2025

Uh oh!

danielroe commented Nov 3, 2025

Uh oh!

AmirSa12 commented Nov 4, 2025

Uh oh!

AmirSa12 commented Nov 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

danielroe commented Nov 4, 2025

Uh oh!

Uh oh!

AmirSa12 commented Nov 5, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

AmirSa12 commented Oct 11, 2025 •

edited by danielroe

Loading

github-actions bot commented Oct 11, 2025 •

edited

Loading

pkg-pr-new bot commented Oct 11, 2025 •

edited

Loading

codspeed-hq bot commented Oct 11, 2025 •

edited

Loading

codecov-commenter commented Oct 30, 2025 •

edited

Loading

AmirSa12 commented Nov 4, 2025 •

edited

Loading