v23.2.32

The balena CLI is a Command Line Interface for balenaCloud or openBalena. It is a software tool available for Windows, macOS and Linux, used through a command prompt / terminal window. It can be used interactively or invoked in scripts. The balena CLI builds on the balena API and the balena SDK, and can also be directly imported in Node.js applications. The balena CLI is an open-source project on GitHub, and your contribution is also welcome!

Installation

Check the balena CLI installation instructions on GitHub.

Note for v22 Migration: If you are upgrading to balena CLI v22 from a previous standalone installation, please see the v22 Migration Guide for installation changes.

Choosing a shell (command prompt/terminal)

On Windows, the standard Command Prompt (cmd.exe) and PowerShell are supported. Alternative shells include:

• MSYS2:

  • Install additional packages with the command: pacman -S git gcc make openssh p7zip
  • Set a Windows environment variable: MSYS2_PATH_TYPE=inherit
  • Note that a bug in the MSYS2 launch script (msys2_shell.cmd) makes text-based interactive CLI menus to break. Check this Github issue for a workaround.
• MSYS
• Git for Windows

  • During the installation, you will be prompted to choose between "Use MinTTY" and "Use Windows' default console window". Choose the latter, because of the same MSYS2 bug mentioned above (Git for Windows actually uses MSYS2). For a screenshot, check this comment.
• Microsoft's Windows Subsystem for Linux (WSL). In this case, a Linux distribution like Ubuntu is installed via the Microsoft Store, and a balena CLI release for Linux should be selected. See FAQ for using the balena CLI with WSL and Docker Desktop for Windows.

On macOS and Linux, the standard terminal window is supported. Optionally, bash command auto completion may be enabled by running balena autocomplete.

Logging in

Several CLI commands require access to your balenaCloud account, for example in order to push a new release to your fleet. Those commands require creating a CLI login session by running:

Proxy support

HTTP(S) proxies can be configured through any of the following methods, in precedence order (from higher to lower):

• The BALENARC_PROXY environment variable in URL format, with protocol (http or https), host, port and optionally basic auth. Examples:

  • export BALENARC_PROXY='https://bob:[e-mail]:12345'
  • export BALENARC_PROXY='http://localhost:8000'
• The proxy setting in the CLI config file. It may be:

  • A string in URL format, e.g. proxy: 'http://localhost:8000'
  • An object in the format:
• The HTTPS_PROXY and/or HTTP_PROXY environment variables, in the same URL format as BALENARC_PROXY.

Proxy setup for balena device ssh

In order to work behind a proxy server, the balena device ssh command requires the proxytunnel package (command-line tool) to be installed. proxytunnel is available for Linux distributions like Ubuntu/Debian (apt install proxytunnel), and for macOS through Homebrew. Windows support is limited to the Windows Subsystem for Linux (e.g., by installing Ubuntu through the Microsoft App Store).

Ensure that the proxy server is configured to allow proxy requests to ssh port 22, using SSL encryption. For example, in the case of the Squid proxy server, it should be configured with the following rules in the squid.conf file: acl SSL_ports port 22 acl Safe_ports port 22

Proxy exclusion

The BALENARC_NO_PROXY variable may be used to exclude specified destinations from proxying.

• This feature requires CLI version 11.30.8 or later. In the case of the npm installation option, it also requires Node.js version 10.16.0 or later.
• To exclude a balena device ssh target from proxying (IP address or .local hostname), the --noproxy option should be specified in addition to the BALENARC_NO_PROXY variable.

By default (if BALENARC_NO_PROXY is not defined), all private IPv4 addresses and '*.local' hostnames are excluded from proxying. Other hostnames that resolve to private IPv4 addresses are not excluded by default, because matching takes place before name resolution.

localhost and 127.0.0.1 are always excluded from proxying, regardless of the value of BALENARC_NO_PROXY.

The format of the BALENARC_NO_PROXY environment variable is a comma-separated list of patterns that are matched against hostnames or IP addresses. For example:

Matched patterns are excluded from proxying. Wildcard expressions are documented at matcher. Matching takes place before name resolution, so a pattern like '192.168.*' will not match a hostname that resolves to an IP address like 192.168.1.2.

Support, FAQ and troubleshooting

To learn more, troubleshoot issues, or to contact us for support:

• Check the masterclass tutorials
• Check our FAQ / troubleshooting document
• Ask us a question in the balena forums

For CLI bug reports or feature requests, check the CLI GitHub issues.

Deprecation policy

The balena CLI uses semver versioning, with the concepts of major, minor and patch version releases.

The latest release of a major version of the balena CLI will remain compatible with the balenaCloud backend services for at least one year from the date when the following major version is released. For example, balena CLI v11.36.0, as the latest v11 release, would remain compatible with the balenaCloud backend for one year from the date when v12.0.0 was released.

Half way through to that period (6 months after the release of the next major version), older major versions of the balena CLI will start printing a deprecation warning message when it is used interactively (when stderr is attached to a TTY device file). At the end of that period, older major versions will exit with an error message unless the --unsupported flag is used. This behavior was introduced in CLI version 12.47.0 and is also documented by balena help. To take advantage of the latest backend features and ensure compatibility, users are encouraged to regularly update the balena CLI to the latest version.

CLI Command Reference

• API Keys

  • api-key generate
  • api-key list
  • api-key revoke
• Apps

  • app create
• Authentication

  • login
  • logout
  • whoami
• Blocks

  • block create
• Config

  • config generate
  • config inject
  • config read
  • config reconfigure
  • config write
• Deploy

  • build
  • deploy
• Device-type

  • device-type list
• Devices

  • device deactivate
  • device detect
  • device identify
  • device
  • device init
  • device list
  • device local-mode
  • device logs
  • device move
  • device note
  • device os-update
  • device pin
  • device public-url
  • device purge
  • device reboot
  • device register
  • device rename
  • device restart
  • device rm
  • device shutdown
  • device ssh
  • device start-service
  • device stop-service
  • device track-fleet
  • device tunnel
• Environment Variables

  • env list
  • env rename
  • env rm
  • env set
• Fleets

  • fleet create
  • fleet
  • fleet list
  • fleet pin
  • fleet purge
  • fleet rename
  • fleet restart
  • fleet rm
  • fleet track-latest
• Local

  • local configure
  • local flash
• Organizations

  • organization list
• OS

  • os configure
  • os download
  • os initialize
  • os versions
• Platform

  • join
  • leave
• Preload

  • preload
• Push

  • push
• Release-asset

  • release-asset delete
  • release-asset download
  • release-asset list
  • release-asset upload
• Releases

  • release finalize
  • release
  • release invalidate
  • release list
  • release validate
• Settings

  • settings
• SSH Keys

  • ssh-key add
  • ssh-key
  • ssh-key list
  • ssh-key rm
• Support

  • support
• Tags

  • tag list
  • tag rm
  • tag set
• Utilities

  • util available-drives

API Keys

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.

This key can be used to log into the CLI using 'balena login --token ', or to authenticate requests to the API with an 'Authorization: Bearer ' header.

Examples:

Arguments

NAME

the API key name

EXPIRYDATE

the expiry date of the API key as an ISO date string, or "never" for no expiry

api-key list

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.

Examples:

Options

-u, --user

show API keys for your user

-f, --fleet FLEET

fleet name or slug (preferred)

api-key revoke

Description

Revoke balenaCloud API keys with the given comma-separated list of ids.

The given balenaCloud API keys will no longer be usable.

Examples:

Arguments

IDS

the API key ids

Apps

app create

Description

Create a new balena app.

You can specify the organization the app should belong to using the --organization option. The organization's handle, not its name, should be provided. Organization handles can be listed with the balena organization list command.

The app's default device type is specified with the --type option. The balena device-type list command can be used to list the available device types.

Interactive dropdowns will be shown for selection if no device type or organization is specified and there are multiple options to choose from. If there is a single option to choose from, it will be chosen automatically. This interactive behavior can be disabled by explicitly specifying a device type and organization.

Examples:

Arguments

NAME

app name

Options

-o, --organization ORGANIZATION

handle of the organization the app should belong to

-t, --type TYPE

app device type (Check available types with balena device-type list)

Authentication

login

Description

Login to your balena account.

This command will prompt you to login using the following login types:

• Web authorization: open your web browser and prompt to authorize the CLI from the dashboard.
• Credentials: using email/password and 2FA.
• Token: using a session token or API key from the preferences page.

Examples:

Arguments

TOKEN

Options

-w, --web

web-based login

-t, --token

session token or API key

-c, --credentials

credential-based login

-e, --email EMAIL

email

-u, --user USER

-p, --password PASSWORD

password

-P, --port PORT

TCP port number of local HTTP login server (--web auth only)

-H, --hideExperimentalWarning

Hides warning for experimental features

logout

Description

Logout from your balena account.

Examples:

whoami

Description

Get the username and email address of the currently logged in user.

Examples:

Blocks

block create

Description

Create a new balena block.

You can specify the organization the block should belong to using the --organization option. The organization's handle, not its name, should be provided. Organization handles can be listed with the balena organization list command.

The block's default device type is specified with the --type option. The balena device-type list command can be used to list the available device types.

Interactive dropdowns will be shown for selection if no device type or organization is specified and there are multiple options to choose from. If there is a single option to choose from, it will be chosen automatically. This interactive behavior can be disabled by explicitly specifying a device type and organization.

Examples:

Arguments

NAME

block name

Options

-o, --organization ORGANIZATION

handle of the organization the block should belong to

-t, --type TYPE

block device type (Check available types with balena device-type list)

Config

config generate

Description

Generate a config.json file for a device or fleet.

The target balenaOS version must be specified with the --version option.

The '--dev' option is used to configure balenaOS to operate in development mode, allowing unauthenticated root ssh access and exposing network ports such as balenaEngine's 2375 (unencrypted). This option causes "developmentMode": true to be inserted in the 'config.json' file in the image's boot partition. Development mode (as a configurable option) is applicable to balenaOS releases from early 2022. Older releases have separate development and production balenaOS images that cannot be reconfigured through 'config.json' or the '--dev' option. Do not confuse the balenaOS "development mode" with a device's "local mode", the latter being a supervisor feature that allows the "balena push" command to push a user's application directly to a device in the local network.

The '--secureBoot' option is used to configure a balenaOS installer image to opt-in secure boot and disk encryption.

To configure an image for a fleet of mixed device types, use the --fleet option 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 or slug. Fleet slugs are the recommended option, as they are unique and unambiguous. Slugs can be listed with the balena fleet list command. Note that slugs may change if the fleet is renamed. Fleet names are not unique and may result in "Fleet is ambiguous" errors at any time (even if it "used to work in the past"), for example if the name clashes with a newly created public fleet, or with fleets from other balena accounts that you may be invited to join under any role. For this reason, fleet names are especially discouraged in scripts (e.g. CI environments).

Examples:

Options

--version VERSION

a balenaOS version

-f, --fleet FLEET

fleet name or slug (preferred)

--dev

Configure balenaOS to operate in development mode

--secureBoot

Configure balenaOS installer to opt-in secure boot and disk encryption

-d, --device DEVICE

device UUID

-k, --deviceApiKey DEVICEAPIKEY

custom device key - note that this is only supported on balenaOS 2.0.3+

--deviceType DEVICETYPE

device type slug (run 'balena device-type list' for possible values)

-o, --output OUTPUT

path of output file

--network NETWORK

the network type to use: ethernet or wifi

--wifiSsid WIFISSID

the wifi ssid to use (used only if --network is set to wifi)

--wifiKey WIFIKEY

the wifi key to use (used only if --network is set to wifi)

--appUpdatePollInterval APPUPDATEPOLLINTERVAL

supervisor cloud polling interval in minutes (e.g. for device variables)

--initial-device-name INITIAL-DEVICE-NAME

This option will set the device name when the device provisions

--provisioning-key-name PROVISIONING-KEY-NAME

custom key name assigned to generated provisioning api key

--provisioning-key-expiry-date PROVISIONING-KEY-EXPIRY-DATE

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.

Documentation for the balenaOS 'config.json' file can be found at: https://www.balena.io/docs/reference/OS/configuration/

Examples:

Arguments

FILE

the path to the config.json file to inject

Options

-d, --drive DRIVE

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.

Documentation for the balenaOS 'config.json' file can be found at: https://www.balena.io/docs/reference/OS/configuration/

Examples:

Options

-d, --drive DRIVE

path to OS image file (e.g. balena.img) or block device (e.g. /dev/disk2)

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 chosen balenaOS image file or attached media, and then passes the UUID as the '--device' argument to the 'balena os configure' command.

For finer-grained or scripted control of the operation, use the 'balena config read' and 'balena os configure' commands separately.

Examples:

Options

-d, --drive DRIVE

path to OS image file (e.g. balena.img) or block device (e.g. /dev/disk2)

-v, --advanced

show advanced commands

--version VERSION

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.

Documentation for the balenaOS 'config.json' file can be found at: https://www.balena.io/docs/reference/OS/configuration/

Examples:

Arguments

KEY

the key of the config parameter to write

VALUE

the value of the config parameter to write

Options

-d, --drive DRIVE

path to OS image file (e.g. balena.img) or block device (e.g. /dev/disk2)

Deploy

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 balenaCloud build servers.)

You must specify either a fleet, or the device type and architecture.

This command will look into the given source directory (or the current working directory if one isn't specified) for a docker-compose.yml file, and if found, each service defined in the compose file will be built. If a compose file isn't found, it will look for a Dockerfile[.template] file (or alternative Dockerfile specified with the --dockerfile option), and if no dockerfile is found, it will try to generate one.

REGISTRY SECRETS The --registry-secrets option specifies a JSON or YAML file containing private Docker registry usernames and passwords to be used when pulling base images. Sample registry-secrets YAML file:

For a sample project using registry secrets with the Google Container Registry, check: https://github.com/balena-io-examples/sample-gcr-registry-secrets

If the --registry-secrets option is not specified, and a secrets.yml or secrets.json file exists in the balena directory (usually $HOME/.balena), this file will be used instead.

DOCKERIGNORE AND GITIGNORE FILES By default, the balena CLI will use a single ".dockerignore" file (if any) at the project root (--source directory) in order to decide which source files to exclude from the "build context" (tar stream) sent to balenaCloud, Docker daemon or balenaEngine. In a microservices (multicontainer) fleet, the source directory is the directory that contains the "docker-compose.yml" file.

The --multi-dockerignore (-m) option may be used with microservices (multicontainer) fleets that define a docker-compose.yml file. When this option is used, each service subdirectory (defined by the build or build.context service properties in the docker-compose.yml file) is filtered separately according to a .dockerignore file defined in the service subdirectory. If no .dockerignore file exists in a service subdirectory, then only the default .dockerignore patterns (see below) apply for that service subdirectory.

When the --multi-dockerignore (-m) option is used, the .dockerignore file (if any) defined at the overall project root will be used to filter files and subdirectories other than service subdirectories. It will not have any effect on service subdirectories, whether or not a service subdirectory defines its own .dockerignore file. Multiple .dockerignore files are not merged or added together, and cannot override or extend other files. This behavior maximizes compatibility with the standard docker-compose tool, while still allowing a root .dockerignore file (at the overall project root) to filter files and folders that are outside service subdirectories.

balena CLI v11 also took .gitignore files into account. This behavior was deprecated in CLI v12 and removed in CLI v13. Please use .dockerignore files instead.

Default .dockerignore patterns A few default/hardcoded dockerignore patterns are "merged" (in memory) with the patterns found in the applicable .dockerignore files, in the following order:

These patterns always apply, whether or not .dockerignore files exist in the project. If necessary, the effect of the **/.git pattern may be modified by adding exception patterns to the applicable .dockerignore file(s), for example !mysubmodule/.git. For documentation on pattern format, see:

• https://docs.docker.com/engine/reference/builder/#dockerignore-file
• https://www.npmjs.com/package/@balena/dockerignore

Examples:

Arguments

SOURCE

path of project source directory

Options

-A, --arch ARCH

the architecture to build for

-d, --deviceType DEVICETYPE

the type of device this build is for

-f, --fleet FLEET

fleet name or slug (preferred)

-e, --emulated

Use QEMU for ARM architecture emulation during the image build

--dockerfile DOCKERFILE

Alternative Dockerfile name/path, relative to the source folder

--nologs

Hide the image build log output (produce less verbose output)

-m, --multi-dockerignore

Have each service use its own .dockerignore file. See "balena help build".

--noparent-check

Disable project validation check of 'docker-compose.yml' file in parent folder

-R, --registry-secrets REGISTRY-SECRETS

Path to a YAML or JSON file with passwords for a private Docker registry

--noconvert-eol

Don't convert line endings from CRLF (Windows format) to LF (Unix format).

-n, --projectName PROJECTNAME

Name prefix for locally built images. This is the 'projectName' portion in 'projectName_serviceName:tag'. The default is the directory name.

-t, --tag TAG

Tag locally built Docker images. This is the 'tag' portion in 'projectName_serviceName:tag'. The default is 'latest'.

-B, --buildArg BUILDARG

[Deprecated] Set a build-time variable (eg. "-B 'ARG=value'"). Can be specified multiple times.

--cache-from CACHE-FROM

Comma-separated list (no spaces) of image names for build cache resolution. Implements the same feature as the "docker build --cache-from" option.

--nocache

Don't use docker layer caching when building

--pull

Pull the base images again even if they exist locally

--squash

Squash newly built layers into a single new layer

-P, --docker DOCKER

Path to a local docker socket (e.g. /var/run/docker.sock)

-h, --dockerHost DOCKERHOST

Docker daemon hostname or IP address (dev machine or balena device)

-p, --dockerPort DOCKERPORT

Docker daemon TCP port number (hint: 2375 for balena devices)

--ca CA

Docker host TLS certificate authority file

--cert CERT

Docker host TLS certificate file

--key KEY

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 fleet, optionally building it first. The source images are searched for (and optionally built) using the docker daemon in your development machine or balena device. (See also the balena push command for the option of building the image in the balenaCloud build servers.)

Unless an image is specified, this command will look into the current directory (or the one specified by --source) for a docker-compose.yml file. If one is found, this command will deploy each service defined in the compose file, building it first if an image for it doesn't exist. Image names will be looked up according to the scheme: <projectName>_<serviceName>.

If a compose file isn't found, the command will look for a Dockerfile[.template] file (or alternative Dockerfile specified with the -f option), and if yet that isn't found, it will try to generate one.

To deploy to a fleet where you are a collaborator, use fleet slug including the organization: balena deploy <organization>/<fleet>.

REGISTRY SECRETS The --registry-secrets option specifies a JSON or YAML file containing private Docker registry usernames and passwords to be used when pulling base images. Sample registry-secrets YAML file:

For a sample project using registry secrets with the Google Container Registry, check: https://github.com/balena-io-examples/sample-gcr-registry-secrets

If the --registry-secrets option is not specified, and a secrets.yml or secrets.json file exists in the balena directory (usually $HOME/.balena), this file will be used instead.

DOCKERIGNORE AND GITIGNORE FILES By default, the balena CLI will use a single ".dockerignore" file (if any) at the project root (--source directory) in order to decide which source files to exclude from the "build context" (tar stream) sent to balenaCloud, Docker daemon or balenaEngine. In a microservices (multicontainer) fleet, the source directory is the directory that contains the "docker-compose.yml" file.

The --multi-dockerignore (-m) option may be used with microservices (multicontainer) fleets that define a docker-compose.yml file. When this option is used, each service subdirectory (defined by the build or build.context service properties in the docker-compose.yml file) is filtered separately according to a .dockerignore file defined in the service subdirectory. If no .dockerignore file exists in a service subdirectory, then only the default .dockerignore patterns (see below) apply for that service subdirectory.

When the --multi-dockerignore (-m) option is used, the .dockerignore file (if any) defined at the overall project root will be used to filter files and subdirectories other than service subdirectories. It will not have any effect on service subdirectories, whether or not a service subdirectory defines its own .dockerignore file. Multiple .dockerignore files are not merged or added together, and cannot override or extend other files. This behavior maximizes compatibility with the standard docker-compose tool, while still allowing a root .dockerignore file (at the overall project root) to filter files and folders that are outside service subdirectories.

balena CLI v11 also took .gitignore files into account. This behavior was deprecated in CLI v12 and removed in CLI v13. Please use .dockerignore files instead.

Default .dockerignore patterns A few default/hardcoded dockerignore patterns are "merged" (in memory) with the patterns found in the applicable .dockerignore files, in the following order:

These patterns always apply, whether or not .dockerignore files exist in the project. If necessary, the effect of the **/.git pattern may be modified by adding exception patterns to the applicable .dockerignore file(s), for example !mysubmodule/.git. For documentation on pattern format, see:

• https://docs.docker.com/engine/reference/builder/#dockerignore-file
• https://www.npmjs.com/package/@balena/dockerignore

Examples:

Arguments

FLEET

fleet name or slug (preferred)

IMAGE

the image to deploy

Options

-s, --source SOURCE

specify an alternate source directory; default is the working directory

-b, --build

force a rebuild before deploy

--nologupload

don't upload build logs to the dashboard with image (if building)

--release-tag RELEASE-TAG

Set release tags if the image deployment is successful. Multiple arguments may be provided, alternating tag keys and values (see examples). Hint: Empty values may be specified with "" (bash, cmd.exe) or '""' (PowerShell).

--draft

Deploy the release as a draft. Draft releases are ignored by the 'track latest' release policy but can be used through release pinning. Draft releases can be marked as final through the API. Releases are created as final by default unless this option is given.

--note NOTE

The notes for this release

-e, --emulated

Use QEMU for ARM architecture emulation during the image build

--dockerfile DOCKERFILE

Alternative Dockerfile name/path, relative to the source folder

--nologs

Hide the image build log output (produce less verbose output)

-m, --multi-dockerignore

Have each service use its own .dockerignore file. See "balena help build".

--noparent-check

Disable project validation check of 'docker-compose.yml' file in parent folder

-R, --registry-secrets REGISTRY-SECRETS

Path to a YAML or JSON file with passwords for a private Docker registry

--noconvert-eol

Don't convert line endings from CRLF (Windows format) to LF (Unix format).

-n, --projectName PROJECTNAME

Name prefix for locally built images. This is the 'projectName' portion in 'projectName_serviceName:tag'. The default is the directory name.

-t, --tag TAG

Tag locally built Docker images. This is the 'tag' portion in 'projectName_serviceName:tag'. The default is 'latest'.

-B, --buildArg BUILDARG

[Deprecated] Set a build-time variable (eg. "-B 'ARG=value'"). Can be specified multiple times.

--cache-from CACHE-FROM

Comma-separated list (no spaces) of image names for build cache resolution. Implements the same feature as the "docker build --cache-from" option.

--nocache

Don't use docker layer caching when building

--pull

Pull the base images again even if they exist locally

--squash

Squash newly built layers into a single new layer

-P, --docker DOCKER

Path to a local docker socket (e.g. /var/run/docker.sock)

-h, --dockerHost DOCKERHOST

Docker daemon hostname or IP address (dev machine or balena device)

-p, --dockerPort DOCKERPORT

Docker daemon TCP port number (hint: 2375 for balena devices)

--ca CA

Docker host TLS certificate authority file

--cert CERT

Docker host TLS certificate file

--key KEY

Docker host TLS key file

Device-type

device-type list

Description

List the device types supported by balena (like 'raspberrypi3' or 'intel-nuc').

By default, only actively supported device types are listed. The --all option can be used to list all device types, including those that are no longer supported by balena.

Examples:

Options

--all

include device types no longer supported by balena

Devices

device deactivate

Description

Deactivate a device.

Note this command asks for confirmation interactively. You can avoid this by passing the --yes option.

Examples:

Arguments

UUID

the UUID of the device to be deactivated

Options

-y, --yes

answer "yes" to all questions (non interactive use)

device detect

Description

Scan for balenaOS devices on your local network.

The output includes device information collected through balenaEngine for devices running a development image of balenaOS. Devices running a production image do not expose balenaEngine (on TCP port 2375), which is why less information is printed about them.

Examples:

Options

-v, --verbose

display full info

-t, --timeout TIMEOUT

scan timeout in seconds

device identify

Description

Identify a device by making the ACT LED blink (Raspberry Pi).

Examples:

Arguments

UUID

the uuid of the device to identify

device

Description

Show information about a single device.

Examples:

Arguments

UUID

the device uuid

Options

--view

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, namely:

'balena device register' 'balena os download' 'balena config generate' 'balena os configure' 'balena os local flash'

Possible arguments for the '--fleet', '--os-version' and '--drive' options can be listed respectively with the commands:

'balena fleet list' 'balena os versions' 'balena util available-drives'

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 or slug. Fleet slugs are the recommended option, as they are unique and unambiguous. Slugs can be listed with the balena fleet list command. Note that slugs may change if the fleet is renamed. Fleet names are not unique and may result in "Fleet is ambiguous" errors at any time (even if it "used to work in the past"), for example if the name clashes with a newly created public fleet, or with fleets from other balena accounts that you may be invited to join under any role. For this reason, fleet names are especially discouraged in scripts (e.g. CI environments).

Image configuration questions will be asked interactively unless a pre-configured 'config.json' file is provided with the '--config' option. The file can be generated with the 'balena config generate' command.

Examples:

Options

-f, --fleet FLEET

fleet name or slug (preferred)

--config CONFIG

path to the config JSON file, see balena config generate

--os-version OS-VERSION

exact version number, or a valid semver range, or 'latest' (includes pre-releases), or 'default' (excludes pre-releases if at least one stable version is available), or 'recommended' (excludes pre-releases, will fail if only pre-release versions are available), or 'menu' (will show the interactive menu)

-v, --advanced

show advanced configuration options

--provisioning-key-name PROVISIONING-KEY-NAME

custom key name assigned to generated provisioning api key

--provisioning-key-expiry-date PROVISIONING-KEY-EXPIRY-DATE

expiry date assigned to generated provisioning api key (format: YYYY-MM-DD)

-d, --drive DRIVE

the drive to write the image to, eg. /dev/sdb or /dev/mmcblk0. Careful with this as you can erase your hard drive. Check balena util available-drives for available options.

-y, --yes

answer "yes" to all questions (non interactive use)

device list

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 fleet list command. Note that slugs may change if the fleet is renamed. Fleet names are not unique and may result in "Fleet is ambiguous" errors at any time (even if it "used to work in the past"), for example if the name clashes with a newly created public fleet, or with fleets from other balena accounts that you may be invited to join under any role. For this reason, fleet names are especially discouraged in scripts (e.g. CI environments).

Examples:

Options

-f, --fleet FLEET

fleet name or slug (preferred)

device local-mode

Description

Output current local mode status, or enable/disable local mode for specified device.

Examples:

Arguments

UUID

the uuid of the device to manage

Options

--enable

enable local mode

--disable

disable local mode

--status

output boolean indicating local mode status

device logs

Description

Show logs for a specific device.

By default, the command prints all log messages and exits.

To continuously stream output, and see new logs in real time, use the --tail option.

If an IP or .local address is passed to this command, logs are displayed from a local mode device with that address. Note that --tail is implied when this command is provided a local mode device.

Logs from a single service can be displayed with the --service flag. Just system logs can be shown with the --system flag. Note that these flags can be used together.

Note: --service and --system flags must come after the device parameter, as per examples.

Examples:

Arguments

DEVICE

device UUID, IP, or .local address

Options

--max-retry MAX-RETRY

Maximum number of reconnection attempts on "connection lost" errors (use 0 to disable auto reconnection).

-t, --tail

continuously stream output

-s, --service SERVICE

Reject logs not originating from this service. This can be used in combination with --system or other --service flags.

-S, --system

Only show system logs. This can be used in combination with --service.

device move

Description

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 or slug. Fleet slugs are the recommended option, as they are unique and unambiguous. Slugs can be listed with the balena fleet list command. Note that slugs may change if the fleet is renamed. Fleet names are not unique and may result in "Fleet is ambiguous" errors at any time (even if it "used to work in the past"), for example if the name clashes with a newly created public fleet, or with fleets from other balena accounts that you may be invited to join under any role. For this reason, fleet names are especially discouraged in scripts (e.g. CI environments).

Examples:

Arguments

UUID

comma-separated list (no blank spaces) of device UUIDs to be moved

Options

-f, --fleet FLEET

fleet name or slug (preferred)

device note

Description

Set or update a device note. If the note argument is not provided, it will be read from stdin.

To view device notes, use the balena device <uuid> command.

Examples:

Arguments

NOTE

note content

Options

-d, --device DEVICE

device UUID

device os-update

Description

Start a Host OS update for a device.

Note this command will ask for confirmation interactively. This can be avoided by passing the --yes option.

Requires balenaCloud; will not work with openBalena or standalone balenaOS.

Examples:

Arguments

UUID

the uuid of the device to update

Options

--version VERSION

a balenaOS version

--include-draft

include pre-release balenaOS versions

-y, --yes

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

Examples:

Arguments

UUID

the uuid of the device to pin to a release

RELEASETOPINTO

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.

Examples:

Arguments

UUID

the uuid of the device to manage

Options

--enable

enable the public URL

--disable

disable the public URL

--status

determine if public URL is enabled

device purge

Description

Purge data from a device. This will clear the device's "/data" directory.

Multiple devices may be specified with a comma-separated list of values (no spaces).

Examples:

Arguments

UUID

comma-separated list (no blank spaces) of device UUIDs

device reboot

Description

Remotely reboot a device.

Examples:

Arguments

UUID

the uuid of the device to reboot

Options

-f, --force

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.

Fleets may be specified by fleet name or slug. Fleet slugs are the recommended option, as they are unique and unambiguous. Slugs can be listed with the balena fleet list command. Note that slugs may change if the fleet is renamed. Fleet names are not unique and may result in "Fleet is ambiguous" errors at any time (even if it "used to work in the past"), for example if the name clashes with a newly created public fleet, or with fleets from other balena accounts that you may be invited to join under any role. For this reason, fleet names are especially discouraged in scripts (e.g. CI environments).

Examples:

Arguments

FLEET

fleet name or slug (preferred)

Options

-u, --uuid UUID

custom uuid

--deviceType DEVICETYPE

device type slug (run 'balena device-type list' for possible values)

device rename

Description

Rename a device.

Note, if the name is omitted, it will be prompted for interactively.

Examples:

Arguments

UUID

the uuid of the device to rename

NEWNAME

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.

Multiple devices and services may be specified with a comma-separated list of values (no spaces).

Note this does not reboot the device, to do so use instead balena device reboot.

Examples:

Arguments

UUID

comma-separated list (no blank spaces) of device UUIDs to restart

Options

-s, --service SERVICE

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. You can avoid this by passing the --yes option.

Examples:

Arguments

UUID

comma-separated list (no blank spaces) of device UUIDs to be removed

Options

-y, --yes

answer "yes" to all questions (non interactive use)

device shutdown

Description

Remotely shutdown a device.

Examples:

Arguments

UUID

the uuid of the device to shutdown

Options

-f, --force

force action if the update lock is set

device 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.

If a fleet is provided, an interactive menu will be presented for the selection of an online device. A shell will then be opened for the host OS or service container of the chosen device.

For local devices, the IP address and .local domain name are supported. If the device is referenced by IP or .local address, the connection is initiated directly to balenaOS on port 22222 via an openssh-compatible client. Otherwise, any connection initiated remotely traverses the balenaCloud VPN.

Commands may be piped to the standard input for remote execution (see examples). Note however that remote command execution on service containers (as opposed to the host OS) is not currently possible when a device UUID is used (instead of an IP address) because of a balenaCloud backend limitation.

Note: balena ssh requires an openssh-compatible client to be correctly installed in your shell environment. For more information (including Windows support) please check: https://github.com/balena-io/balena-cli/blob/master/INSTALL.md#additional-dependencies,

Examples:

Arguments

FLEETORDEVICE

fleet name/slug, device uuid, or address of local device

SERVICE

service name, if connecting to a container

Options

-p, --port PORT

SSH server port number (default 22222) if the target is an IP address or .local hostname. Otherwise, port number for the balenaCloud gateway (default 22).

-t, --tty

force pseudo-terminal allocation (bypass TTY autodetection for stdin)

-v, --verbose

increase verbosity

--noproxy

bypass global proxy configuration for the ssh connection

device start-service

Description

Start containers on a device.

Multiple devices and services may be specified with a comma-separated list of values (no spaces).

Examples:

Arguments

UUID

comma-separated list (no blank spaces) of device UUIDs

SERVICE

comma-separated list (no blank spaces) of service names