Installing and using the Arduino Command-Line Interface (CLI)

The Arduino line of microcontrollers has become a de facto standard in the maker world. One of its main advantages is the Arduino IDE, which makes it very easy to program and debug boards.

However, in more complex projects, it’s often desirable to centralize development around a common toolset, including a general-purpose text editor or IDE. In this case a command-line interface is necessary so that Arduino sketches can be automatically compiled and uploaded from build scripts, instead of manually through the Arduino IDE.

In the past, the Arduino IDE supported command-line options for automatically running tasks such as compiling or uploading a sketch to a board. However, more recently these functionalities have been moved to a new application, the Arduino Command-Line Interface (CLI).

Installing the Arduino CLI can be easily done from the terminal. To install the tool under ~/.local/bin, make sure you have curl installed, then run the commands below:

ARDUINO_PATH="$HOME/.local/bin"
mkdir -p $ARDUINO_PATH
curl -fsSL "https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh" | BINDIR=$ARDUINO_PATH sh

For convenience, make sure that $HOME/.local/bin is in your $PATH environment variable. If not, add the following line to ~/.bashrc:

export PATH="$PATH:$HOME/.local/bin"

Then either start a new terminal session or run the command above in the current session to update the $PATH.

As initially set up, Arduino CLI is unable to communicate with any board. This requires installing “cores”, which contain information and specific tools for specific board architectures. First, download the list of available cores with:

arduino-cli core update-index

In order to know which core to install, connect your Arduino board to your computer, then run the command below:

arduino-cli board list

For example, with a single Arduino UNO connected, the output will be something like this:

Port         Protocol Type              Board Name  FQBN            Core
/dev/ttyACM0 serial   Serial Port (USB) Arduino Uno arduino:avr:uno arduino:avr

Now run the command below:

arduino-cli core install $CORE

Replacing $CORE with the value in the Core column from the output of arduino-cli board list — in the case above, arduino:avr.

If your code uses any extra libraries, they also need to be installed. For example, to install the TimerInterrupt library, enter:

arduino-cli lib install "TimerInterrupt"

Once your environment is properly set up, a sketch can be compiled with:

arduino-cli compile --fqbn $FQBN --warnings all $PATH_SKETCH

Where $FQBN is the Fully-Qualified Board Name (arduino:avr:uno in the example above). If you have your board connected to your computer, finding the FQBN can be automated with:

arduino-cli compile \
  --fqbn $(arduino-cli board list | grep -oEi 'arduino:[^ ]+:[^ ]+') \
  --warnings all \
  $PATH_SKETCH

In contrast to the Arduino IDE, the Arduino CLI does not automatically compile a sketch before upload, so make sure to run this command following any changes to the code. Also notice that we set option –warnings all to make sure we’re notified in case of any compilation warnings. This is important since warnings can often be indicative of programming mistakes, and it’s generally good practice to resolve them whenever possible.

Finally, a sketch can be uploaded to a board with:

arduino-cli upload -p $PORT --fqbn $FQBN $PATH_SKETCH

Where $PORT and $FQBN can be found from the output of arduino-cli board list as shown above. This can be automated with a little shell scripting as below:

arduino-cli upload \
  $(arduino-cli board list | perl -ne 'm/([^ ]+).+(arduino:[^ ]+:[^ ]+)/ && print "-p $1 --fqbn $2"') \
  "$PATH_SKETCH"

The above commands can be added to shell scripts for easy reuse:

#!/bin/bash

# arduino-compile.sh

arduino-cli compile \
  --fqbn $(arduino-cli board list | grep -oEi 'arduino:[^ ]+:[^ ]+') \
  --warnings all \
  "$1"

#!/bin/bash

# arduino-upload.sh

arduino-cli upload \
  $(arduino-cli board list | perl -ne 'm/([^ ]+).+(arduino:[^ ]+:[^ ]+)/ && print "-p $1 --fqbn $2"') \
  "$1"

Create the scripts under ~/.local/bin, then give them execute permission with:

chmod u+x $HOME/.local/bin/arduino-compile.sh
chmod u+x $HOME/.local/bin/arduino-upload.sh

The scripts can then be used as below:

arduino-compile.sh "$PATH_SKETCH"
arduino-upload.sh "$PATH_SKETCH"