feat(wrangler): Add command categories to help menu (#11728)

* Add initial help menu command categories

* Improved category ordering

* Updated `wrangler` help menu test snapshots

* Fixed Wrangler invalid command help menu categories

* Fixed uncategorized commands empty spacing

* Minor refactoring

* Minor `showHelpWithCategories` refactoring

* Added changeset

* Updated changeset to `minor` + improved description

* Updated D1 test snapshots

* Fixed command registry category tracking

* Fixed vectorize command category

* Fixed help menu inline snapshots

* Fixed storage & databases catgeory inline snapshots

* Minor code cleanup from suggestions

Co-authored-by: Dario Piotrowicz <dario@cloudflare.com>

* Minor code cleanup based on review suggestions

* Minor command registry cleanup

* Added explicit return type to `#trackCategory` method

* Restore nullish `definition.metadata` category property

* Updated `#trackCategory` JSDoc description

* Added explicit types to line parameters

Co-authored-by: Dario Piotrowicz <dario@cloudflare.com>

* Minor code cleanup / refactoring

* Convert ordered category entries to array to use `.find()`

---------

Co-authored-by: Dario Piotrowicz <dario@cloudflare.com>

Author: NuroDev

.changeset/large-hotels-open.md

@@ -0,0 +1,26 @@
+---
+"wrangler": minor
+---
+
+Add command categories to `wrangler` help menu
+
+The help output now groups commands by product category (Account, Compute & AI, Storage & Databases, Networking & Security) to match the Cloudflare dashboard organization:
+
+` ` `
+$ wrangler --help
+
+COMMANDS
+  wrangler docs [search..]  📚 Open Wrangler's command documentation in your browser
+
+ACCOUNT
+  wrangler auth    🔓 Manage authentication
+  wrangler login   🔑 Login to Cloudflare
+  ...
+
+COMPUTE & AI
+  wrangler ai          🤖 Manage AI models
+  wrangler containers  📦 Manage Containers [open beta]
+  ...
+` ` `
+
+This improves discoverability by organizing the 20+ wrangler commands into logical groups.

packages/wrangler/src/__tests__/d1/d1.test.ts

@@ -15,7 +15,7 @@ describe("d1", () => {
 		expect(std.out).toMatchInlineSnapshot(`
 			"wrangler d1
 
-			🗄 Manage Workers D1 databases
+			🗄️ Manage Workers D1 databases
 
 			COMMANDS
 			  wrangler d1 create <name>       Creates a new D1 database, and provides the binding and UUID that you will put in your config file
@@ -52,7 +52,7 @@ describe("d1", () => {
 			"
 			wrangler d1
 
-			🗄 Manage Workers D1 databases
+			🗄️ Manage Workers D1 databases
 
 			COMMANDS
 			  wrangler d1 create <name>       Creates a new D1 database, and provides the binding and UUID that you will put in your config file

packages/wrangler/src/__tests__/index.test.ts

@@ -38,40 +38,46 @@ describe("wrangler", () => {
 				COMMANDS
 				  wrangler docs [search..]        📚 Open Wrangler's command documentation in your browser
 
-				  wrangler init [name]            📥 Initialize a basic Worker
-				  wrangler dev [script]           👂 Start a local server for developing your Worker
+				ACCOUNT
+				  wrangler auth                   🔐 Manage authentication
+				  wrangler login                  🔓 Login to Cloudflare
+				  wrangler logout                 🚪 Logout from Cloudflare
+				  wrangler whoami                 🕵️ Retrieve your user information
+
+				COMPUTE & AI
+				  wrangler ai                     🤖 Manage AI models
+				  wrangler containers             📦 Manage Containers [open beta]
+				  wrangler delete [script]        🗑️ Delete a Worker from Cloudflare
 				  wrangler deploy [script]        🆙 Deploy a Worker to Cloudflare
-				  wrangler setup                  🪄 Setup a project to work on Cloudflare [experimental]
 				  wrangler deployments            🚢 List and view the current and past deployments for your Worker
+				  wrangler dev [script]           👂 Start a local server for developing your Worker
+				  wrangler dispatch-namespace     🏗️ Manage dispatch namespaces
+				  wrangler init [name]            📥 Initialize a basic Worker
+				  wrangler pages                  ⚡️ Configure Cloudflare Pages
+				  wrangler pubsub                 📮 Manage Pub/Sub brokers [private beta]
+				  wrangler queues                 📬 Manage Workers Queues
 				  wrangler rollback [version-id]  🔙 Rollback a deployment for a Worker
-				  wrangler versions               🫧 List, view, upload and deploy Versions of your Worker to Cloudflare
-				  wrangler triggers               🎯 Updates the triggers of your current deployment [experimental]
-				  wrangler delete [script]        🗑 Delete a Worker from Cloudflare
-				  wrangler tail [worker]          🦚 Start a log tailing session for a Worker
 				  wrangler secret                 🤫 Generate a secret that can be referenced in a Worker
+				  wrangler setup                  🪄 Setup a project to work on Cloudflare [experimental]
+				  wrangler tail [worker]          🦚 Start a log tailing session for a Worker
+				  wrangler triggers               🎯 Updates the triggers of your current deployment [experimental]
 				  wrangler types [path]           📝 Generate types from your Worker configuration
+				  wrangler versions               🫧 List, view, upload and deploy Versions of your Worker to Cloudflare
+				  wrangler vpc                    🌐 Manage VPC [open beta]
+				  wrangler workflows              🔁 Manage Workflows
 
+				STORAGE & DATABASES
+				  wrangler d1                     🗄️ Manage Workers D1 databases
+				  wrangler hyperdrive             🚀 Manage Hyperdrive databases
 				  wrangler kv                     🗂️ Manage Workers KV Namespaces
-				  wrangler queues                 📬 Manage Workers Queues
+				  wrangler pipelines              🚰 Manage Cloudflare Pipelines [open beta]
 				  wrangler r2                     📦 Manage R2 buckets & objects
-				  wrangler d1                     🗄 Manage Workers D1 databases
+				  wrangler secrets-store          🔐 Manage the Secrets Store [open beta]
 				  wrangler vectorize              🧮 Manage Vectorize indexes
-				  wrangler hyperdrive             🚀 Manage Hyperdrive databases
+
+				NETWORKING & SECURITY
 				  wrangler cert                   🪪 Manage client mTLS certificates and CA certificate chains used for secured connections [open beta]
-				  wrangler pages                  ⚡️ Configure Cloudflare Pages
 				  wrangler mtls-certificate       🪪 Manage certificates used for mTLS connections
-				  wrangler containers             📦 Manage Containers [open beta]
-				  wrangler pubsub                 📮 Manage Pub/Sub brokers [private beta]
-				  wrangler dispatch-namespace     🏗️ Manage dispatch namespaces
-				  wrangler ai                     🤖 Manage AI models
-				  wrangler secrets-store          🔐 Manage the Secrets Store [open beta]
-				  wrangler workflows              🔁 Manage Workflows
-				  wrangler pipelines              🚰 Manage Cloudflare Pipelines [open beta]
-				  wrangler vpc                    🌐 Manage VPC [open beta]
-				  wrangler login                  🔓 Login to Cloudflare
-				  wrangler logout                 🚪 Logout from Cloudflare
-				  wrangler whoami                 🕵️ Retrieve your user information
-				  wrangler auth                   🔐 Manage authentication
 
 				GLOBAL FLAGS
 				  -c, --config    Path to Wrangler configuration file  [string]
@@ -103,40 +109,46 @@ describe("wrangler", () => {
 				COMMANDS
 				  wrangler docs [search..]        📚 Open Wrangler's command documentation in your browser
 
-				  wrangler init [name]            📥 Initialize a basic Worker
-				  wrangler dev [script]           👂 Start a local server for developing your Worker
+				ACCOUNT
+				  wrangler auth                   🔐 Manage authentication
+				  wrangler login                  🔓 Login to Cloudflare
+				  wrangler logout                 🚪 Logout from Cloudflare
+				  wrangler whoami                 🕵️ Retrieve your user information
+
+				COMPUTE & AI
+				  wrangler ai                     🤖 Manage AI models
+				  wrangler containers             📦 Manage Containers [open beta]
+				  wrangler delete [script]        🗑️ Delete a Worker from Cloudflare
 				  wrangler deploy [script]        🆙 Deploy a Worker to Cloudflare
-				  wrangler setup                  🪄 Setup a project to work on Cloudflare [experimental]
 				  wrangler deployments            🚢 List and view the current and past deployments for your Worker
+				  wrangler dev [script]           👂 Start a local server for developing your Worker
+				  wrangler dispatch-namespace     🏗️ Manage dispatch namespaces
+				  wrangler init [name]            📥 Initialize a basic Worker
+				  wrangler pages                  ⚡️ Configure Cloudflare Pages
+				  wrangler pubsub                 📮 Manage Pub/Sub brokers [private beta]
+				  wrangler queues                 📬 Manage Workers Queues
 				  wrangler rollback [version-id]  🔙 Rollback a deployment for a Worker
-				  wrangler versions               🫧 List, view, upload and deploy Versions of your Worker to Cloudflare
-				  wrangler triggers               🎯 Updates the triggers of your current deployment [experimental]
-				  wrangler delete [script]        🗑 Delete a Worker from Cloudflare
-				  wrangler tail [worker]          🦚 Start a log tailing session for a Worker
 				  wrangler secret                 🤫 Generate a secret that can be referenced in a Worker
+				  wrangler setup                  🪄 Setup a project to work on Cloudflare [experimental]
+				  wrangler tail [worker]          🦚 Start a log tailing session for a Worker
+				  wrangler triggers               🎯 Updates the triggers of your current deployment [experimental]
 				  wrangler types [path]           📝 Generate types from your Worker configuration
+				  wrangler versions               🫧 List, view, upload and deploy Versions of your Worker to Cloudflare
+				  wrangler vpc                    🌐 Manage VPC [open beta]
+				  wrangler workflows              🔁 Manage Workflows
 
+				STORAGE & DATABASES
+				  wrangler d1                     🗄️ Manage Workers D1 databases
+				  wrangler hyperdrive             🚀 Manage Hyperdrive databases
 				  wrangler kv                     🗂️ Manage Workers KV Namespaces
-				  wrangler queues                 📬 Manage Workers Queues
+				  wrangler pipelines              🚰 Manage Cloudflare Pipelines [open beta]
 				  wrangler r2                     📦 Manage R2 buckets & objects
-				  wrangler d1                     🗄 Manage Workers D1 databases
+				  wrangler secrets-store          🔐 Manage the Secrets Store [open beta]
 				  wrangler vectorize              🧮 Manage Vectorize indexes
-				  wrangler hyperdrive             🚀 Manage Hyperdrive databases
+
+				NETWORKING & SECURITY
 				  wrangler cert                   🪪 Manage client mTLS certificates and CA certificate chains used for secured connections [open beta]
-				  wrangler pages                  ⚡️ Configure Cloudflare Pages
 				  wrangler mtls-certificate       🪪 Manage certificates used for mTLS connections
-				  wrangler containers             📦 Manage Containers [open beta]
-				  wrangler pubsub                 📮 Manage Pub/Sub brokers [private beta]
-				  wrangler dispatch-namespace     🏗️ Manage dispatch namespaces
-				  wrangler ai                     🤖 Manage AI models
-				  wrangler secrets-store          🔐 Manage the Secrets Store [open beta]
-				  wrangler workflows              🔁 Manage Workflows
-				  wrangler pipelines              🚰 Manage Cloudflare Pipelines [open beta]
-				  wrangler vpc                    🌐 Manage VPC [open beta]
-				  wrangler login                  🔓 Login to Cloudflare
-				  wrangler logout                 🚪 Logout from Cloudflare
-				  wrangler whoami                 🕵️ Retrieve your user information
-				  wrangler auth                   🔐 Manage authentication
 
 				GLOBAL FLAGS
 				  -c, --config    Path to Wrangler configuration file  [string]

packages/wrangler/src/ai/index.ts

@@ -5,6 +5,7 @@ export const aiNamespace = createNamespace({
 		description: "🤖 Manage AI models",
 		status: "stable",
 		owner: "Product: AI",
+		category: "Compute & AI",
 	},
 });
 

packages/wrangler/src/cert/cert.ts

@@ -19,6 +19,7 @@ export const certNamespace = createNamespace({
 			"🪪 Manage client mTLS certificates and CA certificate chains used for secured connections",
 		status: "open beta",
 		owner: "Product: SSL",
+		category: "Networking & security",
 	},
 });
 

packages/wrangler/src/core/CommandRegistry.ts

@@ -13,12 +13,30 @@ import type {
 	DefinitionTreeNode,
 	InternalDefinition,
 	Metadata,
+	MetadataCategory,
 	NamedArgDefinitions,
 	NamespaceDefinition,
 } from "./types";
 
 const BETA_CMD_COLOR = "#BD5B08";
 
+/**
+ * Map of category names to the top-level command segments that belong to them.
+ * Used for grouping commands in the help output.
+ */
+type CategoryMap = Map<MetadataCategory, Array<string>>;
+
+/**
+ * The default order for categories in the help output.
+ * Categories not in this list will appear after these in alphabetical order.
+ */
+const COMMAND_CATEGORY_ORDER = [
+	"Account",
+	"Compute & AI",
+	"Storage & databases",
+	"Networking & security",
+] satisfies Array<MetadataCategory>;
+
 /**
  * Class responsible for registering and managing commands within a command registry.
  */
@@ -43,6 +61,12 @@ export class CommandRegistry {
 	 */
 	#tree: DefinitionTree;
 
+	/**
+	 * Map of category names to command segments.
+	 * Used for grouping commands in the help output.
+	 */
+	#categories: CategoryMap;
+
 	/**
 	 * Initializes the command registry with the given command registration function.
 	 */
@@ -51,6 +75,7 @@ export class CommandRegistry {
 		this.#registeredNamespaces = new Set<string>();
 		this.#registerCommand = registerCommand;
 		this.#tree = this.#DefinitionTreeRoot.subtree;
+		this.#categories = new Map();
 	}
 
 	/**
@@ -109,6 +134,52 @@ export class CommandRegistry {
 		this.#walkTreeAndRegister(namespace, node, `wrangler ${namespace}`);
 	}
 
+	/**
+	 * Returns the map of categories to command segments, ordered according to
+	 * the category order. Commands within each category are sorted alphabetically.
+	 * Used for grouping commands in the help output.
+	 */
+	get orderedCategories(): CategoryMap {
+		const orderedCategories: CategoryMap = new Map();
+		for (const category of COMMAND_CATEGORY_ORDER) {
+			if (!this.#categories.has(category)) {
+				continue;
+			}
+
+			const commands = this.#categories.get(category) ?? [];
+			orderedCategories.set(category, [...commands].sort());
+		}
+
+		const remainingCategories = Array.from(this.#categories.keys())
+			.filter(
+				(cat) => !COMMAND_CATEGORY_ORDER.includes(cat as MetadataCategory)
+			)
+			.sort();
+		for (const category of remainingCategories) {
+			const commands = this.#categories.get(category) ?? [];
+			orderedCategories.set(category, [...commands].sort());
+		}
+
+		return orderedCategories;
+	}
+
+	/**
+	 * Registers a category for a legacy command that doesn't use the CommandRegistry.
+	 * This is used for commands like `containers`, `pubsub`, etc, that use the old yargs pattern.
+	 */
+	registerLegacyCommandCategory(
+		command: string,
+		category: MetadataCategory
+	): void {
+		const existing = this.#categories.get(category) ?? [];
+		if (existing.includes(command)) {
+			return;
+		}
+
+		existing.push(command);
+		this.#categories.set(category, existing);
+	}
+
 	/**
 	 * Defines a single command and its corresponding definition.
 	 */
@@ -128,8 +199,37 @@ export class CommandRegistry {
 
 		if (isCommandDefinition(definition)) {
 			this.#upsertDefinition({ type: "command", command, ...definition });
+			this.#trackCategory(command, definition.metadata?.category);
 		} else if (isNamespaceDefinition(definition)) {
 			this.#upsertDefinition({ type: "namespace", command, ...definition });
+			this.#trackCategory(command, definition.metadata?.category);
+		}
+	}
+
+	/**
+	 * Adds a top-level command (e.g., "wrangler r2") to the `#categories` map for help output grouping.
+	 * Subcommands (e.g., "wrangler r2 bucket") are ignored since the parent already represents them.
+	 */
+	#trackCategory(
+		command: Command,
+		category: MetadataCategory | undefined
+	): void {
+		const segments = command.split(" ").slice(1);
+
+		// Only track categories for top-level commands (e.g., "wrangler r2", not "wrangler r2 bucket")
+		if (segments.length !== 1) {
+			return;
+		}
+
+		if (!category) {
+			return;
+		}
+
+		const segment = segments[0];
+		const existing = this.#categories.get(category) ?? [];
+		if (!existing.includes(segment)) {
+			existing.push(segment);
+			this.#categories.set(category, existing);
 		}
 	}
 

packages/wrangler/src/core/handle-errors.ts

@@ -87,7 +87,28 @@ export async function handleError(
 		// We are not able to ask the `wrangler` CLI parser to show help for a subcommand programmatically.
 		// The workaround is to re-run the parsing with an additional `--help` flag, which will result in the correct help message being displayed.
 		// The `wrangler` object is "frozen"; we cannot reuse that with different args, so we must create a new CLI parser to generate the help message.
-		const { wrangler } = createCLIParser([...subCommandParts, "--help"]);
+
+		// Check if this is a root-level error (unknown argument at root level)
+		// by looking at the error message - if it says "Unknown argument" or "Unknown command",
+		// and there's only one non-flag argument, show the categorized root help
+		const nonFlagArgs = subCommandParts.filter(
+			(arg) => !arg.startsWith("-") && arg !== ""
+		);
+		const isRootLevelError =
+			nonFlagArgs.length <= 1 &&
+			(e.message.includes("Unknown argument") ||
+				e.message.includes("Unknown command"));
+
+		const { wrangler, showHelpWithCategories } = createCLIParser([
+			...(isRootLevelError ? [] : subCommandParts),
+			"--help",
+		]);
+
+		if (isRootLevelError) {
+			await showHelpWithCategories();
+			return;
+		}
+
 		await wrangler.parse();
 	} else if (
 		isAuthenticationError(e) ||

packages/wrangler/src/core/types.ts

@@ -48,6 +48,12 @@ export type DeepFlatten<T> = T extends object
 	? { [K in keyof T]: DeepFlatten<T[K]> }
 	: T;
 
+export type MetadataCategory =
+	| "Account"
+	| "Compute & AI"
+	| "Storage & databases"
+	| "Networking & security";
+
 export type Command = `wrangler${string}`;
 export type Metadata = {
 	description: string;
@@ -64,6 +70,12 @@ export type Metadata = {
 		description: string;
 	}[];
 	hideGlobalFlags?: string[];
+	/**
+	 * Optional category for grouping commands in the help output.
+	 * Commands with the same category will be grouped together under a shared heading.
+	 * Commands without a category will appear under the default "COMMANDS" group.
+	 */
+	category?: MetadataCategory;
 };
 
 export type ArgDefinition = Omit<PositionalOptions, "type"> &