Add alias env list for command envs

Change-type: minor

automation/capitanodoc/capitanodoc.ts

@@ -56,7 +56,6 @@ const commandHeadings: { [key: string]: string } = {
 	whoami: 'Authentication',
 	logout: 'Authentication',
 	env: 'Environment Variables',
-	envs: 'Environment Variables',
 	help: 'Help and Version',
 	'ssh-key': 'SSH Keys',
 	orgs: 'Organizations',

completion/_balena

@@ -8,7 +8,7 @@ _balena() {
   local context state line curcontext="$curcontext"
 
   # Valid top-level completions
-  main_commands=( api-key app block build config deploy device devices env envs fleet internal join leave local login logout logs notes orgs os preload push release scan settings ssh ssh-key support tag tags tunnel util version whoami )
+  main_commands=( api-key app block build config deploy device devices env fleet internal join leave local login logout logs notes orgs os preload push release scan settings ssh ssh-key support tag tags tunnel util version whoami )
   # Sub-completions
   api_key_cmds=( generate list revoke )
   app_cmds=( create )
@@ -16,7 +16,7 @@ _balena() {
   config_cmds=( generate inject read reconfigure write )
   device_cmds=( deactivate identify init list local-mode move os-update pin public-url purge reboot register rename restart rm shutdown start-service stop-service track-fleet )
   devices_cmds=( supported )
-  env_cmds=( add rename rm )
+  env_cmds=( add list rename rm )
   fleet_cmds=( create list pin purge rename restart rm track-latest )
   internal_cmds=( osinit )
   local_cmds=( configure flash )

completion/balena-completion.bash

@@ -7,7 +7,7 @@ _balena_complete()
   local cur prev
 
   # Valid top-level completions
-  main_commands="api-key app block build config deploy device devices env envs fleet internal join leave local login logout logs notes orgs os preload push release scan settings ssh ssh-key support tag tags tunnel util version whoami"
+  main_commands="api-key app block build config deploy device devices env fleet internal join leave local login logout logs notes orgs os preload push release scan settings ssh ssh-key support tag tags tunnel util version whoami"
   # Sub-completions
   api_key_cmds="generate list revoke"
   app_cmds="create"
@@ -15,7 +15,7 @@ _balena_complete()
   config_cmds="generate inject read reconfigure write"
   device_cmds="deactivate identify init list local-mode move os-update pin public-url purge reboot register rename restart rm shutdown start-service stop-service track-fleet"
   devices_cmds="supported"
-  env_cmds="add rename rm"
+  env_cmds="add list rename rm"
   fleet_cmds="create list pin purge rename restart rm track-latest"
   internal_cmds="osinit"
   local_cmds="configure flash"

docs/balena-cli.md

@@ -220,9 +220,9 @@ are encouraged to regularly update the balena CLI to the latest version.
 - Environment Variables
 
 	- [env add](#env-add)
+	- [env list](#env-list)
 	- [env rename](#env-rename)
 	- [env rm](#env-rm)
-	- [envs](#envs)
 
 - Fleets
 
@@ -1976,6 +1976,90 @@ suppress warning messages
 
 service name
 
+## env list
+
+### Aliases
+
+- `envs`
+
+
+To use one of the aliases, replace `env list` with the alias.
+
+### Description
+
+List the environment or configuration variables of a fleet, device or
+service, as selected by the respective command-line options. (A service
+corresponds to a Docker image/container in a microservices fleet.)
+
+The results include fleet-wide (multiple devices), device-specific (multiple
+services on a specific device) and service-specific variables that apply to the
+selected fleet, device or service. It can be thought of as including inherited
+variables; for example, a service inherits device-wide variables, and a device
+inherits fleet-wide variables.
+
+The printed output may include DEVICE and/or SERVICE columns to distinguish
+between fleet-wide, device-specific and service-specific variables.
+An asterisk in these columns indicates that the variable applies to
+"all devices" or "all services".
+
+The --config option is used to list "configuration variables" that control
+balena platform features, as opposed to custom environment variables defined
+by the user. The --config and the --service options are mutually exclusive
+because configuration variables cannot be set for specific services.
+
+The --json option is recommended when scripting the output of this command,
+because the JSON format is less likely to change and it better represents data
+types like lists and empty strings. The 'jq' utility may be helpful in shell
+scripts (https://stedolan.github.io/jq/manual/). When --json is used, an empty
+JSON array ([]) is printed instead of an error message when no variables exist
+for the given query. When querying variables for a device, note that the fleet
+name may be null in JSON output (or 'N/A' in tabular output) if the fleet that
+the device belonged to is no longer accessible by the current user (for example,
+in case the current user was removed from the fleet by the fleet's owner).
+
+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 list --fleet myorg/myfleet
+	$ balena env list --fleet MyFleet --json
+	$ balena env list --fleet MyFleet --service MyService
+	$ balena env list --fleet MyFleet --config
+	$ balena env list --device 7cf02a6
+	$ balena env list --device 7cf02a6 --json
+	$ balena env list --device 7cf02a6 --config --json
+	$ balena env list --device 7cf02a6 --service MyService
+
+### Options
+
+#### -f, --fleet FLEET
+
+fleet name or slug (preferred)
+
+#### -c, --config
+
+show configuration variables only
+
+#### -d, --device DEVICE
+
+device UUID
+
+#### -j, --json
+
+produce JSON output instead of tabular output
+
+#### -s, --service SERVICE
+
+service name
+
 ## env rename
 
 ### Description
@@ -1983,7 +2067,7 @@ service name
 Change the value of a configuration or environment variable for a fleet,
 device or service, as selected by command-line options.
 
-Variables are selected by their database ID (as reported by the 'balena envs'
+Variables are selected by their database ID (as reported by the 'balena env list'
 command) and one of six database "resource types":
 
 - fleet environment variable
@@ -2048,7 +2132,7 @@ select a service variable (may be used together with the --device option)
 Remove a configuration or environment variable from a fleet, device
 or service, as selected by command-line options.
 
-Variables are selected by their database ID (as reported by the 'balena envs'
+Variables are selected by their database ID (as reported by the 'balena env list'
 command) and one of six database "resource types":
 
 - fleet environment variable
@@ -2110,83 +2194,6 @@ select a service variable (may be used together with the --device option)
 
 do not prompt for confirmation before deleting the variable
 
-## envs
-
-### Description
-
-List the environment or configuration variables of a fleet, device or
-service, as selected by the respective command-line options. (A service
-corresponds to a Docker image/container in a microservices fleet.)
-
-The results include fleet-wide (multiple devices), device-specific (multiple
-services on a specific device) and service-specific variables that apply to the
-selected fleet, device or service. It can be thought of as including inherited
-variables; for example, a service inherits device-wide variables, and a device
-inherits fleet-wide variables.
-
-The printed output may include DEVICE and/or SERVICE columns to distinguish
-between fleet-wide, device-specific and service-specific variables.
-An asterisk in these columns indicates that the variable applies to
-"all devices" or "all services".
-
-The --config option is used to list "configuration variables" that control
-balena platform features, as opposed to custom environment variables defined
-by the user. The --config and the --service options are mutually exclusive
-because configuration variables cannot be set for specific services.
-
-The --json option is recommended when scripting the output of this command,
-because the JSON format is less likely to change and it better represents data
-types like lists and empty strings. The 'jq' utility may be helpful in shell
-scripts (https://stedolan.github.io/jq/manual/). When --json is used, an empty
-JSON array ([]) is printed instead of an error message when no variables exist
-for the given query. When querying variables for a device, note that the fleet
-name may be null in JSON output (or 'N/A' in tabular output) if the fleet that
-the device belonged to is no longer accessible by the current user (for example,
-in case the current user was removed from the fleet by the fleet's owner).
-
-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 envs --fleet myorg/myfleet
-	$ balena envs --fleet MyFleet --json
-	$ balena envs --fleet MyFleet --service MyService
-	$ balena envs --fleet MyFleet --config
-	$ balena envs --device 7cf02a6
-	$ balena envs --device 7cf02a6 --json
-	$ balena envs --device 7cf02a6 --config --json
-	$ balena envs --device 7cf02a6 --service MyService
-
-### Options
-
-#### -f, --fleet FLEET
-
-fleet name or slug (preferred)
-
-#### -c, --config
-
-show configuration variables only
-
-#### -d, --device DEVICE
-
-device UUID
-
-#### -j, --json
-
-produce JSON output instead of tabular output
-
-#### -s, --service SERVICE
-
-service name
-
 # Fleets
 
 ## fleet create

src/commands/env/list.ts

@@ -23,7 +23,7 @@ import * as cf from '../../utils/common-flags';
 import { getBalenaSdk, getVisuals, stripIndent } from '../../utils/lazy';
 import { applicationIdInfo } from '../../utils/messages';
 
-type FlagsDef = Interfaces.InferredFlags<typeof EnvsCmd.flags>;
+type FlagsDef = Interfaces.InferredFlags<typeof EnvListCmd.flags>;
 
 interface EnvironmentVariableInfo extends SDK.EnvironmentVariableBase {
 	fleet?: string | null; // fleet slug
@@ -45,7 +45,9 @@ interface ServiceEnvironmentVariableInfo
 	serviceName?: string; // service name
 }
 
-export default class EnvsCmd extends Command {
+export default class EnvListCmd extends Command {
+	public static aliases = ['envs'];
+
 	public static description = stripIndent`
 		List the environment or config variables of a fleet, device or service.
 
@@ -83,14 +85,14 @@ export default class EnvsCmd extends Command {
 	`;
 
 	public static examples = [
-		'$ balena envs --fleet myorg/myfleet',
+		'$ balena env list --fleet myorg/myfleet',
-		'$ balena envs --fleet MyFleet --json',
+		'$ balena env list --fleet MyFleet --json',
-		'$ balena envs --fleet MyFleet --service MyService',
+		'$ balena env list --fleet MyFleet --service MyService',
-		'$ balena envs --fleet MyFleet --config',
+		'$ balena env list --fleet MyFleet --config',
-		'$ balena envs --device 7cf02a6',
+		'$ balena env list --device 7cf02a6',
-		'$ balena envs --device 7cf02a6 --json',
+		'$ balena env list --device 7cf02a6 --json',
-		'$ balena envs --device 7cf02a6 --config --json',
+		'$ balena env list --device 7cf02a6 --config --json',
-		'$ balena envs --device 7cf02a6 --service MyService',
+		'$ balena env list --device 7cf02a6 --service MyService',
 	];
 
 	public static flags = {
@@ -108,7 +110,7 @@ export default class EnvsCmd extends Command {
 	};
 
 	public async run() {
-		const { flags: options } = await this.parse(EnvsCmd);
+		const { flags: options } = await this.parse(EnvListCmd);
 
 		const variables: EnvironmentVariableInfo[] = [];
 

src/utils/env-common.ts

@@ -43,7 +43,7 @@ export const booleanService = Flags.boolean({
 });
 
 export const rmRenameHelp = stripIndent`
-	Variables are selected by their database ID (as reported by the 'balena envs'
+	Variables are selected by their database ID (as reported by the 'balena env list'
 	command) and one of six database "resource types":
 
 	- fleet environment variable

tests/commands/env/list.spec.ts

@@ -22,7 +22,7 @@ import { BalenaAPIMock } from '../../nock/balena-api-mock';
 import { runCommand } from '../../helpers';
 import { randomBytes } from 'node:crypto';
 
-describe('balena envs', function () {
+describe('balena env list', function () {
 	const appName = 'test';
 	let fullUUID: string;
 	let shortUUID: string;
@@ -46,7 +46,7 @@ describe('balena envs', function () {
 		api.expectGetAppEnvVars();
 		api.expectGetAppServiceVars();
 
-		const { out, err } = await runCommand(`envs -f ${appName}`);
+		const { out, err } = await runCommand(`env list -f ${appName}`);
 
 		expect(out.join('')).to.equal(
 			stripIndent`
@@ -60,11 +60,32 @@ describe('balena envs', function () {
 		expect(err.join('')).to.equal('');
 	});
 
+	it('should successfully list env vars for a test fleet via `envs` alias', async () => {
+		api.expectGetApplication();
+		api.expectGetAppEnvVars();
+		api.expectGetAppServiceVars();
+
+		const { out, err } = await runCommand(`envs -f ${appName}`);
+
+		expect(out.join('')).to.satisfy((msg: string) =>
+			msg.endsWith(
+				stripIndent`
+			ID     NAME  VALUE       FLEET           SERVICE
+			120110 svar1 svar1-value gh_user/testApp service1
+			120111 svar2 svar2-value gh_user/testApp service2
+			120101 var1  var1-val    gh_user/testApp *
+			120102 var2  22          gh_user/testApp *
+		` + '\n',
+			),
+		);
+		expect(err.join('')).to.equal('');
+	});
+
 	it('should successfully list config vars for a test fleet', async () => {
 		api.expectGetApplication();
 		api.expectGetAppConfigVars();
 
-		const { out, err } = await runCommand(`envs -f ${appName} --config`);
+		const { out, err } = await runCommand(`env list -f ${appName} --config`);
 
 		expect(out.join('')).to.equal(
 			stripIndent`
@@ -80,7 +101,7 @@ describe('balena envs', function () {
 		api.expectGetApplication();
 		api.expectGetAppConfigVars();
 
-		const { out, err } = await runCommand(`envs -cjf ${appName}`);
+		const { out, err } = await runCommand(`env list -cjf ${appName}`);
 
 		expect(JSON.parse(out.join(''))).to.deep.equal([
 			{
@@ -101,7 +122,7 @@ describe('balena envs', function () {
 		api.expectGetAppServiceVars();
 
 		const { out, err } = await runCommand(
-			`envs -f ${appName} -s ${serviceName}`,
+			`env list -f ${appName} -s ${serviceName}`,
 		);
 
 		expect(out.join('')).to.equal(
@@ -123,7 +144,7 @@ describe('balena envs', function () {
 		api.expectGetAppServiceVars();
 
 		const { out, err } = await runCommand(
-			`envs -f ${appName} -s ${serviceName}`,
+			`env list -f ${appName} -s ${serviceName}`,
 		);
 
 		expect(out.join('')).to.equal(
@@ -146,7 +167,7 @@ describe('balena envs', function () {
 		api.expectGetAppServiceVars();
 		api.expectGetDeviceServiceVars();
 
-		const result = await runCommand(`envs -d ${shortUUID}`);
+		const result = await runCommand(`env list -d ${shortUUID}`);
 		let { out } = result;
 		let expected =
 			stripIndent`
@@ -176,7 +197,7 @@ describe('balena envs', function () {
 		api.expectGetAppServiceVars();
 		api.expectGetDeviceServiceVars();
 
-		const { out, err } = await runCommand(`envs -jd ${shortUUID}`);
+		const { out, err } = await runCommand(`env list -jd ${shortUUID}`);
 		const expected = `[
 			{ "id": 120101, "fleet": "org/test", "deviceUUID": "*", "name": "var1", "value": "var1-val", "serviceName": "*" },
 			{ "id": 120102, "fleet": "org/test", "deviceUUID": "*", "name": "var2", "value": "22", "serviceName": "*" },
@@ -199,7 +220,7 @@ describe('balena envs', function () {
 		api.expectGetApplication();
 		api.expectGetAppConfigVars();
 
-		const result = await runCommand(`envs -d ${shortUUID} --config`);
+		const result = await runCommand(`env list -d ${shortUUID} --config`);
 		let { out } = result;
 		let expected =
 			stripIndent`
@@ -225,7 +246,9 @@ describe('balena envs', function () {
 		api.expectGetAppServiceVars();
 		api.expectGetDeviceEnvVars();
 
-		const result = await runCommand(`envs -d ${shortUUID} -s ${serviceName}`);
+		const result = await runCommand(
+			`env list -d ${shortUUID} -s ${serviceName}`,
+		);
 		let { out } = result;
 		let expected =
 			stripIndent`
@@ -250,7 +273,7 @@ describe('balena envs', function () {
 		api.expectGetDeviceEnvVars();
 		api.expectGetDeviceServiceVars();
 
-		const result = await runCommand(`envs -d ${shortUUID}`);
+		const result = await runCommand(`env list -d ${shortUUID}`);
 		let { out } = result;
 		let expected =
 			stripIndent`
@@ -278,7 +301,9 @@ describe('balena envs', function () {
 		api.expectGetDeviceEnvVars();
 		api.expectGetDeviceServiceVars();
 
-		const result = await runCommand(`envs -d ${shortUUID} -s ${serviceName}`);
+		const result = await runCommand(
+			`env list -d ${shortUUID} -s ${serviceName}`,
+		);
 		let { out } = result;
 		let expected =
 			stripIndent`
@@ -309,7 +334,7 @@ describe('balena envs', function () {
 		api.expectGetDeviceServiceVars();
 
 		const { out, err } = await runCommand(
-			`envs -d ${shortUUID} -js ${serviceName}`,
+			`env list -d ${shortUUID} -js ${serviceName}`,
 		);
 		const expected = `[
 			{ "id": 120101, "fleet": "org/test", "deviceUUID": "*", "name": "var1", "value": "var1-val", "serviceName": "*" },

tests/commands/help.spec.ts

@@ -67,9 +67,9 @@ ADDITIONAL COMMANDS
   device shutdown <uuid>                 shutdown 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 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
-  envs                                   list the environment or config variables of an application, device or service
   ssh-key <id>                           display an SSH key
   ssh-key add <name> [path]              add an SSH key to balenaCloud
   ssh-key list                           list the SSH keys in balenaCloud

tests/test-data/pkg/expected-warnings-darwin-arm64.txt

@@ -130,15 +130,15 @@
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/env/add.js
+> Warning Entry 'main' not found in %1
+  %1: node_modules/@oclif/core/package.json
+  %2: build/commands/env/list.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/env/rename.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/env/rm.js
-> Warning Entry 'main' not found in %1
-  %1: node_modules/@oclif/core/package.json
-  %2: build/commands/envs/index.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/fleet/create.js

tests/test-data/pkg/expected-warnings-darwin-x64.txt

@@ -130,15 +130,15 @@
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/env/add.js
+> Warning Entry 'main' not found in %1
+  %1: node_modules/@oclif/core/package.json
+  %2: build/commands/env/list.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/env/rename.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/env/rm.js
-> Warning Entry 'main' not found in %1
-  %1: node_modules/@oclif/core/package.json
-  %2: build/commands/envs/index.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/fleet/create.js

tests/test-data/pkg/expected-warnings-linux-arm64.txt

@@ -130,15 +130,15 @@
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/env/add.js
+> Warning Entry 'main' not found in %1
+  %1: node_modules/@oclif/core/package.json
+  %2: build/commands/env/list.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/env/rename.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/env/rm.js
-> Warning Entry 'main' not found in %1
-  %1: node_modules/@oclif/core/package.json
-  %2: build/commands/envs/index.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/fleet/create.js

tests/test-data/pkg/expected-warnings-linux-x64.txt

@@ -130,15 +130,15 @@
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/env/add.js
+> Warning Entry 'main' not found in %1
+  %1: node_modules/@oclif/core/package.json
+  %2: build/commands/env/list.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/env/rename.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/env/rm.js
-> Warning Entry 'main' not found in %1
-  %1: node_modules/@oclif/core/package.json
-  %2: build/commands/envs/index.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/fleet/create.js

tests/test-data/pkg/expected-warnings-win32-x64.txt

@@ -130,15 +130,15 @@
 > Warning Entry 'main' not found in %1
   %1: node_modules\@oclif\core\package.json
   %2: build\commands\env\add.js
+> Warning Entry 'main' not found in %1
+  %1: node_modules\@oclif\core\package.json
+  %2: build\commands\env\list.js
 > Warning Entry 'main' not found in %1
   %1: node_modules\@oclif\core\package.json
   %2: build\commands\env\rename.js
 > Warning Entry 'main' not found in %1
   %1: node_modules\@oclif\core\package.json
   %2: build\commands\env\rm.js
-> Warning Entry 'main' not found in %1
-  %1: node_modules\@oclif\core\package.json
-  %2: build\commands\envs\index.js
 > Warning Entry 'main' not found in %1
   %1: node_modules\@oclif\core\package.json
   %2: build\commands\fleet\create.js