ExternalVendorCode/balena-cli
1
0
Fork 0
mirror of https://github.com/balena-io/balena-cli.git synced 2025-04-19 00:26:54 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge pull request #2514 from balena-io/v14

Browse Source 
Release v14
This commit is contained in:
bulldozer-balena[bot] 2022-08-02 15:05:58 +00:00 committed by GitHub
commit c0902bb119
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
39 changed files with 203 additions and 409 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

221
docs/balena-cli.md
View File

@ -333,11 +333,35 @@ Examples:
### Options
#### --fields FIELDS
only show provided fields (comma-separated)
#### -j, --json
output in json format
#### --filter FILTER
filter results by substring matching of a given field, eg: --filter field=foo
#### --no-header
hide table header from output
#### --no-truncate
do not truncate output to fit screen
#### --sort SORT
field to sort by (prepend '-' for descending order)
## fleet <fleet>
Display detailed information about a single fleet.
Fleets may be specified by fleet name, slug, or numeric ID. Fleet slugs are
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
@ -345,9 +369,7 @@ 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). Numeric fleet IDs are deprecated because they consist of an
implementation detail of the balena backend. We intend to remove support for
numeric IDs at some point in the future.
environments).
Examples:
@ -359,7 +381,7 @@ Examples:
#### FLEET
fleet name, slug (preferred), or numeric ID (deprecated)
fleet name or slug (preferred)
### Options
@ -367,6 +389,14 @@ fleet name, slug (preferred), or numeric ID (deprecated)
open fleet dashboard page
#### --fields FIELDS
only show provided fields (comma-separated)
#### -j, --json
output in json format
## fleet create <name>
Create a new balena fleet.
@ -413,7 +443,7 @@ fleet device type (Check available types with `balena devices supported`)
Purge data from all devices belonging to a fleet.
This will clear the fleet's '/data' directory.
Fleets may be specified by fleet name, slug, or numeric ID. Fleet slugs are
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
@ -421,9 +451,7 @@ 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). Numeric fleet IDs are deprecated because they consist of an
implementation detail of the balena backend. We intend to remove support for
numeric IDs at some point in the future.
environments).
Examples:
@ -434,7 +462,7 @@ Examples:
#### FLEET
fleet name, slug (preferred), or numeric ID (deprecated)
fleet name or slug (preferred)
### Options
@ -445,7 +473,7 @@ Rename a fleet.
Note, if the `newName` parameter is omitted, it will be
prompted for interactively.
Fleets may be specified by fleet name, slug, or numeric ID. Fleet slugs are
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
@ -453,9 +481,7 @@ 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). Numeric fleet IDs are deprecated because they consist of an
implementation detail of the balena backend. We intend to remove support for
numeric IDs at some point in the future.
environments).
Examples:
@ -467,7 +493,7 @@ Examples:
#### FLEET
fleet name, slug (preferred), or numeric ID (deprecated)
fleet name or slug (preferred)
#### NEWNAME
@ -479,7 +505,7 @@ the new name for the fleet
Restart all devices belonging to a fleet.
Fleets may be specified by fleet name, slug, or numeric ID. Fleet slugs are
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
@ -487,9 +513,7 @@ 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). Numeric fleet IDs are deprecated because they consist of an
implementation detail of the balena backend. We intend to remove support for
numeric IDs at some point in the future.
environments).
Examples:
@ -500,7 +524,7 @@ Examples:
#### FLEET
fleet name, slug (preferred), or numeric ID (deprecated)
fleet name or slug (preferred)
### Options
@ -510,7 +534,7 @@ Permanently remove a fleet.
The --yes option may be used to avoid interactive confirmation.
Fleets may be specified by fleet name, slug, or numeric ID. Fleet slugs are
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
@ -518,9 +542,7 @@ 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). Numeric fleet IDs are deprecated because they consist of an
implementation detail of the balena backend. We intend to remove support for
numeric IDs at some point in the future.
environments).
Examples:
@ -532,7 +554,7 @@ Examples:
#### FLEET
fleet name, slug (preferred), or numeric ID (deprecated)
fleet name or slug (preferred)
### Options
@ -623,7 +645,7 @@ List all of your devices.
Devices can be filtered by fleet with the `--fleet` option.
Fleets may be specified by fleet name, slug, or numeric ID. Fleet slugs are
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
@ -631,9 +653,7 @@ 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). Numeric fleet IDs are deprecated because they consist of an
implementation detail of the balena backend. We intend to remove support for
numeric IDs at some point in the future.
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
@ -651,7 +671,7 @@ Examples:
#### -f, --fleet FLEET
fleet name, slug (preferred), or numeric ID (deprecated)
fleet name or slug (preferred)
#### -j, --json
@ -763,7 +783,7 @@ If the '--fleet' or '--drive' options are omitted, interactive menus will be
presented with values to choose from. If the '--os-version' option is omitted,
the latest released OS version for the fleet's default device type will be used.
Fleets may be specified by fleet name, slug, or numeric ID. Fleet slugs are
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
@ -771,9 +791,7 @@ 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). Numeric fleet IDs are deprecated because they consist of an
implementation detail of the balena backend. We intend to remove support for
numeric IDs at some point in the future.
environments).
Image configuration questions will be asked interactively unless a pre-configured
'config.json' file is provided with the '--config' option. The file can be
@ -789,7 +807,7 @@ Examples:
#### -f, --fleet FLEET
fleet name, slug (preferred), or numeric ID (deprecated)
fleet name or slug (preferred)
#### -y, --yes
@ -863,7 +881,7 @@ Move one or more devices to another fleet.
If --fleet is omitted, the fleet will be prompted for interactively.
Fleets may be specified by fleet name, slug, or numeric ID. Fleet slugs are
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
@ -871,9 +889,7 @@ 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). Numeric fleet IDs are deprecated because they consist of an
implementation detail of the balena backend. We intend to remove support for
numeric IDs at some point in the future.
environments).
Examples:
@ -892,7 +908,7 @@ comma-separated list (no blank spaces) of device UUIDs to be moved
#### -f, --fleet FLEET
fleet name, slug (preferred), or numeric ID (deprecated)
fleet name or slug (preferred)
## device os-update <uuid>
@ -930,9 +946,6 @@ 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.
The old command style 'balena device public-url enable <uuid>'
is deprecated, but still supported.
Examples:
$ balena device public-url 23c73a1
@ -946,10 +959,6 @@ Examples:
the uuid of the device to manage
#### LEGACYUUID
### Options
#### --enable
@ -1011,7 +1020,7 @@ Register a new device with a balena fleet.
If --uuid is not provided, a new UUID will be automatically assigned.
Fleets may be specified by fleet name, slug, or numeric ID. Fleet slugs are
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
@ -1019,9 +1028,7 @@ 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). Numeric fleet IDs are deprecated because they consist of an
implementation detail of the balena backend. We intend to remove support for
numeric IDs at some point in the future.
environments).
Examples:
@ -1033,7 +1040,7 @@ Examples:
#### FLEET
fleet name, slug (preferred), or numeric ID (deprecated)
fleet name or slug (preferred)
### Options
@ -1247,7 +1254,7 @@ 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, slug, or numeric ID. Fleet slugs are
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
@ -1255,9 +1262,7 @@ 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). Numeric fleet IDs are deprecated because they consist of an
implementation detail of the balena backend. We intend to remove support for
numeric IDs at some point in the future.
environments).
Examples:
@ -1275,7 +1280,7 @@ Examples:
#### -f, --fleet FLEET
fleet name, slug (preferred), or numeric ID (deprecated)
fleet name or slug (preferred)
#### -c, --config
@ -1385,7 +1390,7 @@ 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, slug, or numeric ID. Fleet slugs are
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
@ -1393,9 +1398,7 @@ 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). Numeric fleet IDs are deprecated because they consist of an
implementation detail of the balena backend. We intend to remove support for
numeric IDs at some point in the future.
environments).
Examples:
@ -1423,7 +1426,7 @@ variable value; if omitted, use value from this process' environment
#### -f, --fleet FLEET
fleet name, slug (preferred), or numeric ID (deprecated)
fleet name or slug (preferred)
#### -d, --device DEVICE
@ -1506,7 +1509,7 @@ select a service variable (may be used together with the --device option)
List all tags and their values for the specified fleet, device or release.
Fleets may be specified by fleet name, slug, or numeric ID. Fleet slugs are
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
@ -1514,9 +1517,7 @@ 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). Numeric fleet IDs are deprecated because they consist of an
implementation detail of the balena backend. We intend to remove support for
numeric IDs at some point in the future.
environments).
Examples:
@ -1530,7 +1531,7 @@ Examples:
#### -f, --fleet FLEET
fleet name, slug (preferred), or numeric ID (deprecated)
fleet name or slug (preferred)
#### -d, --device DEVICE
@ -1544,7 +1545,7 @@ release id
Remove a tag from a fleet, device or release.
Fleets may be specified by fleet name, slug, or numeric ID. Fleet slugs are
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
@ -1552,9 +1553,7 @@ 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). Numeric fleet IDs are deprecated because they consist of an
implementation detail of the balena backend. We intend to remove support for
numeric IDs at some point in the future.
environments).
Examples:
@ -1574,7 +1573,7 @@ the key string of the tag
#### -f, --fleet FLEET
fleet name, slug (preferred), or numeric ID (deprecated)
fleet name or slug (preferred)
#### -d, --device DEVICE
@ -1592,7 +1591,7 @@ You can optionally provide a value to be associated with the created
tag, as an extra argument after the tag key. If a value isn't
provided, a tag with an empty value is created.
Fleets may be specified by fleet name, slug, or numeric ID. Fleet slugs are
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
@ -1600,9 +1599,7 @@ 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). Numeric fleet IDs are deprecated because they consist of an
implementation detail of the balena backend. We intend to remove support for
numeric IDs at some point in the future.
environments).
Examples:
@ -1629,7 +1626,7 @@ the optional value associated with the tag
#### -f, --fleet FLEET
fleet name, slug (preferred), or numeric ID (deprecated)
fleet name or slug (preferred)
#### -d, --device DEVICE
@ -1914,7 +1911,7 @@ Examples:
#### FLEETORDEVICE
fleet name/slug/id, device uuid, or address of local device
fleet name/slug, device uuid, or address of local device
#### SERVICE
@ -1982,7 +1979,7 @@ Examples:
#### DEVICEORFLEET
device UUID or fleet name/slug/ID
device UUID or fleet name/slug
### Options
@ -2161,7 +2158,7 @@ are multiple files to inject. See connection profile examples and reference at:
https://www.balena.io/docs/reference/OS/network/2.x/
https://developer.gnome.org/NetworkManager/stable/ref-settings.html
Fleets may be specified by fleet name, slug, or numeric ID. Fleet slugs are
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
@ -2169,9 +2166,7 @@ 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). Numeric fleet IDs are deprecated because they consist of an
implementation detail of the balena backend. We intend to remove support for
numeric IDs at some point in the future.
environments).
Note: This command is currently not supported on Windows natively. Windows users
are advised to install the Windows Subsystem for Linux (WSL) with Ubuntu, and use
@ -2200,7 +2195,7 @@ ask advanced configuration questions (when in interactive mode)
#### -f, --fleet FLEET
fleet name, slug (preferred), or numeric ID (deprecated)
fleet name or slug (preferred)
#### --config CONFIG
@ -2314,7 +2309,7 @@ alongside the --deviceType option to specify the target device type.
To avoid interactive questions, specify a command line option for each question that
would otherwise be asked.
Fleets may be specified by fleet name, slug, or numeric ID. Fleet slugs are
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
@ -2322,9 +2317,7 @@ 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). Numeric fleet IDs are deprecated because they consist of an
implementation detail of the balena backend. We intend to remove support for
numeric IDs at some point in the future.
environments).
Examples:
@ -2345,7 +2338,7 @@ a balenaOS version
#### -f, --fleet FLEET
fleet name, slug (preferred), or numeric ID (deprecated)
fleet name or slug (preferred)
#### --dev
@ -2416,10 +2409,6 @@ the path to the config.json file to inject
### Options
#### -t, --type TYPE
ignored - no longer required
#### -d, --drive DRIVE
path to OS image file (e.g. balena.img) or block device (e.g. /dev/disk2)
@ -2440,10 +2429,6 @@ Examples:
### Options
#### -t, --type TYPE
ignored - no longer required
#### -d, --drive DRIVE
path to OS image file (e.g. balena.img) or block device (e.g. /dev/disk2)
@ -2471,10 +2456,6 @@ Examples:
### Options
#### -t, --type TYPE
ignored - no longer required
#### -d, --drive DRIVE
path to OS image file (e.g. balena.img) or block device (e.g. /dev/disk2)
@ -2513,10 +2494,6 @@ the value of the config parameter to write
### Options
#### -t, --type TYPE
ignored - no longer required
#### -d, --drive DRIVE
path to OS image file (e.g. balena.img) or block device (e.g. /dev/disk2)
@ -2537,7 +2514,7 @@ Check also the Preloading and Preregistering section of the balena CLI's advance
masterclass document:
https://www.balena.io/docs/learn/more/masterclasses/advanced-cli/#5-preloading-and-preregistering
Fleets may be specified by fleet name, slug, or numeric ID. Fleet slugs are
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
@ -2545,9 +2522,7 @@ 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). Numeric fleet IDs are deprecated because they consist of an
implementation detail of the balena backend. We intend to remove support for
numeric IDs at some point in the future.
environments).
Note that the this command requires Docker to be installed, as further detailed
in the balena CLI's installation instructions:
@ -2573,7 +2548,7 @@ the image file path
#### -f, --fleet FLEET
fleet name, slug (preferred), or numeric ID (deprecated)
fleet name or slug (preferred)
#### -c, --commit COMMIT
@ -3037,7 +3012,7 @@ the type of device this build is for
#### -f, --fleet FLEET
fleet name, slug (preferred), or numeric ID (deprecated)
fleet name or slug (preferred)
#### -e, --emulated
@ -3047,10 +3022,6 @@ Use QEMU for ARM architecture emulation during the image build
Alternative Dockerfile name/path, relative to the source folder
#### --logs
No-op and deprecated since balena CLI v12.0.0. Build logs are now shown by default.
#### --nologs
Hide the image build log output (produce less verbose output)
@ -3231,7 +3202,7 @@ Examples:
#### FLEET
fleet name, slug (preferred), or numeric ID (deprecated)
fleet name or slug (preferred)
#### IMAGE
@ -3276,10 +3247,6 @@ Use QEMU for ARM architecture emulation during the image build
Alternative Dockerfile name/path, relative to the source folder
#### --logs
No-op and deprecated since balena CLI v12.0.0. Build logs are now shown by default.
#### --nologs
Hide the image build log output (produce less verbose output)
@ -3373,7 +3340,7 @@ scan the local network for balenaOS devices and prompt you to select one
from an interactive picker. This may require administrator/root privileges.
Likewise, if the fleet option is not provided then a picker will be shown.
Fleets may be specified by fleet name, slug, or numeric ID. Fleet slugs are
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
@ -3381,9 +3348,7 @@ 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). Numeric fleet IDs are deprecated because they consist of an
implementation detail of the balena backend. We intend to remove support for
numeric IDs at some point in the future.
environments).
Examples:
@ -3404,7 +3369,7 @@ the IP or hostname of device
#### -f, --fleet FLEET
fleet name, slug (preferred), or numeric ID (deprecated)
fleet name or slug (preferred)
#### -i, --pollInterval POLLINTERVAL
@ -3460,7 +3425,7 @@ or hours, e.g. '12h', '2d'.
Both --device and --fleet flags accept multiple values, specified as
a comma-separated list (with no spaces).
Fleets may be specified by fleet name, slug, or numeric ID. Fleet slugs are
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
@ -3468,9 +3433,7 @@ 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). Numeric fleet IDs are deprecated because they consist of an
implementation detail of the balena backend. We intend to remove support for
numeric IDs at some point in the future.
environments).
Examples:

8
lib/commands/config/generate.ts
View File

@ -150,11 +150,9 @@ export default class ConfigGenerateCmd extends Command {
| (DeviceWithDeviceType & { belongs_to__application: PineDeferred })
| null = null;
if (options.device != null) {
const { tryAsInteger } = await import('../../utils/validation');
const rawDevice = await balena.models.device.get(
tryAsInteger(options.device),
{ $expand: { is_of__device_type: { $select: 'slug' } } },
);
const rawDevice = await balena.models.device.get(options.device, {
$expand: { is_of__device_type: { $select: 'slug' } },
});
if (!rawDevice.belongs_to__application) {
const { ExpectedError } = await import('../../errors');
throw new ExpectedError(stripIndent`

1
lib/commands/config/inject.ts
View File

@ -57,7 +57,6 @@ export default class ConfigInjectCmd extends Command {
public static usage = 'config inject <file>';
public static flags: flags.Input<FlagsDef> = {
...cf.deviceTypeIgnored,
drive: cf.driveOrImg,
help: cf.help,
};

1
lib/commands/config/read.ts
View File

@ -47,7 +47,6 @@ export default class ConfigReadCmd extends Command {
public static usage = 'config read';
public static flags: flags.Input<FlagsDef> = {
...cf.deviceTypeIgnored,
drive: cf.driveOrImg,
help: cf.help,
json: cf.json,

1
lib/commands/config/reconfigure.ts
View File

@ -50,7 +50,6 @@ export default class ConfigReconfigureCmd extends Command {
public static usage = 'config reconfigure';
public static flags: flags.Input<FlagsDef> = {
...cf.deviceTypeIgnored,
drive: cf.driveOrImg,
advanced: flags.boolean({
description: 'show advanced commands',

1
lib/commands/config/write.ts
View File

@ -64,7 +64,6 @@ export default class ConfigWriteCmd extends Command {
public static usage = 'config write <key> <value>';
public static flags: flags.Input<FlagsDef> = {
...cf.deviceTypeIgnored,
drive: cf.driveOrImg,
help: cf.help,
};

2
lib/commands/device/identify.ts
View File

@ -20,7 +20,6 @@ import type { IArg } from '@oclif/parser/lib/args';
import Command from '../../command';
import * as cf from '../../utils/common-flags';
import { getBalenaSdk, stripIndent } from '../../utils/lazy';
import { tryAsInteger } from '../../utils/validation';
import { ExpectedError } from '../../errors';
interface FlagsDef {
@ -43,7 +42,6 @@ export default class DeviceIdentifyCmd extends Command {
{
name: 'uuid',
description: 'the uuid of the device to identify',
parse: (dev) => tryAsInteger(dev),
required: true,
},
];

2
lib/commands/device/index.ts
View File

@ -21,7 +21,6 @@ import Command from '../../command';
import * as cf from '../../utils/common-flags';
import { expandForAppName } from '../../utils/helpers';
import { getBalenaSdk, getVisuals, stripIndent } from '../../utils/lazy';
import { tryAsInteger } from '../../utils/validation';
import type { Application, Release } from 'balena-sdk';
@ -66,7 +65,6 @@ export default class DeviceCmd extends Command {
{
name: 'uuid',
description: 'the device uuid',
parse: (dev) => tryAsInteger(dev),
required: true,
},
];

2
lib/commands/device/init.ts
View File

@ -128,7 +128,7 @@ export default class DeviceInitCmd extends Command {
options.fleet ||
(
await (await import('../../utils/patterns')).selectApplication()
).id,
).slug,
{
$expand: {
is_for__device_type: {

2
lib/commands/device/local-mode.ts
View File

@ -20,7 +20,6 @@ import type { IArg } from '@oclif/parser/lib/args';
import Command from '../../command';
import * as cf from '../../utils/common-flags';
import { getBalenaSdk, stripIndent } from '../../utils/lazy';
import { tryAsInteger } from '../../utils/validation';
interface FlagsDef {
enable: boolean;
@ -52,7 +51,6 @@ export default class DeviceLocalModeCmd extends Command {
{
name: 'uuid',
description: 'the uuid of the device to manage',
parse: (dev) => tryAsInteger(dev),
required: true,
},
];

13
lib/commands/device/move.ts
View File

@ -88,17 +88,14 @@ export default class DeviceMoveCmd extends Command {
const balena = getBalenaSdk();
const { tryAsInteger } = await import('../../utils/validation');
const { expandForAppNameAndCpuArch } = await import('../../utils/helpers');
// Parse ids string into array of correct types
const deviceIds: Array<string | number> = params.uuid
.split(',')
.map((id) => tryAsInteger(id));
// Split uuids string into array of uuids
const deviceUuids = params.uuid.split(',');
// Get devices
const devices = await Promise.all(
deviceIds.map(
deviceUuids.map(
(uuid) =>
balena.models.device.get(
uuid,
@ -115,7 +112,7 @@ export default class DeviceMoveCmd extends Command {
: 'N/a';
}
// Disambiguate application (if is a number, it could either be an ID or a numerical name)
// Disambiguate application
const { getApplication } = await import('../../utils/sdk');
// Get destination application
@ -124,7 +121,7 @@ export default class DeviceMoveCmd extends Command {
: await this.interactivelySelectApplication(balena, devices);
// Move each device
for (const uuid of deviceIds) {
for (const uuid of deviceUuids) {
try {
await balena.models.device.move(uuid, application.id);
console.info(`Device ${uuid} was moved to fleet ${application.slug}`);

2
lib/commands/device/os-update.ts
View File

@ -20,7 +20,6 @@ import type { IArg } from '@oclif/parser/lib/args';
import Command from '../../command';
import * as cf from '../../utils/common-flags';
import { getBalenaSdk, stripIndent, getCliForm } from '../../utils/lazy';
import { tryAsInteger } from '../../utils/validation';
import type { Device } from 'balena-sdk';
import { ExpectedError } from '../../errors';
@ -54,7 +53,6 @@ export default class DeviceOsUpdateCmd extends Command {
{
name: 'uuid',
description: 'the uuid of the device to update',
parse: (dev) => tryAsInteger(dev),
required: true,
},
];

32
lib/commands/device/public-url.ts
View File

@ -21,7 +21,6 @@ import Command from '../../command';
import { ExpectedError } from '../../errors';
import * as cf from '../../utils/common-flags';
import { getBalenaSdk, stripIndent } from '../../utils/lazy';
import { tryAsInteger } from '../../utils/validation';
interface FlagsDef {
enable: boolean;
@ -32,8 +31,6 @@ interface FlagsDef {
interface ArgsDef {
uuid: string;
// Optional hidden arg to support old command format
legacyUuid?: string;
}
export default class DevicePublicUrlCmd extends Command {
@ -43,9 +40,6 @@ export default class DevicePublicUrlCmd extends Command {
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.
The old command style 'balena device public-url enable <uuid>'
is deprecated, but still supported.
`;
public static examples = [
@ -59,15 +53,8 @@ export default class DevicePublicUrlCmd extends Command {
{
name: 'uuid',
description: 'the uuid of the device to manage',
parse: (dev) => tryAsInteger(dev),
required: true,
},
{
// Optional hidden arg to support old command format
name: 'legacyUuid',
parse: (dev) => tryAsInteger(dev),
hidden: true,
},
];
public static usage = 'device public-url <uuid>';
@ -95,25 +82,6 @@ export default class DevicePublicUrlCmd extends Command {
DevicePublicUrlCmd,
);
// Legacy command format support.
// Previously this command used the following format
// (changed due to oclif technicalities):
// `balena device public-url enable|disable|status <uuid>`
if (params.legacyUuid) {
const action = params.uuid;
if (!['enable', 'disable', 'status'].includes(action)) {
throw new ExpectedError(
`Unexpected arguments: ${params.uuid} ${params.legacyUuid}`,
);
}
options.enable = action === 'enable';
options.disable = action === 'disable';
options.status = action === 'status';
params.uuid = params.legacyUuid;
delete params.legacyUuid;
}
const balena = getBalenaSdk();
if (options.enable) {

11
lib/commands/device/purge.ts
View File

@ -63,17 +63,14 @@ export default class DevicePurgeCmd extends Command {
public async run() {
const { args: params } = this.parse<FlagsDef, ArgsDef>(DevicePurgeCmd);
const { tryAsInteger } = await import('../../utils/validation');
const balena = getBalenaSdk();
const ux = getCliUx();
const deviceIds = params.uuid.split(',').map((id) => {
return tryAsInteger(id);
});
const deviceUuids = params.uuid.split(',');
for (const deviceId of deviceIds) {
ux.action.start(`Purging data from device ${deviceId}`);
await balena.models.device.purge(deviceId);
for (const uuid of deviceUuids) {
ux.action.start(`Purging data from device ${uuid}`);
await balena.models.device.purge(uuid);
ux.action.stop();
}
}

2
lib/commands/device/reboot.ts
View File

@ -20,7 +20,6 @@ import type { IArg } from '@oclif/parser/lib/args';
import Command from '../../command';
import * as cf from '../../utils/common-flags';
import { getBalenaSdk, stripIndent } from '../../utils/lazy';
import { tryAsInteger } from '../../utils/validation';
interface FlagsDef {
force: boolean;
@ -43,7 +42,6 @@ export default class DeviceRebootCmd extends Command {
{
name: 'uuid',
description: 'the uuid of the device to reboot',
parse: (dev) => tryAsInteger(dev),
required: true,
},
];

2
lib/commands/device/rename.ts
View File

@ -20,7 +20,6 @@ import type { IArg } from '@oclif/parser/lib/args';
import Command from '../../command';
import * as cf from '../../utils/common-flags';
import { getBalenaSdk, stripIndent, getCliForm } from '../../utils/lazy';
import { tryAsInteger } from '../../utils/validation';
interface FlagsDef {
help: void;
@ -48,7 +47,6 @@ export default class DeviceRenameCmd extends Command {
{
name: 'uuid',
description: 'the uuid of the device to rename',
parse: (dev) => tryAsInteger(dev),
required: true,
},
{

37
lib/commands/device/restart.ts
View File

@ -82,24 +82,21 @@ export default class DeviceRestartCmd extends Command {
DeviceRestartCmd,
);
const { tryAsInteger } = await import('../../utils/validation');
const balena = getBalenaSdk();
const ux = getCliUx();
const deviceIds = params.uuid.split(',').map((id) => {
return tryAsInteger(id);
});
const deviceUuids = params.uuid.split(',');
const serviceNames = options.service?.split(',');
// Iterate sequentially through deviceIds.
// Iterate sequentially through deviceUuids.
// We may later want to add a batching feature,
// so that n devices are processed in parallel
for (const deviceId of deviceIds) {
ux.action.start(`Restarting services on device ${deviceId}`);
for (const uuid of deviceUuids) {
ux.action.start(`Restarting services on device ${uuid}`);
if (serviceNames) {
await this.restartServices(balena, deviceId, serviceNames);
await this.restartServices(balena, uuid, serviceNames);
} else {
await this.restartAllServices(balena, deviceId);
await this.restartAllServices(balena, uuid);
}
ux.action.stop();
}
@ -107,7 +104,7 @@ export default class DeviceRestartCmd extends Command {
async restartServices(
balena: BalenaSDK,
deviceId: number | string,
deviceUuid: string,
serviceNames: string[],
) {
const { ExpectedError, instanceOf } = await import('../../errors');
@ -116,7 +113,7 @@ export default class DeviceRestartCmd extends Command {
// Get device
let device: DeviceWithServiceDetails<CurrentServiceWithCommit>;
try {
device = await balena.models.device.getWithServiceDetails(deviceId, {
device = await balena.models.device.getWithServiceDetails(deviceUuid, {
$expand: {
is_running__release: { $select: 'commit' },
},
@ -124,7 +121,7 @@ export default class DeviceRestartCmd extends Command {
} catch (e) {
const { BalenaDeviceNotFound } = await import('balena-errors');
if (instanceOf(e, BalenaDeviceNotFound)) {
throw new ExpectedError(`Device ${deviceId} not found.`);
throw new ExpectedError(`Device ${deviceUuid} not found.`);
} else {
throw e;
}
@ -136,7 +133,7 @@ export default class DeviceRestartCmd extends Command {
serviceNames.forEach((service) => {
if (!device.current_services[service]) {
throw new ExpectedError(
`Service ${service} not found on device ${deviceId}.`,
`Service ${service} not found on device ${deviceUuid}.`,
);
}
});
@ -155,7 +152,7 @@ export default class DeviceRestartCmd extends Command {
if (serviceContainer) {
restartPromises.push(
balena.models.device.restartService(
deviceId,
deviceUuid,
serviceContainer.image_id,
),
);
@ -166,32 +163,32 @@ export default class DeviceRestartCmd extends Command {
await Promise.all(restartPromises);
} catch (e) {
if (e.message.toLowerCase().includes('no online device')) {
throw new ExpectedError(`Device ${deviceId} is not online.`);
throw new ExpectedError(`Device ${deviceUuid} is not online.`);
} else {
throw e;
}
}
}
async restartAllServices(balena: BalenaSDK, deviceId: number | string) {
async restartAllServices(balena: BalenaSDK, deviceUuid: string) {
// Note: device.restartApplication throws `BalenaDeviceNotFound: Device not found` if device not online.
// Need to use device.get first to distinguish between non-existant and offline devices.
// Remove this workaround when SDK issue resolved: https://github.com/balena-io/balena-sdk/issues/649
const { instanceOf, ExpectedError } = await import('../../errors');
try {
const device = await balena.models.device.get(deviceId);
const device = await balena.models.device.get(deviceUuid);
if (!device.is_online) {
throw new ExpectedError(`Device ${deviceId} is not online.`);
throw new ExpectedError(`Device ${deviceUuid} is not online.`);
}
} catch (e) {
const { BalenaDeviceNotFound } = await import('balena-errors');
if (instanceOf(e, BalenaDeviceNotFound)) {
throw new ExpectedError(`Device ${deviceId} not found.`);
throw new ExpectedError(`Device ${deviceUuid} not found.`);
} else {
throw e;
}
}
await balena.models.device.restartApplication(deviceId);
await balena.models.device.restartApplication(deviceUuid);
}
}

3
lib/commands/device/rm.ts
View File

@ -20,7 +20,6 @@ import type { IArg } from '@oclif/parser/lib/args';
import Command from '../../command';
import * as cf from '../../utils/common-flags';
import { getBalenaSdk, stripIndent } from '../../utils/lazy';
import { tryAsInteger } from '../../utils/validation';
interface FlagsDef {
yes: boolean;
@ -84,7 +83,7 @@ export default class DeviceRmCmd extends Command {
// Remove
for (const uuid of uuids) {
try {
await balena.models.device.remove(tryAsInteger(uuid));
await balena.models.device.remove(uuid);
} catch (err) {
console.info(`${err.message}, uuid: ${uuid}`);
process.exitCode = 1;

2
lib/commands/device/shutdown.ts
View File

@ -20,7 +20,6 @@ import type { IArg } from '@oclif/parser/lib/args';
import Command from '../../command';
import * as cf from '../../utils/common-flags';
import { getBalenaSdk, stripIndent } from '../../utils/lazy';
import { tryAsInteger } from '../../utils/validation';
import { ExpectedError } from '../../errors';
interface FlagsDef {
@ -44,7 +43,6 @@ export default class DeviceShutdownCmd extends Command {
{
name: 'uuid',
description: 'the uuid of the device to shutdown',
parse: (dev) => tryAsInteger(dev),
required: true,
},
];

28
lib/commands/fleet/index.ts
View File

@ -22,9 +22,8 @@ import type { Release } from 'balena-sdk';
import Command from '../../command';
import * as cf from '../../utils/common-flags';
import * as ca from '../../utils/common-args';
import { getBalenaSdk, getVisuals, stripIndent } from '../../utils/lazy';
import { getBalenaSdk, stripIndent } from '../../utils/lazy';
import { applicationIdInfo } from '../../utils/messages';
import { isV14 } from '../../utils/version';
import type { DataOutputOptions } from '../../framework';
interface FlagsDef extends DataOutputOptions {
@ -60,7 +59,7 @@ export default class FleetCmd extends Command {
default: false,
description: 'open fleet dashboard page',
}),
...(isV14() ? cf.dataOutputFlags : {}),
...cf.dataOutputFlags,
};
public static authenticated = true;
@ -99,23 +98,10 @@ export default class FleetCmd extends Command {
application.device_type = application.is_for__device_type[0].slug;
application.commit = application.should_be_running__release[0]?.commit;
if (isV14()) {
await this.outputData(
application,
['app_name', 'id', 'device_type', 'slug', 'commit'],
options,
);
} else {
// Emulate table.vertical title output, but avoid uppercasing and inserting spaces
console.log(`== ${application.slug}`);
console.log(
getVisuals().table.vertical(application, [
'id',
'device_type',
'slug',
'commit',
]),
);
}
await this.outputData(
application,
['app_name', 'id', 'device_type', 'slug', 'commit'],
options,
);
}
}

4
lib/commands/fleet/restart.ts
View File

@ -62,9 +62,9 @@ export default class FleetRestartCmd extends Command {
const balena = getBalenaSdk();
// Disambiguate application (if is a number, it could either be an ID or a numerical name)
// Disambiguate application
const application = await getApplication(balena, params.fleet);
await balena.models.application.restart(application.id);
await balena.models.application.restart(application.slug);
}
}

2
lib/commands/fleet/rm.ts
View File

@ -79,6 +79,6 @@ export default class FleetRmCmd extends Command {
const application = await getApplication(balena, params.fleet);
// Remove
await balena.models.application.remove(application.id);
await balena.models.application.remove(application.slug);
}
}

42
lib/commands/fleets.ts
View File

@ -19,8 +19,7 @@ import { flags } from '@oclif/command';
import Command from '../command';
import * as cf from '../utils/common-flags';
import { getBalenaSdk, getVisuals, stripIndent } from '../utils/lazy';
import { isV14 } from '../utils/version';
import { getBalenaSdk, stripIndent } from '../utils/lazy';
import type { DataSetOutputOptions } from '../framework';
interface ExtendedApplication extends ApplicationWithDeviceType {
@ -49,7 +48,7 @@ export default class FleetsCmd extends Command {
public static usage = 'fleets';
public static flags: flags.Input<FlagsDef> = {
...(isV14() ? cf.dataSetOutputFlags : {}),
...cf.dataSetOutputFlags,
help: cf.help,
};
@ -79,30 +78,17 @@ export default class FleetsCmd extends Command {
application.device_type = application.is_for__device_type[0].slug;
});
if (isV14()) {
await this.outputData(
applications,
[
'id',
'app_name',
'slug',
'device_type',
'device_count',
'online_devices',
],
options,
);
} else {
console.log(
getVisuals().table.horizontal(applications, [
'id',
'app_name => NAME',
'slug',
'device_type',
'online_devices',
'device_count',
]),
);
}
await this.outputData(
applications,
[
'id',
'app_name',
'slug',
'device_type',
'device_count',
'online_devices',
],
options,
);
}
}

14
lib/commands/preload.ts
View File

@ -288,7 +288,7 @@ Can be repeated to add multiple certificates.\
preloader.on('error', reject);
resolve(
this.prepareAndPreload(preloader, balena, {
appId: fleetSlug,
slug: fleetSlug,
commit,
pinDevice,
}),
@ -491,10 +491,10 @@ Would you like to disable automatic updates for this fleet now?\
});
}
async getAppWithReleases(balenaSdk: BalenaSDK, appId: string) {
async getAppWithReleases(balenaSdk: BalenaSDK, slug: string) {
const { getApplication } = await import('../utils/sdk');
return (await getApplication(balenaSdk, appId, {
return (await getApplication(balenaSdk, slug, {
$expand: this.applicationExpandOptions,
})) as Application & { should_be_running__release: [Release?] };
}
@ -503,15 +503,15 @@ Would you like to disable automatic updates for this fleet now?\
preloader: Preloader,
balenaSdk: BalenaSDK,
options: {
appId?: string;
slug?: string;
commit?: string;
pinDevice: boolean;
},
) {
await preloader.prepare();
const application = options.appId
? await this.getAppWithReleases(balenaSdk, options.appId)
const application = options.slug
? await this.getAppWithReleases(balenaSdk, options.slug)
: await this.selectApplication(preloader.config.deviceType);
let commit: string; // commit hash or the strings 'latest' or 'current'
@ -523,7 +523,7 @@ Would you like to disable automatic updates for this fleet now?\
if (this.isCurrentCommit(options.commit)) {
if (!appCommit) {
throw new Error(
`Unexpected empty commit hash for fleet ID "${application.id}"`,
`Unexpected empty commit hash for fleet slug "${application.slug}"`,
);
}
// handle `--commit current` (and its `--commit latest` synonym)

3
lib/commands/ssh.ts
View File

@ -76,8 +76,7 @@ export default class SshCmd extends Command {
public static args = [
{
name: 'fleetOrDevice',
description:
'fleet name/slug/id, device uuid, or address of local device',
description: 'fleet name/slug, device uuid, or address of local device',
required: true,
},
{

7
lib/commands/tag/rm.ts
View File

@ -90,8 +90,6 @@ export default class TagRmCmd extends Command {
throw new ExpectedError(TagRmCmd.missingResourceMessage);
}
const { tryAsInteger } = await import('../../utils/validation');
if (options.fleet) {
const { getFleetSlug } = await import('../../utils/sdk');
return balena.models.application.tags.remove(
@ -100,10 +98,7 @@ export default class TagRmCmd extends Command {
);
}
if (options.device) {
return balena.models.device.tags.remove(
tryAsInteger(options.device),
params.tagKey,
);
return balena.models.device.tags.remove(options.device, params.tagKey);
}
if (options.release) {
const { disambiguateReleaseParam } = await import(

4
lib/commands/tag/set.ts
View File

@ -105,8 +105,6 @@ export default class TagSetCmd extends Command {
params.value ??= '';
const { tryAsInteger } = await import('../../utils/validation');
if (options.fleet) {
const { getFleetSlug } = await import('../../utils/sdk');
return balena.models.application.tags.set(
@ -117,7 +115,7 @@ export default class TagSetCmd extends Command {
}
if (options.device) {
return balena.models.device.tags.set(
tryAsInteger(options.device),
options.device,
params.tagKey,
params.value,
);

6
lib/commands/tags.ts
View File

@ -76,8 +76,6 @@ export default class TagsCmd extends Command {
throw new ExpectedError(this.missingResourceMessage);
}
const { tryAsInteger } = await import('../utils/validation');
let tags;
if (options.fleet) {
@ -87,9 +85,7 @@ export default class TagsCmd extends Command {
);
}
if (options.device) {
tags = await balena.models.device.tags.getAllByDevice(
tryAsInteger(options.device),
);
tags = await balena.models.device.tags.getAllByDevice(options.device);
}
if (options.release) {
const { disambiguateReleaseParam } = await import(

2
lib/commands/tunnel.ts
View File

@ -82,7 +82,7 @@ export default class TunnelCmd extends Command {
public static args = [
{
name: 'deviceOrFleet',
description: 'device UUID or fleet name/slug/ID',
description: 'device UUID or fleet name/slug',
required: true,
parse: lowercaseIfSlug,
},

2
lib/events.ts
View File

@ -24,7 +24,7 @@ import { stripIndent } from './utils/lazy';
* @param commandSignature A string like, for example:
* "push <fleetOrDevice>"
* That's literally so: "fleetOrDevice" is NOT replaced with the actual
* fleet ID or device ID. The purpose is to find out the most / least
* fleet slug or device uuid. The purpose is to find out the most / least
* used command verbs, so we can focus our development effort where it is most
* beneficial to end users.
*

2
lib/utils/common-args.ts
View File

@ -18,7 +18,7 @@ import { lowercaseIfSlug } from './normalization';
export const fleetRequired = {
name: 'fleet',
description: 'fleet name, slug (preferred), or numeric ID (deprecated)',
description: 'fleet name or slug (preferred)',
required: true,
parse: lowercaseIfSlug,
};

16
lib/utils/common-flags.ts
View File

@ -19,13 +19,12 @@ import { flags } from '@oclif/command';
import { stripIndent } from './lazy';
import { lowercaseIfSlug } from './normalization';
import { isV14 } from './version';
import type { IBooleanFlag } from '@oclif/parser/lib/flags';
import type { DataOutputOptions, DataSetOutputOptions } from '../framework';
export const fleet = flags.string({
char: 'f',
description: 'fleet name, slug (preferred), or numeric ID (deprecated)',
description: 'fleet name or slug (preferred)',
parse: lowercaseIfSlug,
});
@ -97,19 +96,6 @@ export const deviceType = flags.string({
required: true,
});
export const deviceTypeIgnored = {
...(isV14()
? {}
: {
type: flags.string({
description: 'ignored - no longer required',
char: 't',
required: false,
hidden: true,
}),
}),
};
export const json: IBooleanFlag<boolean> = flags.boolean({
char: 'j',
description: 'produce JSON output instead of tabular output',

1
lib/utils/compose-types.d.ts vendored
View File

@ -64,7 +64,6 @@ export interface ComposeOpts {
export interface ComposeCliFlags {
emulated: boolean;
dockerfile?: string;
logs: boolean;
nologs: boolean;
'multi-dockerignore': boolean;
'noparent-check': boolean;

4
lib/utils/compose_ts.ts
View File

@ -1653,10 +1653,6 @@ export const composeCliFlags: flags.Input<ComposeCliFlags> = {
description:
'Alternative Dockerfile name/path, relative to the source folder',
}),
logs: flags.boolean({
description:
'No-op and deprecated since balena CLI v12.0.0. Build logs are now shown by default.',
}),
nologs: flags.boolean({
description:
'Hide the image build log output (produce less verbose output)',

6
lib/utils/messages.ts
View File

@ -137,7 +137,7 @@ adding exception patterns to the applicable .dockerignore file(s), for example
- https://www.npmjs.com/package/@balena/dockerignore`;
export const applicationIdInfo = `\
Fleets may be specified by fleet name, slug, or numeric ID. Fleet slugs are
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
@ -145,9 +145,7 @@ 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). Numeric fleet IDs are deprecated because they consist of an
implementation detail of the balena backend. We intend to remove support for
numeric IDs at some point in the future.`;
environments).`;
export const applicationNameNote = `\
Fleets may be specified by fleet name or slug. Slugs are recommended because

47
lib/utils/patterns.ts
View File

@ -280,71 +280,64 @@ export function inferOrSelectDevice(preferredUuid: string) {
}
/*
* Given applicationOrDevice, which may be
* - an application name
* - an application slug
* - an application id (integer)
* Given fleetOrDevice, which may be
* - a fleet name
* - a fleet slug
* - a device uuid
* Either:
* - in case of device uuid, return uuid of device after verifying that it exists and is online.
* - in case of application, return uuid of device user selects from list of online devices.
*
* TODO: Modify this when app IDs dropped.
* - in case of fleet, return uuid of device user selects from list of online devices.
*/
export async function getOnlineTargetDeviceUuid(
sdk: BalenaSDK,
applicationOrDevice: string,
fleetOrDevice: string,
) {
const logger = (await import('../utils/logger')).getLogger();
// If looks like UUID, probably device
if (validation.validateUuid(applicationOrDevice)) {
if (validation.validateUuid(fleetOrDevice)) {
let device: Device;
try {
logger.logDebug(
`Trying to fetch device by UUID ${applicationOrDevice} (${typeof applicationOrDevice})`,
`Trying to fetch device by UUID ${fleetOrDevice} (${typeof fleetOrDevice})`,
);
device = await sdk.models.device.get(applicationOrDevice, {
device = await sdk.models.device.get(fleetOrDevice, {
$select: ['uuid', 'is_online'],
});
if (!device.is_online) {
throw new ExpectedError(
`Device with UUID ${applicationOrDevice} is offline`,
);
throw new ExpectedError(`Device with UUID ${fleetOrDevice} is offline`);
}
return device.uuid;
} catch (err) {
const { BalenaDeviceNotFound } = await import('balena-errors');
if (instanceOf(err, BalenaDeviceNotFound)) {
logger.logDebug(`Device with UUID ${applicationOrDevice} not found`);
// Now try app
logger.logDebug(`Device with UUID ${fleetOrDevice} not found`);
// Now try application
} else {
throw err;
}
}
}
// Not a device UUID, try app
let app: Application;
// Not a device UUID, try application
let application: Application;
try {
logger.logDebug(`Fetching fleet ${applicationOrDevice}`);
logger.logDebug(`Fetching fleet ${fleetOrDevice}`);
const { getApplication } = await import('./sdk');
app = await getApplication(sdk, applicationOrDevice);
application = await getApplication(sdk, fleetOrDevice);
} catch (err) {
const { BalenaApplicationNotFound } = await import('balena-errors');
if (instanceOf(err, BalenaApplicationNotFound)) {
throw new ExpectedError(
`Fleet or Device not found: ${applicationOrDevice}`,
);
throw new ExpectedError(`Fleet or Device not found: ${fleetOrDevice}`);
} else {
throw err;
}
}
// App found, load its devices
const devices = await sdk.models.device.getAllByApplication(app.id, {
const devices = await sdk.models.device.getAllByApplication(application.id, {
$select: ['device_name', 'uuid'],
$filter: { is_online: true },
});
@ -352,13 +345,13 @@ export async function getOnlineTargetDeviceUuid(
// Throw if no devices online
if (_.isEmpty(devices)) {
throw new ExpectedError(
`Fleet ${app.slug} found, but has no devices online.`,
`Fleet ${application.slug} found, but has no devices online.`,
);
}
// Ask user to select from online devices for application
// Ask user to select from online devices for fleet
return getCliForm().ask({
message: `Select a device on fleet ${app.slug}`,
message: `Select a device on fleet ${application.slug}`,
type: 'list',
default: devices[0].uuid,
choices: _.map(devices, (device) => ({

8
lib/utils/promote.ts
View File

@ -334,13 +334,7 @@ async function createApplication(
try {
await sdk.models.application.getDirectlyAccessible(appName, {
$filter: {
$or: [
{ slug: { $startswith: `${username!.toLowerCase()}/` } },
// TODO: do we still need the following filter? Is it for
// old openBalena instances where slugs were equal to the
// app name and did not contain the slash character?
{ $not: { slug: { $contains: '/' } } },
],
slug: { $startswith: `${username!.toLowerCase()}/` },
},
});
// TODO: This is the only example in the codebase where `printErrorMessage()`

59
lib/utils/sdk.ts
View File

@ -24,54 +24,32 @@ import type {
/**
* Get a fleet object, disambiguating the fleet identifier which may be a
* a fleet slug, name or numeric database ID (as a string).
* a fleet slug or name.
* TODO: add support for fleet UUIDs.
*/
export async function getApplication(
sdk: BalenaSDK,
nameOrSlugOrId: string | number,
nameOrSlug: string,
options?: PineOptions<Application>,
): Promise<Application> {
const { looksLikeFleetSlug, looksLikeInteger } = await import('./validation');
if (
typeof nameOrSlugOrId === 'string' &&
looksLikeFleetSlug(nameOrSlugOrId)
) {
return await sdk.models.application.getDirectlyAccessible(
nameOrSlugOrId,
const { looksLikeFleetSlug } = await import('./validation');
if (!looksLikeFleetSlug(nameOrSlug)) {
// Not a slug: must be an app name.
// TODO: revisit this logic when we add support for fleet UUIDs.
return await sdk.models.application.getAppByName(
nameOrSlug,
options,
'directly_accessible',
);
}
if (typeof nameOrSlugOrId === 'number' || looksLikeInteger(nameOrSlugOrId)) {
try {
// Test for existence of app with this numerical ID
return await sdk.models.application.getDirectlyAccessible(
Number(nameOrSlugOrId),
options,
);
} catch (e) {
if (typeof nameOrSlugOrId === 'number') {
throw e;
}
const { instanceOf } = await import('../errors');
const { BalenaApplicationNotFound } = await import('balena-errors');
if (!instanceOf(e, BalenaApplicationNotFound)) {
throw e;
}
// App with this numerical ID not found, but there may be an app with this numerical name.
}
}
// Not a slug and not a numeric database ID: must be an app name.
// TODO: revisit this logic when we add support for fleet UUIDs.
return await sdk.models.application.getAppByName(
nameOrSlugOrId,
return await sdk.models.application.getDirectlyAccessible(
nameOrSlug,
options,
'directly_accessible',
);
}
/**
* Given a fleet name, slug or numeric database ID, return its slug.
* Given a fleet name or slug, return its slug.
* This function conditionally makes an async SDK/API call to retrieve the
* application object, which can be wasteful if the application object is
* required before or after the call to this function. If this is the case,
@ -79,16 +57,15 @@ export async function getApplication(
*/
export async function getFleetSlug(
sdk: BalenaSDK,
nameOrSlugOrId: string | number,
nameOrSlug: string,
): Promise<string> {
const { looksLikeFleetSlug } = await import('./validation');
if (
typeof nameOrSlugOrId === 'string' &&
looksLikeFleetSlug(nameOrSlugOrId)
) {
return nameOrSlugOrId.toLowerCase();
if (!looksLikeFleetSlug(nameOrSlug)) {
// Not a slug: must be an app name.
// TODO: revisit this logic when we add support for fleet UUIDs.
return (await getApplication(sdk, nameOrSlug)).slug;
}
return (await getApplication(sdk, nameOrSlugOrId)).slug;
return nameOrSlug.toLowerCase();
}
/**

10
lib/utils/version.ts
View File

@ -21,13 +21,3 @@ import { version } from '../../package.json';
export function isVersionGTE(v: string): boolean {
return semver.gte(process.env.BALENA_CLI_VERSION_OVERRIDE || version, v);
}
let v14: boolean;
/** Feature switch for the next major version of the CLI */
export function isV14(): boolean {
if (v14 === undefined) {
v14 = isVersionGTE('14.0.0');
}
return v14;
}