Using The Arduino Command Line

Last Updated: August 30, 2023
Originally Published: April 14, 2019

Skill Level: Intermediate

Introduction
What Is Needed
Background Information
Core Platforms And Fully Qualified Board Names
The Arduino CLI Tool
Additional Resources
Summary

Introduction

This tutorial will teach you how to create, compile, and upload your Arduino sketches and manage your Arduino compatible boards from the command line using the Arduino CLI tool.

It is expected that you already have some familiarity with the Arduino platform and have installed and worked within the Arduino IDE application to program your Arduino board(s). If you are new to Arduino, or would just like to refresh your knowledge, please see our Blink: Making An LED Blink On An Arduino Uno tutorial before proceeding with this one.

In addition to this tutorial, the Arduino Command Line Cheatsheet is also available that you can download for future quick reference.

This tutorial is provided as a free service to our valued readers. Please help us continue this endeavor by considering a GitHub sponsorship or a PayPal donation.

What Is Needed

Linux, macOS, Or Windows Based Computer With A USB Port
Arduino IDE Application
Arduino Development Board (Uno R4 Minima available on Arduino and Sparkfun; Uno R4 WiFi on Arduino and Sparkfun) With Compatible USB Cable

Background Information

Although the Arduino IDE is a very useful and free integrated development environment for developing and uploading code to an Arduino compatible board, sometimes you just want to use your tried and true code editor instead. Or perhaps you want to automate the build and release process through shell or batch scripting. Using the Arduino CLI command line interface tool lets you do just that.

The original (legacy) Arduino IDE 1.x application provided the means to program and manage microcontroller boards from either the IDE GUI or from the command line. This dual capability was split into separate tools with the latest releases from Arduino. The Arduino IDE 2.x application now provides the graphical user interface and the Arduino CLI tool provides the command line interface. In actuality, the new IDE calls the CLI utility for most of its board management functions.

I am using the Arduino Uno R4 WiFi development board connected to a macOS based computer with a previously installed Arduino IDE for this tutorial. If you are using a different Arduino board or computer setup, the vast majority of this tutorial should still apply, however, some minor changes may be necessary.

If you need assistance with your particular setup, post a question in the comments section below and I, or someone else, can try to help you.

Core Platforms And Fully Qualified Board Names

Before we delve into how to use the Arduino CLI tool, it is helpful to understand the concepts behind core platforms and fully qualified board names. The CLI utility uses these concepts when working with your Arduino board(s).

Core platforms (libraries) provide the necessary resources to utilize a specific category of boards within the Arduino ecosystem. They typically represent the vendors and microcontroller architectures of supported boards and are the libraries listed within the Boards Manager of the Arduino IDE. They are installed in the packages directory within the local user’s Arduino library or data folder for the following operating systems.

Windows: C:\Users\<username>\AppData\Local\Arduino15\packages
macOS: /Users/<username>/Library/Arduino15/packages
Linux: /home/<username>/.arduino15/packages

Fully qualified board names (FQBN) are board identifiers used for specifying individual boards with the Arduino CLI tool. The format for an FQBN is as follows.

Syntax: fqbn = <package>:<architecture>:<board>, where
<package> is the vendor identifier, typically arduino
<architecture> is the microcontroller architecture, e.g., avr, megaavr, renesas_uno, samd, etc.
<board> is the board name defined by the core platform, e.g., uno, uno2018, unor4wifi, nano, etc.

The following are some example FQBN identifiers for popular Uno boards.

arduino:avr:uno (Arduino Uno R3)
arduino:megaavr:uno2018 (Arduino Uno WiFi Rev2)
arduino:renesas_uno:unor4wifi (Arduino Uno R4 WiFi)

The core portion of an FQBN is defined by the first two fields (<package>:<architecture>) and represents the associated installed core platform. The board portion of an FQBN is defined within the boards.txt file found within the core platform library. A boards.txt file contains the names and configuration information for all of the boards supported for that particular core platform. They are located in the <package>/hardware/<architecture>/<version> directory for each core. For example, the boards.txt file for version 1.8.6 of the Arduino AVR Boards core library is located at /Users/<username>/Library/Arduino15/packages/arduino/hardware/avr/1.8.6/boards.txt on my macOS based system.

The FQBN identifier for a connected board can be determined by the Arduino CLI tool as we will see shortly.

The Arduino CLI Tool

According to the Arduino CLI tool’s documentation, “Arduino CLI is an all-in-one solution that provides Boards/Library Managers, sketch builder, board detection, uploader, and many other tools needed to use any Arduino compatible board and platform from command line or machine interfaces”.

Locating And Running The Executable

Since the Arduino CLI tool comes bundled with an Arduino IDE 2 installation, install the latest version of the IDE if you have not done so already. The CLI executable is located within the resources/app/lib/backend/resources (or similar) directory within the IDE installation and is named arduino-cli.exe for Windows and arduino-cli for macOS and Linux based systems.

Make sure to close the Arduino IDE before using the command line as it may interfere with your results.

When running the executable, we need to include the full path name in the command, make sure the path is in our path environment variable, or define some sort of alias or symbolic link to the executable. I chose to make an alias on my Mac for the executable and will use the simple arduino-cli name throughout the rest of this tutorial.

alias arduino-cli '/Applications/Arduino\ IDE.app/Contents/Resources/app/lib/backend/resources/Arduino-cli'

Test that it is working properly by running the following within a command or terminal window

$ arduino-cli version

and it should print the version information of the executable.

arduino-cli  Version: 0.34.0 Commit: 304d48cd Date: 2023-08-22T15:54:21Z

The Arduino CLI tool provides a great help system that can be invoked by running one of the following commands, replacing the <command> placeholder with the appropriate command (and subcommand, if applicable).

$ arduino-cli
$ arduino-cli help [<command>]
$ arduino-cli [<command>] --help

For instance, if you want to get help on creating a new sketch, request help with the following command.

$ arduino-cli sketch new --help

To get a listing of all top level commands available, just run the arduino-cli executable without any options.

Creating A Sketch

Now that we know how to create a new sketch, let’s do so. Go to your home or project directory and run the following command.

$ arduino-cli sketch new Blink_CLI

This will create a new directory named Blink_CLI that contains the associated Blink_CLI.ino program file. That file will contain only the base setup() and loop() functions and is meant to be a starting point for your new sketch. Update and save the sketch file with the following simple example using your favorite code editor.

void setup() {
   Serial.begin(9600);
   while (!Serial);
   pinMode(LED_BUILTIN, OUTPUT);
}

void loop() {
   Serial.println("Blinking built-in LED.");
   digitalWrite(LED_BUILTIN, HIGH);
   delay(1000);
   digitalWrite(LED_BUILTIN, LOW);
   delay(1000);
}

Managing Core Platforms

Before going any further, it is a good idea to update the indexes of available core platforms and libraries and upgrade them as necessary. This is typically performed through the automated notifications received within the IDE, but we can perform manual updates and upgrades on the command line.

$ arduino-cli update

Once the indexes have been updated, we can show and upgrade the outdated cores and libraries with the following commands.

$ arduino-cli outdated
$ arduino-cli upgrade

The following command lists the platform cores that have been installed on your system

$ arduino-cli core list

with the following being the packages installed on my system.

ID                  Installed Latest Name
arduino:avr         1.8.6     1.8.6  Arduino AVR Boards
arduino:megaavr     1.8.8     1.8.8  Arduino megaAVR Boards
arduino:renesas_uno 1.0.2     1.0.2  Arduino UNO R4 Boards

On the off chance that you have not already installed the necessary core for your board through the IDE, you can search for and install it from the command line. For instance, for my Arduino UNO R4 WiFi board, I can run

$ arduino-cli core search uno

to search for all cores supporting Uno boards and then install the appropriate core.

$ arduino-cli core install arduino:renesas_uno

Next, connect your Arduino board(s) to your computer and run the following command to discover all connected boards.

$ arduino-cli board list

The output shows you the basic information for your board(s) including the fully qualified board name(s) (FQBN) and associated serial port(s). I received the following information for my board.

Port                            Protocol Type              Board Name          FQBN                          Core
/dev/cu.usbmodemDC5475C3BE142   serial   Serial Port (USB) Arduino UNO R4 WiFi arduino:renesas_uno:unor4wifi arduino:renesas_uno

Compiling And Running Sketches

Now that we know the FQBN and serial port for our board, let’s get back to our Blink_CLI sketch. Go into the sketch directory and compile (verify) the sketch to check it for errors by running the following command, replacing the <fqbn> placeholder with the appropriate one for your board.

$ arduino-cli compile --fqbn <fqbn>

Fix any errors found in your sketch and then upload it to your board, replacing the <fqbn> and <port> placeholders this time.

$ arduino-cli upload --fqbn <fqbn> --port <port>

The following is my full command.

$ arduino-cli upload --fqbn arduino:renesas_uno:unor4wifi --port /dev/cu.usbmodemDC5475C3BE142

Your board should now have a blinking LED.

Note, the previous commands can be run from any directory if you append the optional sketch path to the the end of the commands.

I bet by now you are wondering why I included serial output in the simple sketch we created earlier. An extremely nice feature that Arduino added to the CLI utility is the ability to view serial output from the command line. Run the following command with the appropriate <port> value.

$ arduino-cli monitor --port <port>

You should see

Blinking built-in LED.

being printed to the terminal screen every couple of seconds. When you’re done viewing the serial output, press CTRL-C to exit the serial monitor. I specified a baud rate of 9600 bits per second within the sketch. This is also the default value expected by the monitor command. If you specify a different baud rate in your sketch (e.g. 57600), you will need to let the monitor command know by appending the ‐‐config baudrate=57600 option to the command. For instance, I would use the following for my board.

$ arduino-cli monitor --port /dev/cu.usbmodemDC5475C3BE142 --config baudrate=57600

Are you getting tired of having to type the FQBN and port values yet? You are going to love this next feature. Run the following command, again replacing the placeholders with the appropriate values for your board.

$ arduino-cli board attach --fqbn <fqbn> --port <port>

This command creates a sketch.yaml file within the sketch directory that contains the default values for the FQBN and port values now attached to this particular sketch. Once these values are set, you no longer need to include those values in subsequent commands. You can now run simple commands like

$ arduino-cli compile

and

$ arduino-cli upload

or even combine the two with

$ arduino-cli compile --upload

and they will function just like they did before. Unfortunately, the monitor command does not yet recognize the port value set within the sketch.yaml file, so the port still needs to be specified for that command.

Managing Libraries

Let’s turn our attention to libraries. Run the following command to list the installed libraries.

$ arduino-cli lib list

You should see a listing similar to the following that includes libraries installed by the user along with those installed with an IDE installation.

Name                    Installed Available Location              Description
Arduino_BuiltIn         1.0.0     -         LIBRARY_LOCATION_USER -
Arduino_LSM6DS3         1.0.2     -         LIBRARY_LOCATION_USER -
PubSubClient            2.8       -         LIBRARY_LOCATION_USER -
SD                      1.2.4     -         LIBRARY_LOCATION_USER -
Servo                   1.2.1     -         LIBRARY_LOCATION_USER -
Stepper                 1.1.3     -         LIBRARY_LOCATION_USER -
WiFiNINA                1.8.14    -         LIBRARY_LOCATION_USER -

If you append the ‐‐all option to the command, it will also show you the libraries included within the installed core platforms, e.g. the following SPI library. Notice that the library location changed from LIBRARY_LOCATION_USER to the core’s name and version.

SPI                     1.0       -         arduino:avr@1.8.6         -

Now let’s say you heard about this cool library named JLed that lets you control LEDs in interesting ways and you want to check it out further. Run the following command to search for the JLed library.

$ arduino-cli lib search Jled

It will print a detailed listing of the various libraries available that match the search criteria, typically just the library’s name. When you are ready to install the library, use the following command.

$ arduino-cli lib install Jled

Once the library is installed, you can run the following to view a listing of all the example sketches included within the Jled library.

$ arduino-cli lib examples Jled

Now that you have some examples, I will leave it to you whether you want to continue exploring the Jled library.

We have only covered a subset of the Arduino CLI tools commands available. Use the help system or the online documentation to investigate further. Try some additional commands and options and see what you get.

Resetting GPIO Pins

Before we end, now would be a good time to create and upload a BareMinimum sketch in order to reset all of the board’s GPIO pins back to their default states. This ensures that no outputs are being driven that may damage your board or connected electronics when plugging in your board for your next project. Go back up a level to your project or home directory and then run the following commands, replacing the <fqbn> and <port> placeholders one last time with the appropriate values for your board.

$ arduino-cli sketch new BareMinimum
$ arduino-cli compile --fqbn <fqbn> --port <port> --upload BareMinimum

We did not need to update the sketch since it already contains the empty setup() and loop() functions needed by default.

Additional Resources

Summary

In this tutorial, we learned how to use the Arduino CLI (arduino-cli) command line interface tool to program and manage Arduino compatible boards from the command line.

Specifically, we learned

about core platforms and fully qualified board names and how they are used with the arduino-cli utility,
how to create, compile, and upload sketches to a board along with monitoring its serial output, and
how to search for and install core platforms and user libraries.

Hopefully, this tutorial provided you with a good understanding of how to use the Arduino CLI tool in your own projects.

As a reminder, this tutorial was provided as a free service to our valued readers. Please help us continue this endeavor by considering a GitHub sponsorship or a PayPal donation.

Thank you for joining me on this journey and I hope you enjoyed the experience. Please feel free to share your thoughts or questions in the comments section below.