docs: update nuxt command pages

[BobbieGoede]

🔗 Linked issue

📚 Description

This syncs the documentation again with the actual command definition in nuxt/cli.

This also adds documentation for the test command, I haven't used that command myself so do check if it is correct.

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[coderabbitai]

Walkthrough

Documentation updates across multiple Nuxt CLI command pages. A new -e, --extends= option is added to analyze, build, dev, generate, prepare, preview, and typecheck docs. dev replaces --no-clear with --clear and adjusts host default. preview adds -p, --port and revises its description. init adds --logLevel and updates modules flag to -M, --modules. add expands the TEMPLATE list. module tweaks argument and --dev descriptions. upgrade expands channel values and refines dedupe text. A new test command page is introduced documenting usage, arguments, options, and NODE_ENV behaviour.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title succinctly describes the primary change—updating the Nuxt command documentation pages—without unnecessary detail or noise, adhering to conventional commit style and clearly conveying the main intent of the PR.
Description Check	✅ Passed	The description clearly outlines the purpose of the PR by stating that it syncs the documentation with the CLI definitions and adds the test command documentation, directly reflecting the changes made to the command pages.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[BobbieGoede]

This is the description used in nuxt/cli, the original description is not entirely accurate as was mentioned here #31467 (comment)

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/3.api/4.commands/preview.md (1)

13-37: Document --port as a valued option with its default.

The CLI still expects a numeric argument for --port (args.port ?? process.env.PORT ?? 3000 in packages/nuxi/src/commands/preview.ts), so the usage sample on Line 13 and the options table on Lines 35-37 should show the <port> placeholder. Also, the command continues to fall back to 3000 when neither the flag nor PORT is set; dropping that default from the table makes the docs inaccurate. Please restore both details.

-npx nuxt preview [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--envName] [-e, --extends=<layer-name>] [-p, --port] [--dotenv]
+npx nuxt preview [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--envName] [-e, --extends=<layer-name>] [-p, --port=<port>] [--dotenv]
@@
-`-p, --port` |  | Port to listen on (use `PORT` environment variable to override)
+`-p, --port=<port>` | `3000` | Port to listen on (use `PORT` environment variable to override)

🧹 Nitpick comments (2)

docs/3.api/4.commands/upgrade.md (2)

13-13: Include Nuxt 3 defaults in usage synopsis

The CLI still defaults --logLevel to info, so the usage synopsis should show [--logLevel=<silent|info|verbose> (default: info)] just like the other command docs in this PR do. Please add the (default: info) annotation here for consistency and clarity.

---

34-36: Clarify channel defaults across options table

Line 34 now reads nicely, but Line 36 still says “(default: stable)” in the description column even though the dedicated “Default” column already states stable. That repetition stood out after the change—could we drop the trailing “(default: stable)” to keep the table concise?

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 107197b and 6692582.

📒 Files selected for processing (12)

• docs/3.api/4.commands/add.md (1 hunks)
• docs/3.api/4.commands/analyze.md (2 hunks)
• docs/3.api/4.commands/build.md (2 hunks)
• docs/3.api/4.commands/dev.md (2 hunks)
• docs/3.api/4.commands/generate.md (2 hunks)
• docs/3.api/4.commands/init.md (3 hunks)
• docs/3.api/4.commands/module.md (2 hunks)
• docs/3.api/4.commands/prepare.md (2 hunks)
• docs/3.api/4.commands/preview.md (2 hunks)
• docs/3.api/4.commands/test.md (1 hunks)
• docs/3.api/4.commands/typecheck.md (2 hunks)
• docs/3.api/4.commands/upgrade.md (2 hunks)

🧰 Additional context used

🧠 Learnings (2)

📚 Learning: 2025-07-18T16:46:07.446Z

Learnt from: CR
PR: nuxt/nuxt#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-18T16:46:07.446Z
Learning: Applies to **/*.{test,spec}.{ts,tsx,js,jsx} : Write unit tests for core functionality using `vitest`

Applied to files:

• docs/3.api/4.commands/test.md

📚 Learning: 2025-07-18T16:46:07.446Z

Learnt from: CR
PR: nuxt/nuxt#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-18T16:46:07.446Z
Learning: Applies to **/e2e/**/*.{ts,js} : Write end-to-end tests using Playwright and `nuxt/test-utils`

Applied to files:

• docs/3.api/4.commands/test.md

🔇 Additional comments (1)

docs/3.api/4.commands/module.md (1)

34-34: Clarify dev-dependency flag behaviour
The docs say --dev installs a module as a dev dependency, but I can’t locate the CLI implementation to confirm it writes to devDependencies in package.json. Please verify that isDev truly yields a devDependencies entry; otherwise tighten the wording (e.g. “Install module for development only”).

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Revert multi-module wording for MODULENAME.

packages/nuxi/src/commands/module/add.ts still accepts only a single module name; it doesn’t split or iterate over additional arguments. Documenting “one or more modules… separated by spaces” will mislead users—extra arguments are simply ignored. Please keep the description singular (or document the actual enhancement if the CLI changes accordingly).

🤖 Prompt for AI Agents

In docs/3.api/4.commands/module.md around line 24, the description for
`MODULENAME` incorrectly says "one or more modules… separated by spaces"
although the CLI accepts only a single module; change the phrasing to indicate a
single module (e.g., "Specify the module to install by name") so documentation
matches current behavior, or alternatively note that multiple names are not
supported if you want to be explicit.

[BobbieGoede]

This positional argument does support multiple space separated module names, this description is copied directly from the file you are referencing.

[atinux]

You rock ❤️

[BobbieGoede]

We actually support --no-M (and more unjs/citty#209)

[danielroe]

thank you ❤️