Merge pull request #2844 from balena-io/devices-to-device-list

Devices to device list

automation/capitanodoc/markdown.ts

@@ -24,6 +24,15 @@ import type { Category, Document, OclifCommand } from './doc-types';
 
 function renderOclifCommand(command: Category['commands'][0]): string[] {
 	const result = [`## ${ent.encode(command.name || '')}`];
+	if (command.aliases?.length) {
+		result.push('### Aliases');
+		result.push(command.aliases.map((alias) => `- \`${alias}\``).join('\n'));
+		result.push(
+			`\nTo use one of the aliases, replace \`${command.name}\` with the alias.`,
+		);
+	}
+
+	result.push('### Description');
 	const description = (command.description || '')
 		.split('\n')
 		.slice(1) // remove the first line, which oclif uses as help header

completion/_balena

@@ -14,7 +14,7 @@ _balena() {
   app_cmds=( create )
   block_cmds=( create )
   config_cmds=( generate inject read reconfigure write )
-  device_cmds=( deactivate identify init local-mode move os-update pin public-url purge reboot register rename restart rm shutdown start-service stop-service track-fleet )
+  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 )
   fleet_cmds=( create pin purge rename restart rm track-latest )

completion/balena-completion.bash

@@ -13,7 +13,7 @@ _balena_complete()
   app_cmds="create"
   block_cmds="create"
   config_cmds="generate inject read reconfigure write"
-  device_cmds="deactivate identify init local-mode move os-update pin public-url purge reboot register rename restart rm shutdown start-service stop-service track-fleet"
+  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"
   fleet_cmds="create pin purge rename restart rm track-latest"

docs/balena-cli.md

@@ -199,6 +199,7 @@ are encouraged to regularly update the balena CLI to the latest version.
 	- [device identify](#device-identify)
 	- [device](#device)
 	- [device init](#device-init)
+	- [device list](#device-list)
 	- [device local-mode](#device-local-mode)
 	- [device move](#device-move)
 	- [device os-update](#device-os-update)
@@ -214,7 +215,6 @@ are encouraged to regularly update the balena CLI to the latest version.
 	- [device start-service](#device-start-service)
 	- [device stop-service](#device-stop-service)
 	- [device track-fleet](#device-track-fleet)
-	- [devices](#devices)
 	- [devices supported](#devices-supported)
 
 - Environment Variables
@@ -321,6 +321,8 @@ are encouraged to regularly update the balena CLI to the latest version.
 
 ## api-key generate
 
+### Description
+
 Generate a new balenaCloud API key for the current user, with the given
 name. The key will be logged to the console.
 
@@ -341,6 +343,8 @@ the API key name
 
 ## api-key revoke
 
+### Description
+
 Revoke balenaCloud API keys with the given
 comma-separated list of ids.
 
@@ -361,6 +365,8 @@ the API key ids
 
 ## api-keys
 
+### Description
+
 Print a list of balenaCloud API keys.
 
 Print a list of balenaCloud API keys for the current user or for a specific fleet with the `--fleet` option.
@@ -383,6 +389,8 @@ fleet name or slug (preferred)
 
 ## app create
 
+### Description
+
 Create a new balena app.
 
 You can specify the organization the app should belong to using
@@ -426,6 +434,8 @@ app device type (Check available types with `balena devices supported`)
 
 ## login
 
+### Description
+
 Login to your balena account.
 
 This command will prompt you to login using the following login types:
@@ -487,6 +497,8 @@ Hides warning for experimental features
 
 ## logout
 
+### Description
+
 Logout from your balena account.
 
 Examples:
@@ -495,6 +507,8 @@ Examples:
 
 ## whoami
 
+### Description
+
 Get the username and email address of the currently logged in user.
 
 Examples:
@@ -505,6 +519,8 @@ Examples:
 
 ## block create
 
+### Description
+
 Create a new balena block.
 
 You can specify the organization the block should belong to using
@@ -548,6 +564,8 @@ block device type (Check available types with `balena devices supported`)
 
 ## config generate
 
+### Description
+
 Generate a config.json file for a device or fleet.
 
 The target balenaOS version must be specified with the --version option.
@@ -658,6 +676,8 @@ expiry date assigned to generated provisioning api key (format: YYYY-MM-DD)
 
 ## config inject
 
+### Description
+
 Inject a 'config.json' file to a balenaOS image file or attached SD card or
 USB stick.
 
@@ -683,6 +703,8 @@ path to OS image file (e.g. balena.img) or block device (e.g. /dev/disk2)
 
 ## config read
 
+### Description
+
 Read the 'config.json' file of a balenaOS image file or attached SD card or
 USB stick.
 
@@ -707,6 +729,8 @@ produce JSON output instead of tabular output
 
 ## config reconfigure
 
+### Description
+
 Interactively reconfigure a balenaOS image file or attached media.
 
 This command extracts the device UUID from the 'config.json' file of the
@@ -738,6 +762,8 @@ balenaOS version, for example "2.32.0" or "2.44.0+rev1"
 
 ## config write
 
+### Description
+
 Write a key-value pair to the 'config.json' file of a balenaOS image file or
 attached SD card or USB stick.
 
@@ -770,6 +796,8 @@ path to OS image file (e.g. balena.img) or block device (e.g. /dev/disk2)
 
 ## build
 
+### Description
+
 Use this command to build an image or a complete multicontainer project with
 the provided docker daemon in your development machine or balena device.
 (See also the `balena push` command for the option of building images in the
@@ -969,6 +997,8 @@ Docker host TLS key file
 
 ## deploy
 
+### Description
+
 Usage: `deploy <fleet> ([image] | --build [--source build-dir])`
 
 Use this command to deploy an image or a complete multicontainer project to a
@@ -1196,6 +1226,8 @@ Docker host TLS key file
 
 ## device deactivate
 
+### Description
+
 Deactivate a device.
 
 Note this command asks for confirmation interactively.
@@ -1220,6 +1252,8 @@ answer "yes" to all questions (non interactive use)
 
 ## device identify
 
+### Description
+
 Identify a device by making the ACT LED blink (Raspberry Pi).
 
 Examples:
@@ -1236,6 +1270,8 @@ the uuid of the device to identify
 
 ## device
 
+### Description
+
 Show information about a single device.
 
 The --json option is recommended when scripting the output of this command,
@@ -1268,6 +1304,8 @@ open device dashboard page
 
 ## device init
 
+### Description
+
 Register a new device in the selected fleet, download the OS image for the
 fleet's default device type, configure the image and write it to an SD card.
 This command effectively combines several other balena CLI commands in one,
@@ -1351,8 +1389,57 @@ custom key name assigned to generated provisioning api key
 
 expiry date assigned to generated provisioning api key (format: YYYY-MM-DD)
 
+## device list
+
+### Aliases
+
+- `devices`
+
+
+To use one of the aliases, replace `device list` with the alias.
+
+### Description
+
+List all of your devices.
+
+Devices can be filtered by fleet with the `--fleet` option.
+
+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 fleets` 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).
+
+The --json option is recommended when scripting the output of this command,
+because field names are less likely to change in JSON format and because it
+better represents data types like arrays, empty strings and null values.
+The 'jq' utility may be helpful for querying JSON fields in shell scripts
+(https://stedolan.github.io/jq/manual/).
+
+Examples:
+
+	$ balena device list
+	$ balena device list --fleet MyFleet
+	$ balena device list -f myorg/myfleet
+
+### Options
+
+#### -f, --fleet FLEET
+
+fleet name or slug (preferred)
+
+#### -j, --json
+
+produce JSON output instead of tabular output
+
 ## device local-mode
 
+### Description
+
 Output current local mode status, or enable/disable local mode
 for specified device.
 
@@ -1385,6 +1472,8 @@ output boolean indicating local mode status
 
 ## device move
 
+### Description
+
 Move one or more devices to another fleet.
 
 If --fleet is omitted, the fleet will be prompted for interactively.
@@ -1420,6 +1509,8 @@ fleet name or slug (preferred)
 
 ## device os-update
 
+### Description
+
 Start a Host OS update for a device.
 
 Note this command will ask for confirmation interactively.
@@ -1456,6 +1547,8 @@ answer "yes" to all questions (non interactive use)
 
 ## device pin
 
+### Description
+
 Pin a device to a release.
 
 Note, if the commit is omitted, the currently pinned release will be printed, with instructions for how to see a list of releases
@@ -1479,6 +1572,8 @@ the commit of the release for the device to get pinned to
 
 ## device public-url
 
+### Description
+
 This command will output the current public URL for the
 specified device.  It can also enable or disable the URL,
 or output the enabled status, using the respective options.
@@ -1512,6 +1607,8 @@ determine if public URL is enabled
 
 ## device purge
 
+### Description
+
 Purge data from a device.
 This will clear the device's "/data" directory.
 
@@ -1533,6 +1630,8 @@ comma-separated list (no blank spaces) of device UUIDs
 
 ## device reboot
 
+### Description
+
 Remotely reboot a device.
 
 Examples:
@@ -1553,6 +1652,8 @@ force action if the update lock is set
 
 ## device register
 
+### Description
+
 Register a new device with a balena fleet.
 
 If --uuid is not provided, a new UUID will be automatically assigned.
@@ -1592,6 +1693,8 @@ device type slug (run 'balena devices supported' for possible values)
 
 ## device rename
 
+### Description
+
 Rename a device.
 
 Note, if the name is omitted, it will be prompted for interactively.
@@ -1615,6 +1718,8 @@ the new name for the device
 
 ## device restart
 
+### Description
+
 Restart containers on a device.
 If the --service flag is provided, then only those services' containers
 will be restarted, otherwise all containers on the device will be restarted.
@@ -1645,6 +1750,8 @@ comma-separated list (no blank spaces) of service names to restart
 
 ## device rm
 
+### Description
+
 Remove one or more devices from balena.
 
 Note this command asks for confirmation interactively.
@@ -1670,6 +1777,8 @@ answer "yes" to all questions (non interactive use)
 
 ## device shutdown
 
+### Description
+
 Remotely shutdown a device.
 
 Examples:
@@ -1690,6 +1799,8 @@ force action if the update lock is set
 
 ## device start-service
 
+### Description
+
 Start containers on a device.
 
 Multiple devices and services may be specified with a comma-separated list
@@ -1714,6 +1825,8 @@ comma-separated list (no blank spaces) of service names
 
 ## device stop-service
 
+### Description
+
 Stop containers on a device.
 
 Multiple devices and services may be specified with a comma-separated list
@@ -1738,6 +1851,8 @@ comma-separated list (no blank spaces) of service names
 
 ## device track-fleet
 
+### Description
+
 Make a device track the fleet's pinned release.
 
 Examples:
@@ -1752,46 +1867,10 @@ the uuid of the device to make track the fleet's release
 
 ### Options
 
-## devices
-
-List all of your devices.
-
-Devices can be filtered by fleet with the `--fleet` option.
-
-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 fleets` 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).
-
-The --json option is recommended when scripting the output of this command,
-because field names are less likely to change in JSON format and because it
-better represents data types like arrays, empty strings and null values.
-The 'jq' utility may be helpful for querying JSON fields in shell scripts
-(https://stedolan.github.io/jq/manual/).
-
-Examples:
-
-	$ balena devices
-	$ balena devices --fleet MyFleet
-	$ balena devices -f myorg/myfleet
-
-### Options
-
-#### -f, --fleet FLEET
-
-fleet name or slug (preferred)
-
-#### -j, --json
-
-produce JSON output instead of tabular output
-
 ## devices supported
 
+### Description
+
 List the supported device types (like 'raspberrypi3' or 'intel-nuc').
 
 The --json option is recommended when scripting the output of this command,
@@ -1815,6 +1894,8 @@ produce JSON output instead of tabular output
 
 ## env add
 
+### Description
+
 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
@@ -1890,6 +1971,8 @@ service name
 
 ## env rename
 
+### Description
+
 Change the value of a configuration or environment variable for a fleet,
 device or service, as selected by command-line options.
 
@@ -1953,6 +2036,8 @@ select a service variable (may be used together with the --device option)
 
 ## env rm
 
+### Description
+
 Remove a configuration or environment variable from a fleet, device
 or service, as selected by command-line options.
 
@@ -2020,6 +2105,8 @@ 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.)
@@ -2097,6 +2184,8 @@ service name
 
 ## fleet create
 
+### Description
+
 Create a new balena fleet.
 
 You can specify the organization the fleet should belong to using
@@ -2138,6 +2227,8 @@ fleet device type (Check available types with `balena devices supported`)
 
 ## fleet
 
+### Description
+
 Display detailed information about a single fleet.
 
 Fleets may be specified by fleet name or slug. Fleet slugs are
@@ -2174,6 +2265,8 @@ produce JSON output instead of tabular output
 
 ## fleet pin
 
+### Description
+
 Pin a fleet to a release.
 
 Note, if the commit is omitted, the currently pinned release will be printed, with instructions for how to see a list of releases
@@ -2197,6 +2290,8 @@ the commit of the release for the fleet to get pinned to
 
 ## fleet purge
 
+### Description
+
 Purge data from all devices belonging to a fleet.
 This will clear the fleet's '/data' directory.
 
@@ -2225,6 +2320,8 @@ fleet name or slug (preferred)
 
 ## fleet rename
 
+### Description
+
 Rename a fleet.
 
 Note, if the `newName` parameter is omitted, it will be
@@ -2260,6 +2357,8 @@ the new name for the fleet
 
 ## fleet restart
 
+### Description
+
 Restart all devices belonging to a fleet.
 
 Fleets may be specified by fleet name or slug. Fleet slugs are
@@ -2287,6 +2386,8 @@ fleet name or slug (preferred)
 
 ## fleet rm
 
+### Description
+
 Permanently remove a fleet.
 
 The --yes option may be used to avoid interactive confirmation.
@@ -2321,6 +2422,8 @@ answer "yes" to all questions (non interactive use)
 
 ## fleet track-latest
 
+### Description
+
 Make this fleet track the latest release.
 
 Examples:
@@ -2338,6 +2441,8 @@ the slug of the fleet to make track the latest release
 
 ## fleets
 
+### Description
+
 List all your balena fleets.
 
 For detailed information on a particular fleet, use
@@ -2357,6 +2462,8 @@ produce JSON output instead of tabular output
 
 ## local configure
 
+### Description
+
 Configure or reconfigure a balenaOS drive or image.
 
 Examples:
@@ -2374,6 +2481,8 @@ path of drive or image to configure
 
 ## local flash
 
+### Description
+
 Flash a balenaOS image to a drive.
 Image file may be one of: .img|.zip|.gz|.bz2|.xz
 
@@ -2408,6 +2517,8 @@ answer "yes" to all questions (non interactive use)
 
 ## logs
 
+### Description
+
 Show logs for a specific device.
 
 By default, the command prints all log messages and exits.
@@ -2465,6 +2576,8 @@ Only show system logs. This can be used in combination with --service.
 
 ## scan
 
+### Description
+
 Scan for balenaOS devices on your local network.
 
 The output includes device information collected through balenaEngine for
@@ -2494,6 +2607,8 @@ produce JSON output instead of tabular output
 
 ## ssh
 
+### Description
+
 Start a shell on a local or remote device. If a service name is not provided,
 a shell will be opened on the host OS.
 
@@ -2559,6 +2674,8 @@ bypass global proxy configuration for the ssh connection
 
 ## tunnel
 
+### Description
+
 Use this command to open local TCP ports that tunnel to listening sockets in a
 balenaOS device.
 
@@ -2612,6 +2729,8 @@ port mapping in the format <remotePort>[:[localIP:]localPort]
 
 ## notes
 
+### Description
+
 Set or update a device note. If the note argument is not provided,
 it will be read from stdin.
 
@@ -2642,6 +2761,8 @@ device UUID
 
 ## orgs
 
+### Description
+
 list all the organizations that you are a member of.
 
 Examples:
@@ -2654,6 +2775,8 @@ Examples:
 
 ## os build-config
 
+### Description
+
 Interactively generate a configuration file that can then be used as
 non-interactive input by the 'balena os configure' command.
 
@@ -2684,6 +2807,8 @@ path to output JSON file
 
 ## os configure
 
+### Description
+
 Configure a previously downloaded balenaOS image for a specific device type
 or fleet.
 
@@ -2809,6 +2934,8 @@ expiry date assigned to generated provisioning api key (format: YYYY-MM-DD)
 
 ## os download
 
+### Description
+
 Download an unconfigured OS image for the specified device type.
 Check available device types with 'balena devices supported'.
 
@@ -2864,6 +2991,8 @@ or 'menu-esr' (interactive menu, ESR versions)
 
 ## os initialize
 
+### Description
+
 Initialize an os image for a device with a previously
 		configured operating system image and flash the
 		an external storage drive or the device's storage
@@ -2901,6 +3030,8 @@ answer "yes" to all questions (non interactive use)
 
 ## os versions
 
+### Description
+
 Show the available balenaOS versions for the given device type.
 Check available types with `balena devices supported`.
 
@@ -2931,6 +3062,8 @@ include pre-release balenaOS versions
 
 ## join
 
+### Description
+
 Move a local device to a fleet on another balena server, causing
 the device to "join" the new server. The device must be running balenaOS.
 
@@ -2983,6 +3116,8 @@ the interval in minutes to check for updates
 
 ## leave
 
+### Description
+
 Remove a local device from its balena fleet, causing the device to
 "leave" the server it is provisioned on. This effectively makes the device
 "unmanaged". The device must be running balenaOS.
@@ -3012,6 +3147,8 @@ the device IP or hostname
 
 ## preload
 
+### Description
+
 Preload a release (service images/containers) from a balena fleet, and optionally
 a balenaOS splash screen, in a previously downloaded '.img' balenaOS image file
 in the local disk (a zip file is only accepted for the Intel Edison device type).
@@ -3120,6 +3257,8 @@ Docker host TLS key file
 
 ## push
 
+### Description
+
 Build release images on balenaCloud servers or on a local mode device.
 
 When building on the balenaCloud servers, the given source directory will be
@@ -3347,6 +3486,8 @@ The notes for this release
 
 ## release finalize
 
+### Description
+
 Finalize a release. Releases can be "draft" or "final", and this command
 changes a draft release into a final release. Draft releases can be created
 with the `--draft` option of the `balena build` or `balena deploy`
@@ -3373,6 +3514,8 @@ the commit or ID of the release to finalize
 
 ## release
 
+### Description
+
 The --json option is recommended when scripting the output of this command,
 because field names are less likely to change in JSON format and because it
 better represents data types like arrays, empty strings and null values.
@@ -3403,6 +3546,8 @@ Return the release composition
 
 ## release invalidate
 
+### Description
+
 Invalidate a release.
 
 Invalid releases are not automatically deployed to devices tracking the latest
@@ -3424,6 +3569,8 @@ the commit or ID of the release to invalidate
 
 ## release validate
 
+### Description
+
 Validate a release.
 
 Valid releases are automatically deployed to devices tracking the latest
@@ -3444,6 +3591,8 @@ the commit or ID of the release to validate
 
 ## releases
 
+### Description
+
 List all releases of the given fleet.
 
 Fleets may be specified by fleet name or slug. Slugs are recommended because
@@ -3482,6 +3631,8 @@ produce JSON output instead of tabular output
 
 ## settings
 
+### Description
+
 Use this command to display the current balena CLI settings.
 
 Examples:
@@ -3494,6 +3645,8 @@ Examples:
 
 ## key add
 
+### Description
+
 Add an SSH key to the balenaCloud account of the logged in user.
 
 If `path` is omitted, the command will attempt to read the SSH key from stdin.
@@ -3533,6 +3686,8 @@ the path to the public key file
 
 ## key
 
+### Description
+
 Display a single SSH key registered in balenaCloud for the logged in user.
 
 Examples:
@@ -3549,6 +3704,8 @@ balenaCloud ID for the SSH key
 
 ## key rm
 
+### Description
+
 Remove a single SSH key registered in balenaCloud for the logged in user.
 
 The --yes option may be used to avoid interactive confirmation.
@@ -3572,6 +3729,8 @@ answer "yes" to all questions (non interactive use)
 
 ## keys
 
+### Description
+
 List all SSH keys registered in balenaCloud for the logged in user.
 
 Examples:
@@ -3584,6 +3743,8 @@ Examples:
 
 ## support
 
+### Description
+
 Grant or revoke balena support agent access to devices or fleets
 on balenaCloud. (This command does not apply to openBalena.)
 Access will be automatically revoked once the specified duration has elapsed.
@@ -3634,6 +3795,8 @@ length of time to enable support for, in (h)ours or (d)ays, e.g. 12h, 2d
 
 ## tag rm
 
+### Description
+
 Remove a tag from a fleet, device or release.
 
 Fleets may be specified by fleet name or slug. Fleet slugs are
@@ -3676,6 +3839,8 @@ release id
 
 ## tag set
 
+### Description
+
 Set a tag on a fleet, device or release.
 
 You can optionally provide a value to be associated with the created
@@ -3729,6 +3894,8 @@ release id
 
 ## tags
 
+### Description
+
 List all tags and their values for the specified fleet, device or release.
 
 Fleets may be specified by fleet name or slug. Fleet slugs are
@@ -3767,6 +3934,8 @@ release id
 
 ## util available-drives
 
+### Description
+
 List available drives which are usable for writing an OS image to.
 Does not list system drives.
 
@@ -3776,6 +3945,8 @@ Does not list system drives.
 
 ## version
 
+### Description
+
 Display version information for the balena CLI and/or Node.js. Note that the
 balena CLI executable installers for Windows and macOS, and the standalone
 zip packages, ship with a built-in copy of Node.js.  In this case, the

npm-shrinkwrap.json

@@ -7430,9 +7430,9 @@
       }
     },
     "node_modules/drivelist/node_modules/node-addon-api": {
-      "version": "8.1.0",
+      "version": "8.2.1",
-      "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-8.1.0.tgz",
+      "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-8.2.1.tgz",
-      "integrity": "sha512-yBY+qqWSv3dWKGODD6OGE6GnTX7Q2r+4+DfpqxHSHh8x0B4EKP9+wVGLS6U/AM1vxSNNmUEuIV5EGhYwPpfOwQ==",
+      "integrity": "sha512-vmEOvxwiH8tlOcv4SyE8RH34rI5/nWVaigUeAUPawC6f0+HoDthwI0vkMu4tbtsZrXq6QXFfrkhjofzKEs5tpA==",
       "engines": {
         "node": "^18 || ^20 || >= 21"
       }
@@ -17306,9 +17306,9 @@
       }
     },
     "node_modules/usb/node_modules/node-addon-api": {
-      "version": "8.1.0",
+      "version": "8.2.1",
-      "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-8.1.0.tgz",
+      "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-8.2.1.tgz",
-      "integrity": "sha512-yBY+qqWSv3dWKGODD6OGE6GnTX7Q2r+4+DfpqxHSHh8x0B4EKP9+wVGLS6U/AM1vxSNNmUEuIV5EGhYwPpfOwQ==",
+      "integrity": "sha512-vmEOvxwiH8tlOcv4SyE8RH34rI5/nWVaigUeAUPawC6f0+HoDthwI0vkMu4tbtsZrXq6QXFfrkhjofzKEs5tpA==",
       "engines": {
         "node": "^18 || ^20 || >= 21"
       }

src/commands/device/list.ts

@@ -35,7 +35,9 @@ const devicesSelectFields = {
 	],
 } satisfies PineOptions<Device>;
 
-export default class DevicesCmd extends Command {
+export default class DeviceListCmd extends Command {
+	public static aliases = ['devices'];
+
 	public static description = stripIndent`
 		List all devices.
 
@@ -48,9 +50,9 @@ export default class DevicesCmd extends Command {
 		${jsonInfo.split('\n').join('\n\t\t')}
 	`;
 	public static examples = [
-		'$ balena devices',
+		'$ balena device list',
-		'$ balena devices --fleet MyFleet',
+		'$ balena device list --fleet MyFleet',
-		'$ balena devices -f myorg/myfleet',
+		'$ balena device list -f myorg/myfleet',
 	];
 
 	public static flags = {
@@ -64,7 +66,7 @@ export default class DevicesCmd extends Command {
 	public static authenticated = true;
 
 	public async run() {
-		const { flags: options } = await this.parse(DevicesCmd);
+		const { flags: options } = await this.parse(DeviceListCmd);
 
 		const balena = getBalenaSdk();
 		const devicesOptions = {

src/help.ts

@@ -231,7 +231,6 @@ See: https://git.io/JRHUW#deprecation-policy`,
 		'ssh',
 		'fleets',
 		'fleet',
-		'devices',
 		'device',
 		'tunnel',
 		'preload',

tests/commands/device/device.spec.ts

@@ -121,4 +121,29 @@ describe('balena device', function () {
 		expect(json.belongs_to__application[0].app_name).to.equal('test app');
 		expect(json.device_tag[0].tag_key).to.equal('example');
 	});
+
+	it('should list devices from own and collaborator apps', async () => {
+		api.scope
+			.get(
+				'/v6/device?$orderby=device_name%20asc&$select=id,uuid,device_name,status,is_online,supervisor_version,os_version&$expand=belongs_to__application($select=app_name,slug),is_of__device_type($select=slug),is_running__release($select=commit)',
+			)
+			.replyWithFile(200, path.join(apiResponsePath, 'devices.json'), {
+				'Content-Type': 'application/json',
+			});
+
+		const { out } = await runCommand('device list');
+
+		const lines = cleanOutput(out);
+
+		expect(lines[0].replace(/  +/g, ' ')).to.equal(
+			'ID UUID DEVICE NAME DEVICE TYPE FLEET STATUS IS ONLINE SUPERVISOR VERSION OS VERSION DASHBOARD URL',
+		);
+		expect(lines).to.have.lengthOf.at.least(2);
+
+		expect(lines.some((l) => l.includes('org/test app'))).to.be.true;
+
+		// Devices with missing applications will have application name set to `N/a`.
+		// e.g. When user has a device associated with app that user is no longer a collaborator of.
+		expect(lines.some((l) => l.includes('N/a'))).to.be.true;
+	});
 });

tests/commands/device/devices.spec.ts

@@ -1,61 +0,0 @@
-/**
- * @license
- * Copyright 2019-2020 Balena Ltd.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *    http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import { expect } from 'chai';
-import * as path from 'path';
-
-import { apiResponsePath, BalenaAPIMock } from '../../nock/balena-api-mock';
-import { cleanOutput, runCommand } from '../../helpers';
-
-describe('balena devices', function () {
-	let api: BalenaAPIMock;
-
-	beforeEach(() => {
-		api = new BalenaAPIMock();
-		api.expectGetWhoAmI({ optional: true, persist: true });
-	});
-
-	afterEach(() => {
-		// Check all expected api calls have been made and clean up.
-		api.done();
-	});
-
-	it('should list devices from own and collaborator apps', async () => {
-		api.scope
-			.get(
-				'/v6/device?$orderby=device_name%20asc&$select=id,uuid,device_name,status,is_online,supervisor_version,os_version&$expand=belongs_to__application($select=app_name,slug),is_of__device_type($select=slug),is_running__release($select=commit)',
-			)
-			.replyWithFile(200, path.join(apiResponsePath, 'devices.json'), {
-				'Content-Type': 'application/json',
-			});
-
-		const { out } = await runCommand('devices');
-
-		const lines = cleanOutput(out);
-
-		expect(lines[0].replace(/  +/g, ' ')).to.equal(
-			'ID UUID DEVICE NAME DEVICE TYPE FLEET STATUS IS ONLINE SUPERVISOR VERSION OS VERSION DASHBOARD URL',
-		);
-		expect(lines).to.have.lengthOf.at.least(2);
-
-		expect(lines.some((l) => l.includes('org/test app'))).to.be.true;
-
-		// Devices with missing applications will have application name set to `N/a`.
-		// e.g. When user has a device associated with app that user is no longer a collaborator of.
-		expect(lines.some((l) => l.includes('N/a'))).to.be.true;
-	});
-});

tests/commands/help.spec.ts

@@ -32,7 +32,6 @@ PRIMARY COMMANDS
   ssh <applicationOrDevice> [service]    SSH into the host or application container of a device
   apps                                   list all applications
   app <name>                             display information about a single application
-  devices                                list all devices
   device <uuid>                          show info about a single device
   tunnel <deviceOrApplication>           tunnel local ports to your balenaOS device
   preload <image>                        preload an app on a disk image (or Edison zip archive)
@@ -57,6 +56,7 @@ ADDITIONAL COMMANDS
   config write <key> <value>             write a key-value pair to configuration of a device or OS image
   device identify <uuid>                 identify a device
   device init                            initialise a device with balenaOS
+  device list                            list all devices
   device move <uuid(s)>                  move one or more devices to another application
   device os-update <uuid>                start a Host OS update for a device
   device public-url <uuid>               get or manage the public URL for a device