arduino-cli (Arduino CLI)

What it is

Arduino's headless build tool: manage cores (board support packages) and libraries, compile sketches, and upload over serial — no IDE required. Good fit for CI builds of Arduino-based firmware.

Install

Official script (latest stable into ~/.local/bin):

curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh \
  | BINDIR=~/.local/bin sh

Static binaries (x86_64/arm64) also on the releases page if you want to pin a version. Add ~/.local/bin to PATH if it isn't already.

Authenticate

None for core functionality. Only the (optional) Arduino Cloud integration uses credentials — we don't use it; keep any such tokens in Vaultwarden if you ever enable it.

Configure for this environment

First-run setup for AVR + ESP32:

arduino-cli config init
arduino-cli config add board_manager.additional_urls \
  https://espressif.github.io/arduino-esp32/package_esp32_index.json
arduino-cli core update-index
arduino-cli core install arduino:avr
arduino-cli core install esp32:esp32
arduino-cli lib install "PubSubClient"

Serial access: sudo usermod -aG dialout $USER (re-login).

Typical cycle:

arduino-cli board list                       # find the port + FQBN
arduino-cli compile --fqbn esp32:esp32:esp32 sketch/
arduino-cli upload -p /dev/ttyUSB0 --fqbn esp32:esp32:esp32 sketch/
arduino-cli monitor -p /dev/ttyUSB0 -c baudrate=115200

Self-hosted equivalent

Fully local — cores/libraries download from public indexes, but builds and uploads happen on the laptop. No cloud dependency. (Build artifacts can be mirrored to MinIO http://192.168.0.40:9000 with the rest of the firmware.)

Aurélio integration

The embedded-linux skill uses arduino-cli for Arduino-core firmware builds and uploads (ESP32/AVR). Flashed devices usually talk to the mqtt-local broker connector.

Verify

arduino-cli version
# arduino-cli  Version: 1.x.y ...
arduino-cli board list
# Port         Protocol Type              Board Name  FQBN            Core
# /dev/ttyUSB0 serial   Serial Port (USB) Unknown     esp32:esp32:... esp32:esp32

Troubleshooting

Board not found on compile — the core isn't installed; arduino-cli core search <chip> then core install.
ESP32 package index ignored — the additional_urls must be added via config add (as above), then core update-index again.
Upload permission denied — dialout group missing, or arduino-cli monitor/minicom still holding the port.
Compile cache confusion after core upgrade — arduino-cli cache clean then rebuild.

2.6 KiB Raw Blame History