Deprecate env add in favor of env set

Change-type: patch

completion/_balena

@@ -16,7 +16,7 @@ _balena() {
   config_cmds=( generate inject read reconfigure write )
   device_cmds=( deactivate detect identify init list local-mode logs move os-update pin public-url purge reboot register rename restart rm shutdown ssh start-service stop-service track-fleet )
   devices_cmds=( supported )
-  env_cmds=( add list rename rm )
+  env_cmds=( list rename rm set )
   fleet_cmds=( create list pin purge rename restart rm track-latest )
   internal_cmds=( osinit )
   local_cmds=( configure flash )

completion/balena-completion.bash

@@ -15,7 +15,7 @@ _balena_complete()
   config_cmds="generate inject read reconfigure write"
   device_cmds="deactivate detect identify init list local-mode logs move os-update pin public-url purge reboot register rename restart rm shutdown ssh start-service stop-service track-fleet"
   devices_cmds="supported"
-  env_cmds="add list rename rm"
+  env_cmds="list rename rm set"
   fleet_cmds="create list pin purge rename restart rm track-latest"
   internal_cmds="osinit"
   local_cmds="configure flash"

docs/balena-cli.md

@@ -222,10 +222,10 @@ are encouraged to regularly update the balena CLI to the latest version.
 
 - Environment Variables
 
-	- [env add <name> [value]](#env-add-name-value)
 	- [env list](#env-list)
 	- [env rename <id> <value>](#env-rename-id-value)
 	- [env rm <id>](#env-rm-id)
+	- [env set <name> [value]](#env-set-name-value)
 
 - Fleets
 
@@ -1959,81 +1959,6 @@ produce JSON output instead of tabular output
 
 # Environment Variables
 
-## env add <name> [value]
-
-Add an environment or config variable to one or more fleets, devices or
-services, as selected by the respective command-line options. Either the
---fleet or the --device option must be provided,  and either may be be
-used alongside the --service option to define a service-specific variable.
-(A service corresponds to a Docker image/container in a microservices fleet.)
-When the --service option is used in conjunction with the --device option,
-the service variable applies to the selected device only.  Otherwise, it
-applies to all devices of the selected fleet. If the --service option is
-omitted, the variable applies to all services.
-
-If VALUE is omitted, the CLI will attempt to use the value of the environment
-variable of same name in the CLI process' environment. In this case, a warning
-message will be printed. Use `--quiet` to suppress it.
-
-'BALENA_' or 'RESIN_' are reserved variable name prefixes used to identify
-"configuration variables". Configuration variables control balena platform
-features and are treated specially by balenaOS and the balena supervisor
-running on devices. They are also stored differently in the balenaCloud API
-database. Configuration variables cannot be set for specific services,
-therefore the --service option cannot be used when the variable name starts
-with a reserved prefix. When defining custom fleet variables, please avoid
-these reserved prefixes.
-
-Fleets may be specified by fleet name or slug. Fleet slugs are
-the recommended option, as they are unique and unambiguous. Slugs can be
-listed with the `balena fleet list` command. Note that slugs may change if the
-fleet is renamed. Fleet names are not unique and may result in  "Fleet is
-ambiguous" errors at any time (even if it "used to work in the past"), for
-example if the name clashes with a newly created public fleet, or with fleets
-from other balena accounts that you may be invited to join under any role.
-For this reason, fleet names are especially discouraged in scripts (e.g. CI
-environments).
-
-Examples:
-
-	$ balena env add TERM --fleet MyFleet
-	$ balena env add EDITOR vim -f myorg/myfleet
-	$ balena env add EDITOR vim --fleet MyFleet,MyFleet2
-	$ balena env add EDITOR vim --fleet MyFleet --service MyService
-	$ balena env add EDITOR vim --fleet MyFleet,MyFleet2 --service MyService,MyService2
-	$ balena env add EDITOR vim --device 7cf02a6
-	$ balena env add EDITOR vim --device 7cf02a6,d6f1433
-	$ balena env add EDITOR vim --device 7cf02a6 --service MyService
-	$ balena env add EDITOR vim --device 7cf02a6,d6f1433 --service MyService,MyService2
-
-### Arguments
-
-#### NAME
-
-environment or config variable name
-
-#### VALUE
-
-variable value; if omitted, use value from this process' environment
-
-### Options
-
-#### -f, --fleet FLEET
-
-fleet name or slug (preferred)
-
-#### -d, --device DEVICE
-
-device UUID
-
-#### -q, --quiet
-
-suppress warning messages
-
-#### -s, --service SERVICE
-
-service name
-
 ## env list
 
 List the environment or configuration variables of a fleet, device or
@@ -2239,6 +2164,81 @@ select a service variable (may be used together with the --device option)
 
 do not prompt for confirmation before deleting the variable
 
+## env set <name> [value]
+
+Add or update an environment or config variable to one or more fleets, devices or
+services, as selected by the respective command-line options. Either the
+--fleet or the --device option must be provided,  and either may be be
+used alongside the --service option to define a service-specific variable.
+(A service corresponds to a Docker image/container in a microservices fleet.)
+When the --service option is used in conjunction with the --device option,
+the service variable applies to the selected device only.  Otherwise, it
+applies to all devices of the selected fleet. If the --service option is
+omitted, the variable applies to all services.
+
+If VALUE is omitted, the CLI will attempt to use the value of the environment
+variable of same name in the CLI process' environment. In this case, a warning
+message will be printed. Use `--quiet` to suppress it.
+
+'BALENA_' or 'RESIN_' are reserved variable name prefixes used to identify
+"configuration variables". Configuration variables control balena platform
+features and are treated specially by balenaOS and the balena supervisor
+running on devices. They are also stored differently in the balenaCloud API
+database. Configuration variables cannot be set for specific services,
+therefore the --service option cannot be used when the variable name starts
+with a reserved prefix. When defining custom fleet variables, please avoid
+these reserved prefixes.
+
+Fleets may be specified by fleet name or slug. Fleet slugs are
+the recommended option, as they are unique and unambiguous. Slugs can be
+listed with the `balena fleet list` command. Note that slugs may change if the
+fleet is renamed. Fleet names are not unique and may result in  "Fleet is
+ambiguous" errors at any time (even if it "used to work in the past"), for
+example if the name clashes with a newly created public fleet, or with fleets
+from other balena accounts that you may be invited to join under any role.
+For this reason, fleet names are especially discouraged in scripts (e.g. CI
+environments).
+
+Examples:
+
+	$ balena env set TERM --fleet MyFleet
+	$ balena env set EDITOR vim -f myorg/myfleet
+	$ balena env set EDITOR vim --fleet MyFleet,MyFleet2
+	$ balena env set EDITOR vim --fleet MyFleet --service MyService
+	$ balena env set EDITOR vim --fleet MyFleet,MyFleet2 --service MyService,MyService2
+	$ balena env set EDITOR vim --device 7cf02a6
+	$ balena env set EDITOR vim --device 7cf02a6,d6f1433
+	$ balena env set EDITOR vim --device 7cf02a6 --service MyService
+	$ balena env set EDITOR vim --device 7cf02a6,d6f1433 --service MyService,MyService2
+
+### Arguments
+
+#### NAME
+
+environment or config variable name
+
+#### VALUE
+
+variable value; if omitted, use value from this process' environment
+
+### Options
+
+#### -f, --fleet FLEET
+
+fleet name or slug (preferred)
+
+#### -d, --device DEVICE
+
+device UUID
+
+#### -q, --quiet
+
+suppress warning messages
+
+#### -s, --service SERVICE
+
+service name
+
 # Fleets
 
 ## fleet create <name>

src/commands/env/set.ts

@@ -36,11 +36,14 @@ interface ArgsDef {
 	value?: string;
 }
 
-export default class EnvAddCmd extends Command {
+export default class EnvSetCmd extends Command {
+	public static aliases = ['env add'];
+	public static deprecateAliases = true;
+
 	public static description = stripIndent`
-		Add env or config variable to fleets, devices or services.
+		Add or update env or config variable to fleets, devices or services.
 
-		Add an environment or config variable to one or more fleets, devices or
+		Add or update an environment or config variable to one or more fleets, devices or
 		services, as selected by the respective command-line options. Either the
 		--fleet or the --device option must be provided,  and either may be be
 		used alongside the --service option to define a service-specific variable.
@@ -67,15 +70,15 @@ export default class EnvAddCmd extends Command {
 	`;
 
 	public static examples = [
-		'$ balena env add TERM --fleet MyFleet',
-		'$ balena env add EDITOR vim -f myorg/myfleet',
-		'$ balena env add EDITOR vim --fleet MyFleet,MyFleet2',
-		'$ balena env add EDITOR vim --fleet MyFleet --service MyService',
-		'$ balena env add EDITOR vim --fleet MyFleet,MyFleet2 --service MyService,MyService2',
-		'$ balena env add EDITOR vim --device 7cf02a6',
-		'$ balena env add EDITOR vim --device 7cf02a6,d6f1433',
-		'$ balena env add EDITOR vim --device 7cf02a6 --service MyService',
-		'$ balena env add EDITOR vim --device 7cf02a6,d6f1433 --service MyService,MyService2',
+		'$ balena env set TERM --fleet MyFleet',
+		'$ balena env set EDITOR vim -f myorg/myfleet',
+		'$ balena env set EDITOR vim --fleet MyFleet,MyFleet2',
+		'$ balena env set EDITOR vim --fleet MyFleet --service MyService',
+		'$ balena env set EDITOR vim --fleet MyFleet,MyFleet2 --service MyService,MyService2',
+		'$ balena env set EDITOR vim --device 7cf02a6',
+		'$ balena env set EDITOR vim --device 7cf02a6,d6f1433',
+		'$ balena env set EDITOR vim --device 7cf02a6 --service MyService',
+		'$ balena env set EDITOR vim --device 7cf02a6,d6f1433 --service MyService,MyService2',
 	];
 
 	public static args = {
@@ -92,7 +95,7 @@ export default class EnvAddCmd extends Command {
 
 	// Required for supporting empty string ('') `value` args.
 	public static strict = false;
-	public static usage = 'env add <name> [value]';
+	public static usage = 'env set <name> [value]';
 
 	public static flags = {
 		fleet: { ...cf.fleet, exclusive: ['device'] },
@@ -103,7 +106,7 @@ export default class EnvAddCmd extends Command {
 	};
 
 	public async run() {
-		const { args: params, flags: options } = await this.parse(EnvAddCmd);
+		const { args: params, flags: options } = await this.parse(EnvSetCmd);
 		const cmd = this;
 
 		if (!options.fleet && !options.device) {

src/hooks/prerun/track.ts

@@ -29,7 +29,7 @@ export const trackPromise = new Promise((resolve) => {
  * See: https://oclif.io/docs/hooks
  *
  * This hook is used to track CLI command signatures (usage analytics).
- * A command signature is something like "env add NAME [VALUE]". That's
+ * A command signature is something like "env set NAME [VALUE]". That's
  * literally so: 'NAME' and 'VALUE' are NOT replaced with actual values.
  */
 const hook: Hook<'prerun'> = async function (options) {

src/preparser.ts

@@ -44,7 +44,7 @@ export async function preparseArgs(argv: string[]): Promise<string[]> {
 		else if (['--help', '-h'].includes(cmdSlice[0])) {
 			cmdSlice[0] = 'help';
 		}
-		// convert e.g. 'balena help env add' to 'balena env add --help'
+		// convert e.g. 'balena help env set' to 'balena env set --help'
 		if (
 			cmdSlice.length > 1 &&
 			cmdSlice[0] === 'help' &&

src/utils/logger.ts

@@ -48,7 +48,7 @@ interface LoggerAdapter {
 class Logger {
 	public static readonly Level = Level;
 	// `Logger.command` is currently set in `preparser.ts`
-	public static command: string; // CLI cmd, e.g. 'push', 'env add', ...
+	public static command: string; // CLI cmd, e.g. 'push', 'env set', ...
 
 	public streams: {
 		build: NodeJS.ReadWriteStream;

src/utils/oclif-utils.ts

@@ -41,7 +41,7 @@ export class CommandHelp {
 	}
 }
 
-/** Convert e.g. 'env add NAME [VALUE]' to 'env add <name> [value]' */
+/** Convert e.g. 'env set NAME [VALUE]' to 'env set <name> [value]' */
 export function capitanoizeOclifUsage(
 	oclifUsage: string | string[] | undefined,
 ): string {

tests/commands/env/add.spec.ts

@@ -20,7 +20,7 @@ import { expect } from 'chai';
 import { BalenaAPIMock } from '../../nock/balena-api-mock';
 import { runCommand } from '../../helpers';
 
-describe('balena env add', function () {
+describe('balena env set', function () {
 	let api: BalenaAPIMock;
 
 	const fullUUID = 'f63fd7d7812c34c4c14ae023fdff05f5';
@@ -43,7 +43,7 @@ describe('balena env add', function () {
 			.post(/^\/v\d+\/device_environment_variable($|\?)/)
 			.reply(200, 'OK');
 
-		const { out, err } = await runCommand(`env add TEST 1 -d ${fullUUID}`);
+		const { out, err } = await runCommand(`env set TEST 1 -d ${fullUUID}`);
 
 		expect(out.join('')).to.equal('');
 		expect(err.join('')).to.equal('');
@@ -54,7 +54,7 @@ describe('balena env add', function () {
 		delete process.env.TEST_ENV_VAR_ADD_NO_VALUE_REJECTED;
 
 		const { out, err } = await runCommand(
-			`env add TEST_ENV_VAR_ADD_NO_VALUE_REJECTED -d ${fullUUID}`,
+			`env set TEST_ENV_VAR_ADD_NO_VALUE_REJECTED -d ${fullUUID}`,
 		);
 
 		expect(out.join('')).to.equal('');
@@ -75,7 +75,7 @@ describe('balena env add', function () {
 		process.env.TEST_ENV_VAR_ADD_NO_VALUE = '4';
 
 		const { out, err } = await runCommand(
-			`env add TEST_ENV_VAR_ADD_NO_VALUE -d ${fullUUID}`,
+			`env set TEST_ENV_VAR_ADD_NO_VALUE -d ${fullUUID}`,
 		);
 
 		delete process.env.TEST_ENV_VAR_ADD_NO_VALUE;
@@ -96,7 +96,7 @@ describe('balena env add', function () {
 			.reply(200, 'OK');
 
 		const { out, err } = await runCommand(
-			`env add TEST_EMPTY_STRING '' -d ${fullUUID}`,
+			`env set TEST_EMPTY_STRING '' -d ${fullUUID}`,
 		);
 
 		expect(out.join('')).to.equal('');

tests/commands/help.spec.ts

@@ -64,7 +64,7 @@ ADDITIONAL COMMANDS
   device shutdown <uuid>                 shutdown a device
   device ssh <applicationOrDevice> [service]    SSH into the host or application container of a device
   devices supported                      list the supported device types (like 'raspberrypi3' or 'intel-nuc')
-  env add <name> [value]                 add env or config variable to application(s), device(s) or service(s)
+  env set <name> [value]                 add or update env or config variable to application(s), device(s) or service(s)
   env list                               list the environment or config variables of an application, device or service
   env rename <name> <value>              change the value of a config or env var for an app, device or service
   env rm <id>                            remove a config or env var from an application, device or service