arduino-cli

While arduino-cli is an awesome tool, unfortunately most guides skip right past it and assume you use the Arduino IDE, this page is a collection of common patterns for arduino-cli. It assumes that you know a few things about how Arduino works.

Basics

To create a sketch arduino-cli assumes that your main .ino file has the same name as the directory containing it.

To build and upload use arduino-cli compile --fqbn <fqbn> and arduino-cli upload -p <serial-device> --fqbn <fqbn> in your code directory.

FQBN? Fully Qualified Board Name!

The Fully qualified Board name consists of what Arduino calls the Platform ID and a name for the board. You can find it out either by using arduino-cli board search <searchterm> or by appending the official board name in lowercase to the Platform ID.

Examples include:

arduino:avr:uno (Arduino Uno or another board with an ATMega328P running at 16MHz)
esp8266:esp8266:generic (A generic esp8266 Module)
esp32:esp32:esp32 (A generic esp32 module)

Please note that the esp boards are not available by default.

Adding more boards

The arduino-cli is not just a wrapper for a compiler and whatever you prefer for uploading … it also is a package manager. If you want more boards (or libraries) you can search for and install them. But if you want to write code for example, an esp or another non-arduino branded board those packages are in their own repositories.

Adding an extra repository can be done by letting arduino-cli do the dirty work …

arduino-cli config add board_manager.additional_urls 'url://to/index.json'

Command to add an extra repository URL to the board manager. It edits the configuration file for you.

… or by manually editing ~/.arduino15/arduino-cli.yaml (yay another popular program not respecting XDG …) and adding your URL there.

board_manager:
  additional_urls:
  - https://arduino.esp8266.com/stable/package_esp8266com_index.json
  - https://dl.espressif.com/dl/package_esp32_index.json
  - https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_dev_index.json

An excerpt from the configuration file from my laptop with additional URL to the stable esp8266 and esp32 repositories in addition to the development version of the esp32 repository.

Don't forget to arduino-cli update and arduino-cli upgrade!

Compile and upload script

I usually create a compile-and-upload.sh script to make development and testing easier.

#!/bin/sh
arduino-cli compile --fqbn arduino:avr:uno && \
arduino-cli upload --fqbn arduino:avr:uno -p "${1:-/dev/ttyUSB0}"

A simple compile and upload script with a fixed board and an optional argument for the serial port that defaults to /dev/ttyUSB0

You may also be interested in

The offical arduino-cli documantation

Serial Port Troublehooting on Linux