Arduino-cli: compile, upload and manage libraries, cores, and boards

This tutorial describes how to use Arduino-cli to compile, uploads your sketches to an Arduino board or to an alternative board such as ESP32 or ESP8266. Using Arduino-cli we can, also, manage libraries, cores, and board as we will see later during this tutorial.

What is Arduino-cli?

Arduino-cli is a command line interface that you can use to create your sketch and upload it into our boards. It provides all the features we are used to see in the Arduino IDE:

  • Compile the sketch
  • Upload the sketch
  • Library management
  • Boards and cores management

We can use all these features from the command line without using the Arduino IDE.

Shoud we use Arduino-cli?

The answer is yes. Until now, if we wanted to use the Arduino tools, we had to use the Arduino IDE. Even if this IDE is simple and easy to use, it lacks some features. The introduction of Arduino-cli splits the editor from the compile, board, and library management. Therefore, it is possible to use our favorite IDE and manage everything using Arduino-cli. This is a big step ahead.

Arduino-cli concepts

If you are familiar with Arduino IDE, you will not have problems to move to Arduino-cli. Anyway, there are some important concepts or keywords in Arduino command line interface:

  • sketch: it is the source code of tha application we are coding
  • board: it represents the board we are using and where we want to upload the code. A board is identified by a unique id called FQBN.
  • core: it is the core used by the board. There can be several different boards that use the same core
  • library: it is a piece of software that we include in our sketch developed by someone else that manages specific tasks: sensor libraries, LED libraries, protocol libraries and so on

Getting started with Arduino-cli

Before we can make our hand dirty using Arduino command line interface, it is necessary to install it. There are different versions according to your OS (Mac, Window, Linux). We won’t cover it in this tutorial but you can refer to the installation guide (it is very simple).

Once the installation is finished, the first command to use is:

arduino-cli config init

It initialiazies a new configuration:

Arduino-cli initialization

This step generates a file named arduino-cli.yaml that is very important and we will use it later when we will install alternative boards such as ESP32 or ESP8266.

Update core list

Next, we update the core list. This is useful when we want to know if there are new cores available:

arduino-cli core update-index

Listing all the available boards in Arduino-cli

Before coding our sketch, it is important to verify if the board we will use in our Arduino project is supported by the Arduino command line interface application. To do it, this is the Arduino-cli command:

arduino-cli board listall
List all the available boards in Arduino-cli

Notice the FQBN. We will use later during the upload.

Create a sketch using the Arduino command line interface application

Let us start creating our first sketch using the command interface application:

arduino-cli sketch new Documents/Arduino/MKR1000-DHT11Code language: JavaScript (javascript)

In this example, we will develop a simple sketch that uses the DHT11 sensor to read the temperature and the humidity. This command creates a new folder named MKR1000-DHT11 and inside this folder, there is a file with the same name with .ino extension. This is the sketch we will use to build our simple application.

Open this file with your favorite editor and paste this simple code:

#include "DHT.h"
#define PIN 3
#define DHTTYPE DHT11
void setup() {
void loop() {
  int temp = dht.readTemperature();
  int hum = dht.readHumidity();
  Serial.println("Temperature: " + String(temp));
  Serial.println("Humidity: " + String(hum));
}Code language: C++ (cpp)

This example is very simple but t is useful to understand the steps to follow to compile and upload the code.

Moreover, let us suppose we want to upload it to Arduino MKR1000. If you don’t have this board, you can use another Arduino board or a compatible one. Therefore, if you are using another board, please check the PIN number and change it if needed.

Installing an Arduino board

Until now, we have configured our Arduino-cli and create our first sketch. The next step is installing the board to compile the code. If you are familiar with Arduino IDE, it is a step you do in the IDE too. So nothing different!

The MKR1000 is a board based on SAMD so we have to install the corresponding core.

arduino-cli core install arduino:samdCode language: CSS (css)

How to find the core id to use in the core installation command?

There are two different methods to find out the core used by our board:

Search for the core

If you are not sure about the core you have to use to compile your sketch, you can search for it:

arduino-cli core search MKR1000

The result is shown below:

How to search for a board in Arduino-cli

Our core id is arduino:samd. If you have another board, you have to replace MKR1000 with your board name.

List the connected board

The second method is connecting the board to your PC and list all the connected boards:

arduino-cli board listCode language: PHP (php)

The result is:

List of connected boards using Arduino command line interface application

Under the core column, there is the core id.

Installing Arduino library from the command interface

Also this step, it is the same we are used to do in the IDE. The sketch shown above, used the DHT11 sensor. Therefore it is necessary to install the library to manage this sensor. We can do it in two steps:

  • look for the library by name
  • install the library

Look for the library

In this first step, we look for the library to install using the name or a part of it. We are looking for a library to manage the DHT11 sensor, therefore the command is:

arduino-cli lib search DHT11

The result is:

Search for a library in Arduino-cli

The library name is the key we have to use to install it.

Installing the library using the name

In this example, we will use the DHT11 Library developed by Adafruit, then:

arduino-cli lib install "DHT sensor library"Code language: JavaScript (javascript)

Compiling the sketch using the command line

Before uloading the sketch into our board, we have to compile it. To do this task, we need the FQBN of the board we will use to run the sketch. In this example we will use the Arduino MKR1000 board therefore the FQBN is arduino:samd:mkr1000. If you don’t remember your FQBN you simply can list all the available boards and find your board in the list.

To compile the code the command is:

arduino-cli compile --fqbn arduino:samd:mkr1000 MKR1000-DHT11/

where MKR1000-DHT11 is the directory created at the beginning when we have created our first sketch. Wait until the compile task finishes.

Uploading the sketch into your board using Arduino-cli

The last step is uploading the compiled code into our connected board. To do it we need the serial port id where the board is connected. If you don’t know it or you don’t remember, you can list again all the connected boards as we did previously.

To upload the code use this command:

arduino-cli upload --port /dev/cu.usbmodem14201 --fqbn arduino:samd:mkr1000 MKR1000-DHT11/

The parameters are very simple and now we know them all:

All done! The compiled code is now on our board and running on it.

Check the sketch output

If we want to check the output produced by the sketch we can use the following command:

cat /dev/cu.usbmodem14201Code language: Bash (bash)

The result is shown below:

Console output for Arduino sketch

How to use Arduinp-cli with alternative board: ESP32 and ESP8266

By now, we have discussed how to use Arduino-cli with Arduino boards. There’s more. Arduino-cli supports alternative non-Arduino boards such as ESP32 and ESP8266 just to name a few. Listing all the boards supported, you can notice that there are many choices.

In this paragraph, we want to describe how to use Arduino-cli to compile and run sketches on ESP266 and ESP32. The same steps can be applied to other boards.

Installing ESP32 and ESP8266 in Arduinp-cli

The first step is installing this boards into Arduino-cli. To do it, it is necessary to edit the file arduino-cli.yaml that we have created when we have initialized the configuration. The file location changes according to your OS anyway it isn’t hard to find it.

Edit this file adding these two lines:

    - language: YAML (yaml)

Now we can install the ESP32 and the ESP8266:

arduino-cli core install esp8266:esp8266Code language: CSS (css)

and to install ESP32:

arduino-cli core search esp32
arduino-cli core install esp32:esp32Code language: CSS (css)

Compile and run a sketch on ESP32 using Arduino-cli

In this last example, we will create, compile, and run a sketch on ESP32. In this example, we will use a Github repository:

git clone language: PHP (php)

This repository contains a simple ESP32 weather station that was developed using PlatformIO. Before using it with Arduino-cli, it is necessary to rename the file main.cpp in ESP32-Weather-station.ino.

Then this it the list of commands:

  • Find and Install the libraries used by the sketch
arduino-cli lib search BME280
arduino-cli lib search SSD1306
arduino-cli lib install "Adafruit BME280 Library"
arduino-cli lib install "Adafruit SSD1306"Code language: JavaScript (javascript)
  • compile the code
arduino-cli compile --fqbn esp32:esp32:esp2wrover ESP32-Weather-station/
  • Upload it into the ESP32
arduino-cli upload --port /dev/cu.usbserial-0001 --fqbn esp32:esp32:esp32wrover ESP32-Weather-station/

Recommended tutorials:
How to build a Smart plant monitoring system using IoT
How to build an Arduino MQTT client

Wrapping up

At the end of this tutorial, we have discovered a new way to use Arduino based on Arduino-cli that is a command line interface app. Using Arduino-cli it is possible to use our favorite code editor and compile and run the code using Aduino tools.

During this tutorial, we have seen how to use the Arduino-cli to compile and run the sketch. Also, we can use it to manage boards and libraries too.

    1. lazt omen September 28, 2020
      • Francesco Azzola September 29, 2020
    2. Sumithran October 31, 2020
    3. Jose January 25, 2021
    4. user45624 April 19, 2021
    5. O.H. May 27, 2021
    6. Ooops January 25, 2023

    Add Your Comment