balena

Log in to the balenaCloud account

$ balena login

$ balena app create [app_name]

$ balena apps

$ balena devices

$ balena local flash [path/to/balenaos.img] --drive [drive_location]

balena [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [OPTIONS] [ARGS...]

The balena command operates with a command-subcommand structure. Global options apply to the entire CLI invocation, while specific options and arguments are relevant to the chosen command and its subcommand. Common top-level commands include login, logout, push, deploy, devices, apps, help, config, and os.

--help, -h
    Displays help information for the specific command or subcommand.

--version, -v
    Displays the version of the balena CLI.

--debug
    Enables verbose debug output for troubleshooting.

--json
    Formats command output as JSON, useful for scripting.

--visual
    Activates a visual progress display for operations like balena push.

--pipe
    Strips extra formatting from output, suitable for piping to other commands.

--token token
    Used with balena login to authenticate using an API token instead of interactive login.

--source path
    Used with balena push to specify the project directory of the application to be deployed.

--build
    Used with balena push to force a complete rebuild of application images on the balenaCloud builders, even if not strictly necessary.

--dont-start
    Used with balena push to prevent services from starting immediately after deployment, useful for staged rollouts.

--app name_or_id
    Used with commands like balena devices or balena logs to filter results by a specific application.

The balena command-line interface (CLI) is the primary tool for interacting with the balenaCloud platform, a comprehensive ecosystem designed for developing, deploying, and managing fleets of internet-connected embedded devices. It provides a robust set of functionalities for the entire IoT device lifecycle, from initial provisioning and setup to continuous deployment and remote management. Users can leverage balena to push applications to specific devices or entire fleets, monitor device status and logs, SSH into running containers or the host OS, and perform various administrative tasks like creating new applications or adding devices. It abstracts complex device management operations, enabling developers and operators to efficiently build, deploy, and scale IoT solutions across diverse hardware. The CLI supports local development workflows and seamless integration with balenaCloud's over-the-air update capabilities, making it indispensable for modern IoT development.

The balena CLI requires an active balenaCloud account and internet connectivity to operate effectively, as it primarily interacts with the remote balenaCloud platform. It is not a standard, pre-installed Linux utility and must be installed separately, typically via npm or a standalone installer. Users should be aware that large application pushes or OS downloads can consume significant network bandwidth and may take considerable time depending on internet speed and project size. Development on cross-architecture devices might require careful management of build environments or reliance on balenaCloud builders.

The balena CLI is highly modular, organized into numerous subcommands (e.g., balena login, balena push, balena devices, balena help). Each subcommand manages specific aspects of the balena ecosystem, offering a focused set of options and arguments. Users can explore available commands and their usage via balena help or balena help command.

While runnable locally, the balena CLI is primarily designed to interact with the balenaCloud platform. Most of its functionalities, such as deploying applications, managing devices, and accessing logs, rely on authenticated communication with balenaCloud services. This integration enables powerful remote management and over-the-air updates for vast fleets of devices.

A significant feature of balena is its support for 'local mode' development. By pushing code directly to a local device's IP address (e.g., balena push 192.168.1.100), developers can rapidly iterate on their applications without involving the cloud builders. This speeds up the development cycle considerably for individual devices.

The balena CLI has its roots in resin.io, the predecessor platform founded around 2013-2014, which aimed to simplify embedded Linux development and device management. The CLI evolved alongside the platform, initially providing basic deployment and device interaction capabilities. In 2018, resin.io rebranded to balena, signifying an expansion beyond just Linux containers to encompass the entire IoT device lifecycle, including operating system management (balenaOS) and fleet orchestration. The CLI has consistently been updated to reflect these platform advancements, adding comprehensive features for local development, robust fleet management, advanced device diagnostics, and seamless over-the-air updates, establishing itself as a cornerstone tool for modern IoT application development and deployment.

docker(1), git(1), ssh(1), npm(1)