Using the CLI
bb-imager-cli provides everything the GUI does for flashing local image files, plus extra
targets, and is suited to scripting and headless machines. To install it, see
Install BeagleBoard Imaging Utility (CLI).
Every command has built-in help:
bb-imager-cli --help
bb-imager-cli flash --help
bb-imager-cli flash sd --help
Global option: --verbose turns on more logging.
| The CLI flashes local image files. Download the image for your board first, for example from beagleboard.org/distros. |
Flash an SD card
1. Find the destination
bb-imager-cli list-destinations sd
--no-frills
|
Print only device paths, one per line. Useful in scripts. |
--no-filter
|
Show every device without sanity filtering. Use this when your card is not listed because the OS reports it incorrectly. Double-check the device, since this also lists internal disks. |
2. Flash
bb-imager-cli flash sd ./image.img.xz /dev/sdX
The image can be xz-compressed or uncompressed.
All data on the destination is erased. Make sure /dev/sdX is your SD card, not a system
disk.
|
Add --quiet (before the target, flash --quiet sd …) to suppress progress output.
Customize on first boot
These options pre-configure supported images, like the GUI’s Modify step:
| Option | Description |
|---|---|
|
Hostname, e.g. |
|
Timezone, e.g. |
|
Keyboard layout, e.g. |
|
Default user, used together. Cannot be |
|
Wi-Fi network, used together. |
|
SSH public key to authorize. |
|
Enable DHCP on the USB network interface. |
|
Write the configuration as sysconf. Currently sysconf is generated even without this flag; this will change, so set it explicitly. |
|
Write the configuration as cloud-init instead. |
Example:
bb-imager-cli flash sd ./image.img.xz /dev/sdX \
--sysconfig \
--hostname mybeagle \
--user-name debian --user-password 'change-me' \
--wifi-ssid MyNetwork --wifi-password 'secret' \
--ssh-key "$(cat ~/.ssh/id_ed25519.pub)"
Advanced options
| Option | Description |
|---|---|
|
Use a bmap file to write only the used blocks. Faster for sparse images. |
|
Grow the last partition to fill the card. |
|
Copy a boot-partition tarball after flashing. Useful for making Fedora and other distribution images bootable. |
|
Treat the destination as a regular file instead of a device. Useful for preparing images. |
Other targets
Some subcommands exist only when the CLI was built with the matching cargo feature. See
Features. Run bb-imager-cli list-destinations <target> to find
the port or device for each.
| Target | Command | Feature |
|---|---|---|
BeagleConnect Freedom (CC1352P7) |
|
|
BeagleConnect Freedom (MSP430 USB-UART bridge) |
|
|
BeagleConnect Zepto (MSPM0) |
|
|
PocketBeagle 2 MSPM0 |
|
|
USB DFU devices |
|
|
Examples:
# BeagleConnect Freedom over its serial port
bb-imager-cli flash bcf ./firmware.bin /dev/ttyACM0
# BeagleConnect Zepto over I2C with explicit reset/BSL GPIOs (Linux)
bb-imager-cli flash zepto ./firmware.hex /dev/i2c-1 --reset-gpio <gpio> --bsl-gpio <gpio>
For dfu, the identifier has the form {bus_num}:{address}:{vendor_id}:{product_id} (all hex), as
printed by list-destinations dfu. Each firmware is given as a name followed by a path, and they
are flashed in order.
On Linux, serial and USB targets need device permissions. See Enable Serial Flashing Support.
Shell completion
# bash
bb-imager-cli generate-completion bash > ~/.local/share/bash-completion/completions/bb-imager-cli
# zsh (pick a directory on your $fpath)
bb-imager-cli generate-completion zsh > ~/.zfunc/_bb-imager-cli
# fish
bb-imager-cli generate-completion fish > ~/.config/fish/completions/bb-imager-cli.fish
Supported shells: bash, zsh, fish, elvish, powershell.