balena-io/balena-cli

Purpose and Runtime

This is the TypeScript/Node.js implementation of the cross-platform balena CLI. It provides interactive and scriptable access to balenaCloud or self-hosted openBalena: fleet/device administration, application deployment, OS image management, authentication, and local device operations.

Primary launchers are bin/balena, bin/run.js, and development launcher bin/balena-dev. The command framework application is rooted at src/app.ts.

CLI Dispatch and Lifecycle

The CLI uses an oclif-style command layout: command path segments map to modules under src/commands/. Startup preprocessing, global behavior, and invalid-command suggestions form the command boundary.

• src/app.ts

• src/preparser.ts

• src/hooks/prerun.ts

• src/hooks/command-not-found/suggest.ts

Commands receive normalized arguments/flags, configuration, authentication state, and shared SDK/network facilities rather than directly owning those concerns.

Cloud API and Authentication Boundary

Cloud-facing commands communicate through the balena SDK/API abstraction, supporting balenaCloud and openBalena. Login starts a local authentication flow/server and persists usable credentials; logout and identity commands consume the same session state.

• src/auth/index.ts

• src/auth/server.ts

• src/utils/sdk.ts

• src/commands/login/index.ts

• src/commands/logout/index.ts

The local auth HTTP server and EJS success/error pages are a contained browser callback boundary, not an application web server.

Deployment and Build Pipeline

push, deploy, and build turn a local Dockerfile or Compose project into deployable images/releases. Compose parsing and validation determine service definitions; Docker and/or remote build facilities create images; release utilities publish and promote artifacts through the cloud API.

• src/commands/push/index.ts

• src/commands/deploy/index.ts

• src/commands/build/index.ts

• src/utils/compose.ts

• src/utils/docker.ts

• src/utils/remote-build.ts

This pipeline crosses local filesystem/Docker daemon boundaries and remote builder/API boundaries. Legacy deployment remains isolated in src/utils/deploy-legacy.ts.

Fleet, Device, and Release Control Plane

Most commands are thin CLI adapters over a common cloud control plane: applications/fleets, devices, releases, environment variables, tags, organizations, SSH keys, and release assets. Device-specific operations additionally support logs, SSH, tunnels, restart/state actions, and local-mode workflows.

• src/commands/fleet/index.ts

• src/commands/device/index.ts

• src/commands/release/index.ts

• src/utils/device/api.ts

• src/utils/device/live.ts

• src/utils/tunnel.ts

The important distinction is cloud resource mutation/query versus direct/live device connectivity.

Local OS and Device Provisioning

The CLI can discover drives/devices, download/configure/initialize balena OS images, flash local media, and inject configuration. These workflows depend on host OS capabilities, privileged operations, disk mounting/unmounting, compression/image handling, and optional emulation tooling.

• src/commands/os/configure.ts

• src/commands/local/flash.ts

• src/commands/config/inject.ts

• src/utils/image-manager.ts

• src/utils/qemu.ts

• src/utils/umount.ts

Shared Environment and External Dependencies

Cross-cutting services centralize persisted configuration, proxy selection/exclusion, logging, terminal interaction, update/version enforcement, and platform command discovery.

• src/config.ts

• src/utils/config.ts

• src/utils/proxy.ts

• src/utils/update.ts

• src/utils/tty.ts

Material external dependencies are Node.js, Docker, the balena SDK/API, balena remote builders, local SSH/proxytunnel, and host disk/OS utilities. Release packaging produces standalone binaries via automation/build-bin.ts; npm remains another distribution route.