Merge pull request #1746 from Automattic/update/docs-pt-vip-config

Update/docs pt vip config

__tests__/bin/vip-config-envvar-delete.js

@@ -63,7 +63,7 @@ describe( 'deleteEnvVarCommand', () => {
 	let args;
 	let opts;
 	const eventPayload = expect.objectContaining( {
-		command: expect.stringContaining( 'vip @mysite.develop config envvar delete' ),
+		command: expect.stringContaining( 'vip config envvar delete' ),
 	} );
 	const executeEvent = [ 'envvar_delete_command_execute', eventPayload ];
 	const successEvent = [ 'envvar_delete_command_success', eventPayload ];

__tests__/bin/vip-config-envvar-get-all.js

@@ -59,7 +59,7 @@ describe( 'getAllEnvVarsCommand', () => {
 		format: 'csv',
 	};
 	const eventPayload = expect.objectContaining( {
-		command: 'vip @mysite.develop config envvar get-all',
+		command: 'vip config envvar get-all',
 	} );
 	const executeEvent = [ 'envvar_get_all_command_execute', eventPayload ];
 	const successEvent = [ 'envvar_get_all_command_success', eventPayload ];

__tests__/bin/vip-config-envvar-get.js

@@ -53,7 +53,7 @@ describe( 'getEnvVarCommand', () => {
 		},
 	};
 	const eventPayload = expect.objectContaining( {
-		command: 'vip @mysite.develop config envvar get HELLO',
+		command: 'vip config envvar get HELLO',
 	} );
 	const executeEvent = [ 'envvar_get_command_execute', eventPayload ];
 	const successEvent = [ 'envvar_get_command_success', eventPayload ];

__tests__/bin/vip-config-envvar-list.js

@@ -59,7 +59,7 @@ describe( 'listEnvVarsCommand', () => {
 		format: 'csv',
 	};
 	const eventPayload = expect.objectContaining( {
-		command: 'vip @mysite.develop config envvar list',
+		command: 'vip config envvar list',
 	} );
 	const executeEvent = [ 'envvar_list_command_execute', eventPayload ];
 	const successEvent = [ 'envvar_list_command_success', eventPayload ];

__tests__/bin/vip-config-envvar-set.js

@@ -69,7 +69,7 @@ describe( 'setEnvVarCommand', () => {
 	let args;
 	let opts;
 	const eventPayload = expect.objectContaining( {
-		command: expect.stringContaining( 'vip @mysite.develop config envvar set' ),
+		command: expect.stringContaining( 'vip config envvar set' ),
 	} );
 	const executeEvent = [ 'envvar_set_command_execute', eventPayload ];
 	const successEvent = [ 'envvar_set_command_success', eventPayload ];

src/bin/vip-config-envvar-delete.js

@@ -8,13 +8,14 @@ import { cancel, confirm, promptForValue } from '../lib/envvar/input';
 import { debug, getEnvContext } from '../lib/envvar/logging';
 import { trackEvent } from '../lib/tracker';
 
-const baseUsage = 'vip @mysite.develop config envvar delete';
+const baseUsage = 'vip config envvar delete';
+const exampleUsage = 'vip @example-app.develop config envvar delete';
 
 // Command examples
 const examples = [
 	{
-		usage: `${ baseUsage } MY_VARIABLE`,
-		description: 'Permanently deletes the environment variable "MY_VARIABLE"',
+		usage: `${ exampleUsage } MY_VARIABLE`,
+		description: 'Delete the environment variable "MY_VARIABLE" from the environment.',
 	},
 ];
 

src/bin/vip-config-envvar-get-all.js

@@ -8,13 +8,26 @@ import { appQuery, getEnvVars } from '../lib/envvar/api';
 import { debug, getEnvContext } from '../lib/envvar/logging';
 import { trackEvent } from '../lib/tracker';
 
-const usage = 'vip @mysite.develop config envvar get-all';
+const exampleUsage = 'vip @example-app.develop config envvar get-all';
+const usage = 'vip config envvar get-all';
 
 // Command examples
 const examples = [
 	{
-		usage,
-		description: 'Get the values of all environment variables',
+		usage: exampleUsage,
+		description: 'Retrieve a list of all environment variables in the default table format.',
+	},
+	{
+		usage: `${ exampleUsage } --format=csv`,
+		description: 'Retrieve a list of all environment variables in CSV format.',
+	},
+	{
+		usage: `${ exampleUsage } --format=ids`,
+		description: 'Retrieve a list of all environment variable names as a space separated list.',
+	},
+	{
+		usage: `${ exampleUsage } --format=keyValue`,
+		description: 'Retrieve a list of all environment variables as a key value list.',
 	},
 ];
 

src/bin/vip-config-envvar-get.js

@@ -7,13 +7,14 @@ import { appQuery, getEnvVar } from '../lib/envvar/api';
 import { debug, getEnvContext } from '../lib/envvar/logging';
 import { trackEvent } from '../lib/tracker';
 
-const baseUsage = 'vip @mysite.develop config envvar get';
+const baseUsage = 'vip config envvar get';
+const exampleUsage = 'vip @example-app.develop config envvar get';
 
 // Command examples
 const examples = [
 	{
-		usage: `${ baseUsage } MY_VARIABLE`,
-		description: 'Get the value of the environment variable "MY_VARIABLE"',
+		usage: `${ exampleUsage } MY_VARIABLE`,
+		description: 'Retrieve the value of the environment variable "MY_VARIABLE".',
 	},
 ];
 

src/bin/vip-config-envvar-list.js

@@ -8,13 +8,14 @@ import { appQuery, listEnvVars } from '../lib/envvar/api';
 import { debug, getEnvContext } from '../lib/envvar/logging';
 import { trackEvent } from '../lib/tracker';
 
-const usage = 'vip @mysite.develop config envvar list';
+const usage = 'vip config envvar list';
+const exampleUsage = 'vip @example-app.develop config envvar list';
 
 // Command examples
 const examples = [
 	{
-		usage,
-		description: 'Lists all environment variables (names only)',
+		usage: exampleUsage,
+		description: 'List the names of all environment variables on an environment.',
 	},
 ];
 

src/bin/vip-config-envvar-set.js

@@ -9,15 +9,22 @@ import { debug, getEnvContext } from '../lib/envvar/logging';
 import { readVariableFromFile } from '../lib/envvar/read-file';
 import { trackEvent } from '../lib/tracker';
 
-const baseUsage = 'vip @mysite.develop config envvar set';
+const baseUsage = 'vip config envvar set';
+const exampleUsage = 'vip @example-app.develop config envvar set';
 
 const NEW_RELIC_ENVVAR_KEY = 'NEW_RELIC_LICENSE_KEY';
 
 // Command examples
 const examples = [
 	{
-		usage: `${ baseUsage } MY_VARIABLE`,
-		description: 'Sets the environment variable "MY_VARIABLE" and prompts for its value',
+		usage: `${ exampleUsage } MY_VARIABLE`,
+		description:
+			'Add or update the environment variable "MY_VARIABLE" and assign its value at the prompt.',
+	},
+	{
+		usage: `${ exampleUsage } MULTILINE_ENV_VAR --from-file=envvar-value.txt`,
+		description:
+			'Add or update the environment variable "MULTILINE_ENV_VAR" and assign the multiline contents of local file envvar-value.txt as its value.',
 	},
 ];
 
@@ -52,7 +59,7 @@ export async function setEnvVarCommand( arg, opt ) {
 		await trackEvent( 'envvar_set_newrelic_key', trackingParams );
 		console.log(
 			chalk.bold.red( 'Setting the New Relic key is not permitted.' ),
-			'If you want to set your own New Relic key, please contact our support team through the usual channels.'
+			'If you want to set your own New Relic key, please contact WordPress VIP support.'
 		);
 		process.exit( 1 );
 	}

src/bin/vip-config-envvar.js

@@ -2,12 +2,42 @@
 
 import command from '../lib/cli/command';
 
+const usage = 'vip config envvar';
+const exampleUsage = 'vip @example-app.develop config envvar';
+
+// Command examples
+const examples = [
+	{
+		usage: `${ exampleUsage } delete MY_VARIABLE`,
+		description: 'Delete the environment variable "MY_VARIABLE" from the environment.',
+	},
+	{
+		usage: `${ exampleUsage } get MY_VARIABLE`,
+		description: 'Retrieve the value of the environment variable "MY_VARIABLE".',
+	},
+	{
+		usage: `${ exampleUsage } get-all`,
+		description: 'Retrieve a list of all environment variables in the default table format.',
+	},
+	{
+		usage: `${ exampleUsage } list`,
+		description: 'List the names of all environment variables.',
+	},
+	{
+		usage: `${ exampleUsage } set MY_VARIABLE`,
+		description:
+			'Add or update the environment variable "MY_VARIABLE" and assign its value at the prompt.',
+	},
+];
+
 command( {
 	requiredArgs: 0,
+	usage,
 } )
-	.command( 'delete', 'Permanently delete an environment variable' )
-	.command( 'get', 'Get the value of an environment variable' )
-	.command( 'get-all', 'Get the values of all environment variable' )
-	.command( 'list', 'List the names of all environment variables' )
-	.command( 'set', 'Add or update an environment variable' )
+	.command( 'delete', 'Delete an environment variable.' )
+	.command( 'get', 'Retrieve the value of an environment variable.' )
+	.command( 'get-all', 'Retrieve the names and values of all environment variables.' )
+	.command( 'list', 'List the names of all environment variables.' )
+	.command( 'set', 'Add or update an environment variable.' )
+	.examples( examples )
 	.argv( process.argv );

src/bin/vip-config-software-get.js

@@ -6,17 +6,36 @@ import { appQuery, appQueryFragments, formatSoftwareSettings } from '../lib/conf
 import { trackEvent } from '../lib/tracker';
 import UserError from '../lib/user-error';
 
+const usage = 'vip config software get <wordpress|php|nodejs|muplugins>';
+const exampleUsage = 'vip @example-app.develop config software get';
+const exampleUsageNode = 'vip @example-node-app.develop config software get';
+
 // Command examples
 const examples = [
 	{
-		usage:
-			'vip @mysite.develop config software get wordpress --include available_versions --format json',
+		usage: exampleUsage,
+		description:
+			'Retrieve a list of the current versions of all environment software in the default table format.',
+	},
+	{
+		usage: `${ exampleUsage } --format=csv`,
 		description:
-			'Read current software settings for WordPress in JSON format including available versions',
+			'Retrieve a list of the current versions of all environment software in CSV format.',
 	},
 	{
-		usage: 'vip @mysite.develop config software get',
-		description: 'Read current software settings for all components',
+		usage: `${ exampleUsage } wordpress --include=available_versions`,
+		description:
+			'Retrieve the current version of WordPress for a WordPress environment and a list of available versions in the default table format.',
+	},
+	{
+		usage: `${ exampleUsage } php --include=available_versions`,
+		description:
+			'Retrieve the current version of PHP for a WordPress environment and a list of available versions in the default table format.',
+	},
+	{
+		usage: `${ exampleUsageNode } nodejs --include=available_versions --format=json`,
+		description:
+			'Retrieve the current version of Node.js for a Node.js environment and a list of available versions in JSON format.',
 	},
 ];
 
@@ -29,11 +48,11 @@ command( {
 	envContext: true,
 	wildcardCommand: true,
 	format: true,
-	usage: 'vip @mysite.develop config software get <wordpress|php|nodejs|muplugins>',
+	usage,
 } )
 	.option(
 		'include',
-		`Extra information to be included. Valid values: ${ VALID_INCLUDES.join( ',' ) }`
+		`Retrieve additional data of a specific type. Supported values: ${ VALID_INCLUDES.join( ',' ) }`
 	)
 	.examples( examples )
 	.argv( process.argv, async ( arg, opt ) => {

src/bin/vip-config-software-update.js

@@ -22,23 +22,38 @@ const UPDATE_SOFTWARE_PROGRESS_STEPS = [
 	{ id: 'process', name: 'Process software update' },
 ];
 
+const usage = 'vip config software update <wordpress|php|nodejs|muplugins> <version>';
+const exampleUsage = 'vip @example-app.develop config software update';
+const exampleUsageNode = 'vip @example-node-app.develop config software update';
+
+const examples = [
+	{
+		usage: `${ exampleUsage } wordpress 6.4`,
+		description: 'Update the version of WordPress on a WordPress environment to 6.4.x.',
+	},
+	{
+		usage: `${ exampleUsage } wordpress managed_latest`,
+		description:
+			'Update a WordPress environment to the latest major version of WordPress, and automatically update WordPress to the next major version on a continual basis.',
+	},
+	{
+		usage: `${ exampleUsage } php 8.3`,
+		description: 'Update the version of PHP on a WordPress environment to 8.3.x.',
+	},
+	{
+		usage: `${ exampleUsageNode } nodejs 18`,
+		description: 'Update the version of Node.js on a Node.js environment to 18.x.',
+	},
+];
+
 const cmd = command( {
 	appContext: true,
 	appQuery,
 	appQueryFragments,
 	envContext: true,
 	wildcardCommand: true,
-	usage: 'vip @mysite.develop config software update <wordpress|php|nodejs|muplugins> <version>',
-} ).examples( [
-	{
-		usage: 'vip @mysite.develop config software update wordpress 6.0',
-		description: 'Update WordPress to 6.0.x',
-	},
-	{
-		usage: 'vip @mysite.develop config software update nodejs 16',
-		description: 'Update Node.js to v16',
-	},
-] );
+	usage,
+} ).examples( examples );
 cmd.option( 'yes', 'Auto-confirm update' );
 cmd.argv( process.argv, async ( arg, opt ) => {
 	const { app, env } = opt;

src/bin/vip-config-software.js

@@ -2,10 +2,37 @@
 
 import command from '../lib/cli/command';
 
+const usage = 'vip config software';
+const exampleUsage = 'vip @example-app.develop config software';
+const exampleUsageNode = 'vip @example-node-app.develop config software';
+
+// Command examples
+const examples = [
+	{
+		usage: `${ exampleUsage } get`,
+		description:
+			'Retrieve a list of the current versions of all environment software in the default table format.',
+	},
+	{
+		usage: `${ exampleUsage } get wordpress --include=available_versions`,
+		description:
+			'Retrieve the current version of WordPress for a WordPress environment and a list of available versions in the default table format.',
+	},
+	{
+		usage: `${ exampleUsage } update wordpress 6.4`,
+		description: 'Update the version of WordPress on a WordPress environment to 6.4.x.',
+	},
+	{
+		usage: `${ exampleUsageNode } update nodejs 18`,
+		description: 'Update the version of Node.js on a Node.js environment to 18.x.',
+	},
+];
+
 command( {
 	requiredArgs: 1,
-	usage: 'vip @mysite.develop config software <action>',
+	usage,
 } )
-	.command( 'get', 'Read current software settings' )
-	.command( 'update', 'Update software settings' )
+	.command( 'get', 'Retrieve the current versions of environment software.' )
+	.command( 'update', 'Update the version of software running on an environment.' )
+	.examples( examples )
 	.argv( process.argv );

src/bin/vip-config.js

@@ -2,11 +2,28 @@
 
 import command from '../lib/cli/command';
 
+const usage = 'vip config';
+const exampleUsage = 'vip @example-app.develop config';
+
+// Command examples
+const examples = [
+	{
+		usage: `${ exampleUsage } envvar list`,
+		description: 'List the names of all environment variables on the environment.',
+	},
+	{
+		usage: `${ exampleUsage } software get`,
+		description: 'Retrieve the current versions of all environment software.',
+	},
+];
+
 command( {
 	requiredArgs: 2,
+	usage,
 } )
-	.command( 'envvar', 'Manage environment variables for an application environment' )
-	.command( 'software', 'Software management' )
+	.command( 'envvar', 'Manage environment variables for an environment.' )
+	.command( 'software', 'Manage versions of software for an environment.' )
+	.examples( examples )
 	.argv( process.argv, async () => {
 		process.exit( 0 );
 	} );

src/bin/vip.js

@@ -29,7 +29,7 @@ const runCmd = async function () {
 		.command( 'app', 'List and modify your VIP applications' )
 		.command( 'backup', 'Generate a backup for VIP applications' )
 		.command( 'cache', 'Manage page cache for your VIP applications' )
-		.command( 'config', 'Set configuration for your VIP applications' )
+		.command( 'config', 'Manage environment configurations.' )
 		.command( 'dev-env', 'Use local dev-environment' )
 		.command( 'export', 'Export a copy of data associated with an environment.' )
 		.command( 'import', 'Import media or SQL files into your VIP applications' )