DOCSEARCHbyAlgolia
Submit Docs

balena CLI

repository·master·Indexed 19 days ago

https://github.com/balena-io/balena-cli

The official command-line interface for managing balenaCloud and openBalena environments. It enables developers to interact with device fleets, push releases, manage devices, and configure balenaOS settings via terminal or scripts. Key features include API key management, app and block creation, and balenaOS config.json generation, injection, and modification.

Tokens
60.7K
Snippets
227
Records
270
Agent score
67%

What's inside balena-cli

  1. Manage `.dockerignore` files in multicontainer fleets

    master

    The balena CLI uses .dockerignore files to exclude files from the build context sent to balenaCloud or the local daemon.

    • Default Behavior: Uses a single .dockerignore at the project root.
    • Multi-dockerignore (-m): In multicontainer fleets, using --multi-dockerignore allows each service subdirectory (defined by build or build.context in docker-compose.yml) to use its own .dockerignore file.
    • Root .dockerignore with -m: When -m is active, the root .dockerignore filters files/subdirectories outside of service subdirectories but does not affect the service subdirectories themselves.
    • Note: .gitignore files are no longer supported for build context filtering; use .dockerignore instead.

  2. Manage build context with `.dockerignore`

    master

    The balena CLI uses .dockerignore files to decide which files to exclude from the build context sent to the builder.

    • Standard behavior: Uses a single .dockerignore at the project root.
    • Microservices (Multicontainer) fleets: Use the --multi-dockerignore (-m) flag to allow each service subdirectory to have its own .dockerignore file.
    • Root .dockerignore: When using -m, the root .dockerignore still applies to files/folders outside of service subdirectories, but it will not affect or override service-specific .dockerignore files.

    Default patterns: The following patterns are always merged in memory with your files:

    • **/.git
    • !**/.balena
    • !**/.resin
    • !**/Dockerfile
    • !**/Dockerfile.*
    • !**/docker-compose.yml

  3. Manage build context with `.dockerignore` and `--multi-dockerignore`

    master

    The balena CLI uses .dockerignore files to exclude files from the build context sent to the Docker daemon or balenaCloud.

    Standard Behavior: By default, the CLI uses a single .dockerignore file at the project root.

    Multicontainer (Microservices) Behavior: If you have a docker-compose.yml file, you can use the --multi-dockerignore (-m) option. This allows each service subdirectory (defined by build or build.context) to use its own .dockerignore file.

    Important Rules:

    • The root .dockerignore file filters files/subdirectories outside of service subdirectories. It does not affect service subdirectories.
    • Multiple .dockerignore files are not merged or added together.
    • .gitignore files are no longer supported (removed in CLI v13); use .dockerignore instead.

    Default Hardcoded Patterns: The following patterns are always merged with your .dockerignore files:

    • **/.git
    • !**/.balena
    • !**/.resin
    • !**/Dockerfile
    • !**/Dockerfile.*
    • !**/docker-compose.yml

  4. Configure remote Docker or balenaEngine for CLI commands

    master

    Certain commands like balena device ssh, device detect, build, deploy, and preload require Docker or balenaEngine.

    You can use a remote Docker Engine or balenaEngine instead of a local one to save local resources or to build natively on ARM devices. To do this, specify the remote machine's IP and port using the --dockerHost and --dockerPort flags.

    Note: The preload command has additional requirements because it utilizes bind mounts.

    # Example usage pattern (placeholders for actual values)
balena build --dockerHost <REMOTE_IP> --dockerPort <REMOTE_PORT>

  5. Understand the balena CLI deprecation policy

    master

    The balena CLI follows semantic versioning. To ensure compatibility with balenaCloud backend services:

    1. Compatibility Window: The latest release of a major version remains compatible with the backend for at least one year after the next major version is released.
    2. Deprecation Warnings: Six months after a new major version is released, older major versions will print a deprecation warning when used interactively.
    3. End of Life: After the one-year period, older major versions will exit with an error unless the --unsupported flag is used.

    It is recommended to regularly update to the latest version to access new features and maintain compatibility.

  6. Install the balena CLI on macOS

    master

    Follow these steps to install the recommended version of the balena CLI on macOS:

    1. Download the latest installer from the balena-cli releases page. Ensure the filename ends with -installer.pkg (e.g., balena-cli-vX.Y.Z-macOS-x64-installer.pkg).
    2. Run the .pkg file and follow the on-screen installation instructions.
    3. Verify the installation by running balena version in your Terminal. It should return the installed version number.

    To update the CLI, repeat this process with a newer version. To uninstall the CLI, run the uninstall script using sudo.

    # Verify installation
balena version

# Uninstall the CLI
sudo /usr/local/src/balena-cli/bin/uninstall

  7. Install the balena CLI via NPM

    master

    Node.js developers can install the CLI via npm. This method builds native platform-specific binary modules and requires specific development tools to be installed first.

    Requirements:

    • Node.js version > 24.11.0 (Note: Versions 25 and later are not yet fully supported).

    1. Install Development Tools

    Linux or WSL

    sudo apt-get update && sudo apt-get -y install curl python3 git make g++
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
. ~/.bashrc
nvm install 22

    macOS

    1. Download and install Apple's Command Line Tools.
    2. Install Node.js via nvm:
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
. ~/.bashrc
nvm install 22

    Windows (not WSL)

    • Install Node.js v22 (or use nvm-windows).
    • Install MSYS2 shell and run: pacman -S git gcc make openssh p7zip.
    • Set the environment variable: MSYS2_PATH_TYPE=inherit.
    • Install the Windows Driver Kit (WDK) (Step 2 of the WDK installation guide).
    • Run npm install --global --production windows-build-tools from an administrator console.

    2. Install the CLI

    Once tools are ready, run:

    npm install balena-cli --global --production --unsafe-perm

    Note: --unsafe-perm is required when running as root (e.g., in Docker) to allow postinstall scripts to execute.

  8. Configure dependencies for balena device ssh

    master

    To use the balena device ssh command, you must satisfy two requirements:

    1. SSH Client: An ssh command-line tool must be available in your terminal. Windows 10 and later include this via Windows Update. You can verify this by running ssh in PowerShell. If missing, you can install OpenSSH manually.
    2. SSH Key: You must have an SSH key added to your balena account. You can manage these keys using the balena key* command set (use balena help -v for a full list of key management commands).

  10. Configure sudo for balena CLI commands

    master

    Some commands, such as balena device detect, require sudo privileges. If your Linux distribution uses a secure_path setting in the /etc/sudoers file, you must add the balena CLI's bin folder to that path to ensure sudo can find the executable.

    1. Run sudo visudo to edit the configuration.
    2. Locate the Defaults secure_path line.
    3. Append your balena CLI installation folder to the existing entries.

    Example: If your CLI is in /home/james/balena:

    Defaults secure_path="/home/james/balena/bin:<pre-existing entries>"

    Note: If /etc/sudoers does not exist or does not contain a secure_path setting, do not modify it.

    Defaults   secure_path="/home/james/balena/bin:<pre-existing entries go here>"

  12. Configure dependencies for balena device detect

    master

    The balena device detect command requires a multicast DNS (mDNS) service to discover devices on your network.

    • Requirement: An mDNS service such as Apple's Bonjour must be installed on your Windows machine.
    • Installation: If not already present (some applications like Skype may bundle it), you can download Bonjour for Windows from Apple's support site.