improve C3 help message (#4249)

* improve C3 help message

* correct C3's error message for unrecognized application type

* remove usage details from c3 readme and just point to official docs

* Apply suggestions from code review

Co-authored-by: Adam Murray <admah@users.noreply.github.com>

---------

Co-authored-by: Adam Murray <admah@users.noreply.github.com>

.changeset/hot-kiwis-raise.md

@@ -0,0 +1,5 @@
+---
+"create-cloudflare": patch
+---
+
+correct error message for unrecognized application type

.changeset/olive-queens-retire.md

@@ -0,0 +1,6 @@
+---
+"create-cloudflare": patch
+---
+
+improve help message by adding more detailed descriptions about the various CLI options
+also let the user know that more information is available in the Cloudflare docs

packages/create-cloudflare/README.md

@@ -2,58 +2,7 @@
 
 A CLI for creating and deploying new applications to [Cloudflare](https://developers.cloudflare.com/).
 
-## Usage
-
-### Setup via Interactive CLI
-
-To create new applications via interactive CLI, run:
-
-```bash
-npm create cloudflare@latest
-# or
-pnpm create cloudflare@latest
-# or
-yarn create cloudflare
-```
-
-### Setup via CLI Arguments
-
-#### New Websites or Web applications via Frameworks
-
-To create a new website or web framework without interaction, run:
-
-```bash
-npm create cloudflare@latest -- --type webFramework --framework <frameworkName>
-# or
-pnpm create cloudflare@latest ...
-# or
-yarn create cloudflare ...
-```
-
-Currently supported framework options: `angular`, `astro`, `docusaurus`, `gatsby`, `hono`, `next`, `nuxt`, `qwik`, `react`, `remix`, `solid`, `svelte`, `vue`.
-
-#### New Workers via Templates
-
-To create a new Javascript "Hello World" worker, run:
-
-```bash
-npm create cloudflare@latest hello-world -- --type hello-world --no-ts
-```
-
-To create a new Typescript "Hello World" worker, run:
-
-```bash
-npm create cloudflare@latest hello-world -- --type hello-world --ts
-```
-
-Current template options are: `hello-world`, `common`, `chatgptPlugin`, or `openapi`.
-
-#### Additional arguments
-
-|               |                                                                         |
-| ------------- | :---------------------------------------------------------------------: |
-| `--deploy`    | deploy your application automatically, bypassing the interactive prompt |
-| `--no-deploy` |   create and scaffold a new application and bypass deployment prompt    |
+For more details on how to use the create-cloudflare CLI (C3) please visit the [official C3 documentation](https://developers.cloudflare.com/pages/get-started/c3).
 
 ### Community
 

packages/create-cloudflare/src/cli.ts

@@ -104,10 +104,14 @@ export const runCli = async (args: Partial<C3Args>) => {
 		defaultValue: C3_DEFAULTS.type,
 	});
 
-	if (!type || !Object.keys(templateMap).includes(type)) {
+	if (!type) {
 		return crash("An application type must be specified to continue.");
 	}
 
+	if (!Object.keys(templateMap).includes(type)) {
+		return crash(`Unknown application type provided: ${type}.`);
+	}
+
 	const validatedArgs: C3Args = {
 		...args,
 		type,

packages/create-cloudflare/src/helpers/args.ts

@@ -20,17 +20,37 @@ export const parseArgs = async (argv: string[]): Promise<Partial<C3Args>> => {
 	const yargsObj = yargs(hideBin(c3Args))
 		.scriptName("create-cloudflare")
 		.usage("$0 [args]")
-		.positional("name", { type: "string" })
-		.option("type", { type: "string" })
-		.option("framework", { type: "string" })
-		.option("deploy", { type: "boolean" })
-		.option("ts", { type: "boolean" })
-		.option("git", { type: "boolean" })
+		.positional("directory", {
+			type: "string",
+			description:
+				"The directory where the application should be created. The name of the application is taken from the directory name",
+		})
+		.option("type", {
+			type: "string",
+			description: "The type of application that should be created",
+		})
+		.option("framework", {
+			type: "string",
+			description:
+				"The type of framework to use to create a web application (when using this option `--type` is ignored)",
+		})
+		.option("deploy", {
+			type: "boolean",
+			description: "Deploy your application after it has been created",
+		})
+		.option("ts", {
+			type: "boolean",
+			description: "Use TypeScript in your application",
+		})
+		.option("git", {
+			type: "boolean",
+			description: "Initialize a local git repository for your application",
+		})
 		.option("open", {
 			type: "boolean",
 			default: true,
 			description:
-				"opens your browser after your deployment, set --no-open to disable",
+				"Opens the deployed application in your browser (this option is ignored if the application is not deployed)",
 		})
 		.option("existing-script", {
 			type: "string",
@@ -39,28 +59,53 @@ export const parseArgs = async (argv: string[]): Promise<Partial<C3Args>> => {
 		.option("accept-defaults", {
 			alias: "y",
 			type: "boolean",
+			description:
+				"Use all the default C3 options (each can also be overridden by specifying it)",
 		})
 		.option("auto-update", {
 			type: "boolean",
 			default: C3_DEFAULTS.autoUpdate,
-			description:
-				"Automatically uses the latest version of `create-cloudflare`. Set --no-auto-update to disable",
+			description: "Automatically uses the latest version of C3",
 		})
 		.option("wrangler-defaults", { type: "boolean", hidden: true })
 		.version(version)
+		.alias("v", "version")
 		// note: we use strictOptions since `strict()` seems not to handle `positional`s correctly
 		.strictOptions()
+		// we want to include a note in our help message pointing people to the cloudflare C3 docs, yargs doesn't
+		// allow us to simply append to its help message so we need to prevent yargs from process.exiting so that
+		// we can show the extra note and exit manually
+		.exitProcess(false)
 		.alias("h", "help")
 		.help();
 
-	const args = await yargsObj.argv;
+	let args: Awaited<typeof yargsObj["argv"]> | null = null;
+
+	try {
+		args = await yargsObj.argv;
+	} catch {}
+
+	if (args === null) {
+		showMoreInfoNote();
+		process.exit(1);
+	}
+
+	if (args.version) {
+		process.exit(0);
+	}
+
+	if (args.help) {
+		showMoreInfoNote();
+		process.exit(0);
+	}
 
 	const positionalArgs = args._;
 
 	// since `yargs.strict()` can't check the `positional`s for us we need to do it manually ourselves
 	if (positionalArgs.length > 1) {
 		yargsObj.showHelp();
 		console.error("\nToo many positional arguments provided");
+		showMoreInfoNote();
 		process.exit(1);
 	}
 
@@ -101,3 +146,11 @@ export const processArgument = async <T>(
 
 	return value as T;
 };
+
+const showMoreInfoNote = () => {
+	const c3CliArgsDocsPage =
+		"https://developers.cloudflare.com/pages/get-started/c3/#cli-arguments";
+	console.log(
+		`\nFor more information regarding how to invoke C3 please visit ${c3CliArgsDocsPage}`
+	);
+};

packages/create-cloudflare/src/types.ts

@@ -15,7 +15,6 @@ export type C3Args = {
 	ts?: boolean;
 	existingScript?: string;
 	wranglerDefaults?: boolean;
-	acceptDefaults?: boolean;
 	additionalArgs?: string[];
 };