Update the dev-env commands to follow the VIP-CLI style guide

src/bin/vip-dev-env-create.js

@@ -5,10 +5,6 @@ import debugLib from 'debug';
 
 import command from '../lib/cli/command';
 import * as exit from '../lib/cli/exit';
-import {
-	DEV_ENVIRONMENT_FULL_COMMAND,
-	DEV_ENVIRONMENT_SUBCOMMAND,
-} from '../lib/constants/dev-environment';
 import {
 	DEFAULT_SLUG,
 	getEnvironmentName,
@@ -36,41 +32,52 @@ import { bootstrapLando } from '../lib/dev-environment/dev-environment-lando';
 import { trackEvent } from '../lib/tracker';
 
 const debug = debugLib( '@automattic/vip:bin:dev-environment' );
+const exampleUsage = 'vip dev-env create';
+const usage = 'vip dev-env create';
 
+// Command examples
 const examples = [
 	{
-		usage: `${ DEV_ENVIRONMENT_FULL_COMMAND } create`,
-		description: 'Creates a local dev environment',
-	},
-	{
-		usage: `vip @123.production ${ DEV_ENVIRONMENT_SUBCOMMAND } create`,
-		description: 'Creates a local dev environment for production site for id 123',
-	},
-	{
-		usage: `vip ${ DEV_ENVIRONMENT_SUBCOMMAND } create --slug=my_site`,
-		description: 'Creates a local dev environment aliased as "my_site"',
+		usage: exampleUsage,
+		description:
+			'Create a new VIP Local Development Environment.\n' +
+			'       * The environment will be named "vip-local" by default if a custom name is not assigned with "--slug" .',
 	},
 	{
-		usage: `${ DEV_ENVIRONMENT_FULL_COMMAND } create --slug=test`,
+		usage: `${ exampleUsage } --slug=example-site`,
 		description:
-			'Assigning unique slugs to environments allows multiple environments to be created.',
+			'Create a new local environment with the unique name "example-site".\n' +
+			'       * Unique names allow multiple local environments to exist simultaneously.',
 	},
 	{
-		usage: `${ DEV_ENVIRONMENT_FULL_COMMAND } create --multisite --wordpress="5.8" --app-code="~/git/my_code"`,
+		usage: `${ exampleUsage } --slug=example-site --multisite=y --php=8.2 --wordpress=6.4`,
 		description:
-			'Creates a local multisite dev environment using WP 5.8 and application code is expected to be in "~/git/my_code"',
+			'Create a new local environment configured as a multisite running PHP 8.2 and WordPress version 6.4.\n' +
+			'       * Options that are set in the `create` command will be skipped in the setup wizard.',
 	},
 	{
-		usage: `${ DEV_ENVIRONMENT_FULL_COMMAND } create --multisite=subdirectory --wordpress="5.8" --app-code="~/git/my_code"`,
+		usage: `vip @example-app.production dev-env create --slug=example-site --app-code=/Users/example/Desktop/example-repo`,
 		description:
-			'Creates a local multisite dev environment with a subdirectory URL structure using WP 5.8 and application code is expected to be in "~/git/my_code"',
+			'Create a new local environment with settings based on the production environment of the "example-app" application and load the locally git-cloned application repository "example-repo".',
 	},
 ];
 
-const cmd = command()
-	.option( 'slug', 'Custom name of the dev environment', undefined, processSlug )
-	.option( 'title', 'Title for the WordPress site' )
-	.option( 'multisite', 'Enable multisite install', undefined, processStringOrBooleanOption );
+const cmd = command( {
+	usage,
+} )
+	.option(
+		'slug',
+		'A unique name for a local environment. Default is "vip-local".',
+		undefined,
+		processSlug
+	)
+	.option( 'title', 'A descriptive value for the WordPress Site Title. Default is "VIP Dev").' )
+	.option(
+		'multisite',
+		'Create environment as a multisite. Accepts "y" for a subdomain multisite, "subdirectory" (recommended) for a subdirectory multisite, or "false". Default is "y".',
+		undefined,
+		processStringOrBooleanOption
+	);
 
 addDevEnvConfigurationOptions( cmd );
 
@@ -155,7 +162,7 @@ cmd.argv( process.argv, async ( arg, opt ) => {
 		const message =
 			'\n' +
 			chalk.green( '✓' ) +
-			` environment created.\n\nTo start it please run:\n\n${ startCommand }\n`;
+			` environment created.\n\nTo start the environment run:\n\n${ startCommand }\n`;
 		console.log( message );
 
 		await trackEvent( 'dev_env_create_command_success', trackingInfo );

src/bin/vip-dev-env-destroy.js

@@ -4,7 +4,6 @@ import chalk from 'chalk';
 import debugLib from 'debug';
 
 import command from '../lib/cli/command';
-import { DEV_ENVIRONMENT_FULL_COMMAND } from '../lib/constants/dev-environment';
 import {
 	getEnvTrackingInfo,
 	getEnvironmentName,
@@ -17,21 +16,36 @@ import { bootstrapLando } from '../lib/dev-environment/dev-environment-lando';
 import { trackEvent } from '../lib/tracker';
 
 const debug = debugLib( '@automattic/vip:bin:dev-environment' );
+const exampleUsage = 'vip dev-env destroy';
+const usage = 'vip dev-env destroy';
 
 const examples = [
 	{
-		usage: `${ DEV_ENVIRONMENT_FULL_COMMAND } destroy`,
-		description: 'Destroys the default local dev environment',
+		usage: `${ exampleUsage } --slug=example-site`,
+		description:
+			'Completely remove a local environment named "example-site" by removing all Docker containers, volumes, and configuration files.',
 	},
 	{
-		usage: `${ DEV_ENVIRONMENT_FULL_COMMAND } destroy --slug=foo`,
-		description: 'Destroys a local dev environment named foo',
+		usage: `${ exampleUsage } --soft --slug=example-site`,
+		description:
+			'Remove the Docker containers and volumes of a local environment named "example-site" but preserve the configuration files.\n' +
+			'      * The preserved configuration files allow the local environment to be restarted with new Docker containers and volumes.',
 	},
 ];
 
-command()
-	.option( 'slug', 'Custom name of the dev environment', undefined, processSlug )
-	.option( 'soft', 'Keep config files needed to start an environment intact' )
+command( {
+	usage,
+} )
+	.option(
+		'slug',
+		'A unique name for a local environment. Default is "vip-local".',
+		undefined,
+		processSlug
+	)
+	.option(
+		'soft',
+		'Preserve an environment’s configuration files; allows an environment to be regenerated with the start command.'
+	)
 	.examples( examples )
 	.argv( process.argv, async ( arg, opt ) => {
 		const slug = await getEnvironmentName( opt );

src/bin/vip-dev-env-exec.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 
 import command from '../lib/cli/command';
-import { DEV_ENVIRONMENT_FULL_COMMAND } from '../lib/constants/dev-environment';
 import {
 	getEnvTrackingInfo,
 	getEnvironmentName,
@@ -15,25 +14,45 @@ import { bootstrapLando, isEnvUp } from '../lib/dev-environment/dev-environment-
 import { trackEvent } from '../lib/tracker';
 import UserError from '../lib/user-error';
 
+const exampleUsage = 'vip dev-env exec';
+const usage = 'vip dev-env exec';
+
 const examples = [
 	{
-		usage: `${ DEV_ENVIRONMENT_FULL_COMMAND } exec -- wp post list`,
-		description: 'Use dev-environment to run `wp post list`',
+		usage: `${ exampleUsage } --slug=example-site -- wp post list`,
+		description:
+			'Run a WP-CLI command against a local environment named "example-site".\n' +
+			'      * A double dash ("--") must separate the arguments of "vip" from those of the "wp" command.',
 	},
 	{
-		usage: `${ DEV_ENVIRONMENT_FULL_COMMAND } exec --slug my_site -- wp post list --posts_per_page=500`,
-		description: 'Use dev-environment "my-site" to run `wp post list --posts_per_page=500`',
+		usage: `${ exampleUsage } --slug=example-site -- wp user list --url=example.example-site.vipdev.lndo.site`,
+		description:
+			'Target the WP-CLI command against the network site "example.example-site.vipdev.lndo.site" of a local multisite environment.',
 	},
 	{
-		usage: `${ DEV_ENVIRONMENT_FULL_COMMAND } exec --slug my_site -- wp shell`,
-		description: 'Use dev-environment "my_site" to run interactive wp shell',
+		usage: `${ exampleUsage } --slug=example-site -- wp shell`,
+		description:
+			'Run the WP-CLI command "wp shell" against a local environment to open an interactive PHP console.',
 	},
 ];
 
-command( { wildcardCommand: true } )
-	.option( 'slug', 'Custom name of the dev environment', undefined, processSlug )
-	.option( 'force', 'Disable validations before task execution', undefined, processBooleanOption )
-	.option( 'quiet', 'Suppress output', undefined, processBooleanOption )
+command( {
+	wildcardCommand: true,
+	usage,
+} )
+	.option(
+		'slug',
+		'A unique name for a local environment. Default is "vip-local".',
+		undefined,
+		processSlug
+	)
+	.option(
+		'force',
+		'Skip validation for a local environment to be in a running state.',
+		undefined,
+		processBooleanOption
+	)
+	.option( 'quiet', 'Suppress informational messages.', undefined, processBooleanOption )
 	.examples( examples )
 	.argv( process.argv, async ( unmatchedArgs, opt ) => {
 		const slug = await getEnvironmentName( opt );
@@ -49,7 +68,7 @@ command( { wildcardCommand: true } )
 			const argSplitterFound = argSplitterIx > -1;
 			if ( unmatchedArgs.length > 0 && ! argSplitterFound ) {
 				throw new Error(
-					'Please provide "--" argument to separate arguments for "vip" and command to be executed (see "--help" for examples)'
+					'A double dash ("--") must separate the arguments of "vip" from those of the "wp" command. Run "vip dev-env exec --help" for examples.'
 				);
 			}
 
@@ -62,7 +81,9 @@ command( { wildcardCommand: true } )
 			if ( ! opt.force ) {
 				const isUp = await isEnvUp( lando, getEnvironmentPath( slug ) );
 				if ( ! isUp ) {
-					throw new UserError( 'Environment needs to be started before running a command' );
+					throw new UserError(
+						'A WP-CLI command can only be executed on a running local environment.'
+					);
 				}
 			}
 

src/bin/vip-dev-env-import-media.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 
 import command from '../lib/cli/command';
-import { DEV_ENVIRONMENT_FULL_COMMAND } from '../lib/constants/dev-environment';
 import {
 	getEnvironmentName,
 	getEnvTrackingInfo,
@@ -11,24 +10,28 @@ import {
 import { importMediaPath } from '../lib/dev-environment/dev-environment-core';
 import { trackEvent } from '../lib/tracker';
 
+const exampleUsage = 'vip dev-env import media';
+const usage = 'vip dev-env import media';
+
 const examples = [
 	{
-		usage: `${ DEV_ENVIRONMENT_FULL_COMMAND } import media path/to/wp-content/uploads`,
-		description:
-			'Import contents of the given WP uploads folder file into the media library of the default dev environment',
-	},
-	{
-		usage: `${ DEV_ENVIRONMENT_FULL_COMMAND } import media path/to/wp-content/uploads --slug=mysite`,
+		usage: `${ exampleUsage } /Users/example/Desktop/uploads --slug="example-site"`,
 		description:
-			'Import contents of the given WP uploads folder file into the media library of a dev environment named `mysite`',
+			'Import the contents of the "uploads" directory from a path on the user\'s local machine to the "/wp-content/uploads" directory of the local environment named "example-site".',
 	},
 ];
 
 command( {
 	requiredArgs: 1,
+	usage,
 } )
 	.examples( examples )
-	.option( 'slug', 'Custom name of the dev environment', undefined, processSlug )
+	.option(
+		'slug',
+		'A unique name for a local environment. Default is "vip-local".',
+		undefined,
+		processSlug
+	)
 	.argv( process.argv, async ( unmatchedArgs, opt ) => {
 		const [ filePath ] = unmatchedArgs;
 		const slug = await getEnvironmentName( opt );

src/bin/vip-dev-env-import-sql.js

@@ -2,7 +2,6 @@
 
 import { DevEnvImportSQLCommand } from '../commands/dev-env-import-sql';
 import command from '../lib/cli/command';
-import { DEV_ENVIRONMENT_FULL_COMMAND } from '../lib/constants/dev-environment';
 import {
 	getEnvTrackingInfo,
 	handleCLIException,
@@ -11,36 +10,58 @@ import {
 } from '../lib/dev-environment/dev-environment-cli';
 import { makeCommandTracker } from '../lib/tracker';
 
+const exampleUsage = 'vip dev-env import sql';
+const usage = 'vip dev-env import sql';
+
 const examples = [
 	{
-		usage: `${ DEV_ENVIRONMENT_FULL_COMMAND } import sql some-wp-db-file.sql`,
-		description: 'Import the contents of a WordPress database from an SQL file',
+		usage: `${ exampleUsage } /Users/example/Downloads/file.sql --slug="example-site"`,
+		description:
+			'Import the SQL file named "file.sql" from a path on the user\'s local machine to a running local environment named "example-site".',
+	},
+	{
+		usage: `${ exampleUsage } /Users/example/Downloads/file.sql --search-replace="example-site.com,example-site.vipdev.lndo.site" --slug="example-site"`,
+		description:
+			'Search for the string "example-site.com" in the SQL file and replace it with "example-site.vipdev.lndo.site" during the import.',
 	},
 	{
-		usage: `${ DEV_ENVIRONMENT_FULL_COMMAND } import sql wordpress.sql --slug=my_site`,
-		description: 'Import the contents of a WordPress database from an SQL file into `my_site`',
+		usage: `${ exampleUsage } /Users/example/Downloads/file.sql --search-replace="example-site.com,example-site.vipdev.lndo.site" --skip-reindex --slug="example-site"`,
+		description:
+			'Import the SQL file to a local environment with Elasticsearch enabled, and do not reindex after the import is completed.',
 	},
 	{
-		usage: `${ DEV_ENVIRONMENT_FULL_COMMAND } import sql wordpress.sql --search-replace="testsite.com,test-site.go-vip.net"`,
+		usage: `${ exampleUsage } /Users/example/Downloads/file.sql --search-replace="example-site.com,example-site.vipdev.lndo.site" --in-place`,
 		description:
-			'Import the contents of a WordPress database from an SQL file and replace the occurrences of `testsite.com` with `test-site.go-vip.net`',
+			'Perform the search and replace operation on the local SQL file ("file.sql"), save the changes, and import the updated file to the local environment.',
 	},
 	{
-		usage: `${ DEV_ENVIRONMENT_FULL_COMMAND } import sql wordpress.sql --search-replace="testsite.com,test-site.go-vip.net" --in-place`,
+		usage: `${ exampleUsage } /Users/example/Downloads/file.sql --search-replace="example-site.com/site-three,site-three.example-site.vipdev.lndo.site" --search-replace="example-site.com,example-site.vipdev.lndo.site" --slug="example-site"`,
 		description:
-			'Import the contents of a WordPress database from an SQL file and replace the occurrences of `testsite.com` with `test-site.go-vip.net` in place (modifies the original SQL file)',
+			'Search and replace 2 pairs of strings during the import of the SQL file to a local multisite environment.',
 	},
 ];
 
 command( {
 	requiredArgs: 1,
+	usage,
 } )
-	.option( 'slug', 'Custom name of the dev environment', undefined, processSlug )
-	.option( [ 'r', 'search-replace' ], 'Perform Search and Replace on the specified SQL file' )
-	.option( 'in-place', 'Search and Replace explicitly on the given input file' )
-	.option( 'skip-validate', 'Do not perform file validation' )
-	.option( [ 'k', 'skip-reindex' ], 'Do not reindex data in Elasticsearch after import' )
-	.option( 'quiet', 'Suppress prompts and informational messages' )
+	.option(
+		'slug',
+		'A unique name for a local environment. Default is "vip-local".',
+		undefined,
+		processSlug
+	)
+	.option(
+		[ 'r', 'search-replace' ],
+		'Search for a string in the SQL file and replace it with a new string.'
+	)
+	.option(
+		'in-place',
+		'Perform a search and replace operation on the local SQL file and save the results.'
+	)
+	.option( 'skip-validate', 'Skip file validation.' )
+	.option( [ 'k', 'skip-reindex' ], 'Skip Elasticsearch reindex after import.' )
+	.option( 'quiet', 'Skip confirmation and suppress informational messages.' )
 	.examples( examples )
 	.argv( process.argv, async ( unmatchedArgs, opt ) => {
 		const [ fileName ] = unmatchedArgs;

src/bin/vip-dev-env-import.js

@@ -1,28 +1,28 @@
 #!/usr/bin/env node
 
 import command from '../lib/cli/command';
-import { DEV_ENVIRONMENT_FULL_COMMAND } from '../lib/constants/dev-environment';
+
+const exampleUsage = 'vip dev-env import';
+const usage = 'vip dev-env import';
 
 const examples = [
 	{
-		usage: `${ DEV_ENVIRONMENT_FULL_COMMAND } import sql file.sql`,
-		description: 'Import the given SQL file to your site',
+		usage: `${ exampleUsage } sql /Users/example/Downloads/file.sql`,
+		description:
+			'Import the SQL file named "file.sql" from a path on the user\'s local machine to a running local environment.',
 	},
 	{
-		usage: `${ DEV_ENVIRONMENT_FULL_COMMAND } import media path/to/wp-content/uploads`,
+		usage: `${ exampleUsage } media /Users/example/Desktop/uploads`,
 		description:
-			'Import contents of the given WP uploads folder file into the media library of the default dev environment',
+			'Import the contents of the "uploads" directory from a path on the user\'s local machine to the "/wp-content/uploads" directory of a running local environment.',
 	},
 ];
 
 command( {
 	requiredArgs: 1,
+	usage,
 } )
 	.examples( examples )
-	.command( 'sql', 'Import SQL to your dev-env database from a file' )
-	.command(
-		'media',
-		'Import media files to the dev environment of your application from a compressed web archive. ' +
-			'This command will copy the contents of a folder to the `uploads` folder of the target dev environment.'
-	)
+	.command( 'sql', 'Import a SQL file to a running local environment.' )
+	.command( 'media', 'Import media files to a running local environment.' )
 	.argv( process.argv );