feat(cli): add help flags to various commands

.changeset/old-rivers-remember.md

@@ -0,0 +1,5 @@
+---
+'astro': minor
+---
+
+Add `--help` to various commands: `check`, `sync`, `dev`, `preview`, and `build`

packages/astro/src/cli/check/index.ts

@@ -2,14 +2,15 @@
 import { AstroCheck, DiagnosticSeverity } from '@astrojs/language-server';
 import type { AstroSettings } from '../../@types/astro';
 import type { LogOptions } from '../../core/logger/core.js';
-
 import glob from 'fast-glob';
 import * as fs from 'fs';
 import { bold, dim, red, yellow } from 'kleur/colors';
 import { createRequire } from 'module';
 import ora from 'ora';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { printDiagnostic } from './print.js';
+import { Arguments } from 'yargs-parser';
+import { printHelp } from '../../core/messages.js';
 
 interface Result {
 	errors: number;
@@ -18,11 +19,25 @@ interface Result {
 	hints: number;
 }
 
-export async function check(settings: AstroSettings, { logging }: { logging: LogOptions }) {
+export async function check(
+	settings: AstroSettings,
+	{ logging, flags }: { logging: LogOptions; flags: Arguments }
+) {
+	if (flags.help || flags.h) {
+		printHelp({
+			commandName: 'astro check',
+			usage: '[...flags]',
+			tables: {
+				Flags: [['--help (-h)', 'See all available flags.']],
+			},
+			description: `Runs diagnostics against your project and reports errors to the console.`,
+		});
+		return;
+	}
 	console.log(bold('astro check'));
 
 	const { syncCli } = await import('../../core/sync/index.js');
-	const syncRet = await syncCli(settings, { logging, fs });
+	const syncRet = await syncCli(settings, { logging, fs, flags });
 	// early exit on sync failure
 	if (syncRet === 1) return syncRet;
 

packages/astro/src/cli/index.ts

@@ -75,13 +75,18 @@ async function printVersion() {
 /** Determine which command the user requested */
 function resolveCommand(flags: Arguments): CLICommand {
 	const cmd = flags._[2] as string;
-	if (cmd === 'add') return 'add';
-	if (cmd === 'sync') return 'sync';
-	if (cmd === 'telemetry') return 'telemetry';
 	if (flags.version) return 'version';
-	else if (flags.help) return 'help';
 
-	const supportedCommands = new Set(['dev', 'build', 'preview', 'check', 'docs']);
+	const supportedCommands = new Set([
+		'add',
+		'sync',
+		'telemetry',
+		'dev',
+		'build',
+		'preview',
+		'check',
+		'docs',
+	]);
 	if (supportedCommands.has(cmd)) {
 		return cmd as CLICommand;
 	}
@@ -144,6 +149,16 @@ async function runCommand(cmd: string, flags: yargs.Arguments) {
 		}
 		case 'docs': {
 			telemetry.record(event.eventCliSession(cmd));
+			if (flags.help || flags.h) {
+				printHelp({
+					commandName: 'astro docs',
+					tables: {
+						Flags: [['--help (-h)', 'See all available flags.']],
+					},
+					description: `Launches the Astro Docs website directly from the terminal.`,
+				});
+				return;
+			}
 			return await openInBrowser('https://docs.astro.build/');
 		}
 		case 'telemetry': {
@@ -203,26 +218,29 @@ async function runCommand(cmd: string, flags: yargs.Arguments) {
 		case 'build': {
 			const { default: build } = await import('../core/build/index.js');
 
-			return await build(settings, { ...flags, logging, telemetry, teardownCompiler: true });
+			return await build(settings, { flags, logging, telemetry, teardownCompiler: true });
 		}
 
 		case 'check': {
-			const ret = await check(settings, { logging });
+			const ret = await check(settings, { logging, flags });
 			return process.exit(ret);
 		}
 
 		case 'sync': {
 			const { syncCli } = await import('../core/sync/index.js');
 
-			const ret = await syncCli(settings, { logging, fs });
+			const ret = await syncCli(settings, { logging, fs, flags });
 			return process.exit(ret);
 		}
 
 		case 'preview': {
 			const { default: preview } = await import('../core/preview/index.js');
 
-			const server = await preview(settings, { logging, telemetry });
-			return await server.closed(); // keep alive until the server is closed
+			const server = await preview(settings, { logging, telemetry, flags });
+			if (server) {
+				return await server.closed(); // keep alive until the server is closed
+			}
+			return;
 		}
 	}
 

packages/astro/src/cli/telemetry.ts

@@ -10,7 +10,7 @@ export interface TelemetryOptions {
 export async function update(subcommand: string, { flags, telemetry }: TelemetryOptions) {
 	const isValid = ['enable', 'disable', 'reset'].includes(subcommand);
 
-	if (flags.help || !isValid) {
+	if (flags.help || flags.h || !isValid) {
 		msg.printHelp({
 			commandName: 'astro telemetry',
 			usage: '[command]',

packages/astro/src/core/build/index.ts

@@ -21,6 +21,8 @@ import { collectPagesData } from './page-data.js';
 import { staticBuild, viteBuild } from './static-build.js';
 import { StaticBuildOptions } from './types.js';
 import { getTimeStat } from './util.js';
+import { printHelp } from '../messages.js';
+import yargs from 'yargs-parser';
 
 export interface BuildOptions {
 	mode?: RuntimeMode;
@@ -31,11 +33,27 @@ export interface BuildOptions {
 	 * building once, but may cause a performance hit if building multiple times in a row.
 	 */
 	teardownCompiler?: boolean;
+	flags?: yargs.Arguments;
 }
 
 /** `astro build` */
 export default async function build(settings: AstroSettings, options: BuildOptions): Promise<void> {
 	applyPolyfill();
+	if (options.flags?.help || options.flags?.h) {
+		printHelp({
+			commandName: 'astro build',
+			usage: '[...flags]',
+			tables: {
+				Flags: [
+					['--drafts', `Include Markdown draft pages in the build.`],
+					['--help (-h)', 'See all available flags.'],
+				],
+			},
+			description: `Builds your site for deployment.`,
+		});
+		return;
+	}
+
 	const builder = new AstroBuilder(settings, options);
 	await builder.run();
 }

packages/astro/src/core/dev/dev.ts

@@ -10,11 +10,13 @@ import { info, LogOptions, warn } from '../logger/core.js';
 import * as msg from '../messages.js';
 import { startContainer } from './container.js';
 import { createContainerWithAutomaticRestart } from './restart.js';
+import { printHelp } from '../messages.js';
+import { cyan } from 'kleur/colors';
 
 export interface DevOptions {
 	configFlag: string | undefined;
 	configFlagPath: string | undefined;
-	flags: yargs.Arguments | undefined;
+	flags?: yargs.Arguments;
 	logging: LogOptions;
 	telemetry: AstroTelemetry;
 	handleConfigError: (error: Error) => void;
@@ -32,7 +34,26 @@ export interface DevServer {
 export default async function dev(
 	settings: AstroSettings,
 	options: DevOptions
-): Promise<DevServer> {
+): Promise<DevServer | undefined> {
+	if (options.flags?.help || options.flags?.h) {
+		printHelp({
+			commandName: 'astro dev',
+			usage: '[...flags]',
+			tables: {
+				Flags: [
+					['--port', `Specify which port to run on. Defaults to 3000.`],
+					['--host', `Listen on all addresses, including LAN and public addresses.`],
+					['--host <custom-address>', `Expose on a network IP address at <custom-address>`],
+					['--help (-h)', 'See all available flags.'],
+				],
+			},
+			description: `Check ${cyan(
+				'https://docs.astro.build/en/reference/cli-reference/#astro-dev'
+			)} for more information.`,
+		});
+		return;
+	}
+
 	const devStart = performance.now();
 	await options.telemetry.record([]);
 

packages/astro/src/core/preview/index.ts

@@ -6,17 +6,35 @@ import { runHookConfigDone, runHookConfigSetup } from '../../integrations/index.
 import type { LogOptions } from '../logger/core';
 import createStaticPreviewServer from './static-preview-server.js';
 import { getResolvedHostForHttpServer } from './util.js';
+import type { Arguments } from 'yargs-parser';
+import { printHelp } from '../messages.js';
+import { cyan } from 'kleur/colors';
 
 interface PreviewOptions {
 	logging: LogOptions;
 	telemetry: AstroTelemetry;
+	flags?: Arguments;
 }
 
 /** The primary dev action */
 export default async function preview(
 	_settings: AstroSettings,
-	{ logging }: PreviewOptions
-): Promise<PreviewServer> {
+	{ logging, flags }: PreviewOptions
+): Promise<PreviewServer | undefined> {
+	if (flags?.help || flags?.h) {
+		printHelp({
+			commandName: 'astro preview',
+			usage: '[...flags]',
+			tables: {
+				Flags: [['--help (-h)', 'See all available flags.']],
+			},
+			description: `Starts a local server to serve your static dist/ directory. Check ${cyan(
+				'https://docs.astro.build/en/reference/cli-reference/#astro-preview'
+			)} for more information.`,
+		});
+		return;
+	}
+
 	const settings = await runHookConfigSetup({
 		settings: _settings,
 		command: 'preview',

packages/astro/src/core/sync/index.ts

@@ -11,13 +11,27 @@ import { getTimeStat } from '../build/util.js';
 import { createVite } from '../create-vite.js';
 import { AstroError, AstroErrorData } from '../errors/index.js';
 import { info, LogOptions } from '../logger/core.js';
+import { printHelp } from '../messages.js';
+import { Arguments } from 'yargs-parser';
 
 type ProcessExit = 0 | 1;
 
 export async function syncCli(
 	settings: AstroSettings,
-	{ logging, fs }: { logging: LogOptions; fs: typeof fsMod }
+	{ logging, fs, flags }: { logging: LogOptions; fs: typeof fsMod; flags?: Arguments }
 ): Promise<ProcessExit> {
+	if (flags?.help || flags?.h) {
+		printHelp({
+			commandName: 'astro sync',
+			usage: '[...flags]',
+			tables: {
+				Flags: [['--help (-h)', 'See all available flags.']],
+			},
+			description: `Generates TypeScript types for all Astro modules.`,
+		});
+		return 0;
+	}
+
 	const resolvedSettings = await runHookConfigSetup({
 		settings,
 		logging,