Arduino CLI Tutorial

Introduction

There is an official Arduino CLI application that allows you to compile and upload sketches from the command-line without IDE.

This guide will walk through the process of installing and configuring the CLI tool as well as compiling and uploading sketches. It will also cover third-party boards and libraries like the ESP8266, Adafruit PyPortal, and Seed Studio boards like Seeeduino Nano.

Read the official documentation and view the source code at https://github.com/arduino/arduino-cli.

Install arduino-cli

You can either download the pre-built binary or build it from source yourself. It is written in Go so it generates a single statically linked executable.

Download pre-built executable

Download the official pre-built release for Windows, Linux, Mac, or ARM from the GitHub page.

Download arduino-cli releases

For example, arduino-cli_0.5.0_Windows_64bit.zip .

After downloading it, Unzip it and put the binary file in a directory that is in your PATH or you will have to refer to the executable using it's full path.

If needed, rename the executable to arduino-cli for convenience.

Build from source

Alternatively, if you want to build it from source (maybe unstable), you will need Go installed. Then run the go get command shown below and the binary will be in your $GOPATH/bin or $GOBIN directory.

go get -u github.com/arduino/arduino-cli

Verify installation

To check everything working, you can try to run the tool and check the version:

arduino-cli version

Setup

Before compiling and uploading sketches there is some setup to do. You will need to:

Update the board index that tracks all available boards you can install
Search for the cores (board) that you need to support
Install any cores (boards) that you need

Once you have done these steps, you can compile and upload sketches. Let's look at each of the setup steps individually.

Update board index

Before doing anything, update the index of boards by running:

arduino-cli core update-index

Search for board support

You can search for available cores using arduino-cli core search. Some example searches:

arduino-cli core search arduino
arduino-cli core search leonardo
arduino-cli core search uno
arduino-cli core search samd

In this example, I am using a TinyLab which has an Arduino Leonardo board that uses the arduino:avr core, just like an Arduino Duemilanove. Boards that have an SAMD21/SAMD51 chip use the arduino:samd core.

Install board support

After finding the ID of the platform you need, in my case, arduino:avr you need to install it. You can do that like this:

# Arduino board support like Leonardo/Uno
arduino-cli core install arduino:avr
# Or if you need SAMD21/SAMD51 support:
arduino-cli core install arduino:samd

Verify installed cores with:

arduino-cli core list

To get a complete list of all boards supported by your installed cores, use:

arduino-cli board listall

Install third-party board support

To add third-party boards like the ESP8266, Seeed Studio, or Adafruit boards you need to add additional board manager URLs. To do this, you need to create a YAML file named arduino-cli.yaml. This file should go in your current working directory.

Here is an example arduino-cli.yaml that includes additional board URLs for:

NOTE: Make sure it is .yaml and not .yml!!!

# arduino-cli.yaml
board_manager:
  additional_urls:
    - http://arduino.esp8266.com/stable/package_esp8266com_index.json
    - https://adafruit.github.io/arduino-board-index/package_adafruit_index.json
    - https://raw.githubusercontent.com/Seeed-Studio/Seeed_Platform/master/package_seeeduino_boards_index.json

After creating the YAML file, you will need to update the index again:

arduino-cli core update-index

You should see output like this:

Updating index: package_index.json downloaded
Updating index: package_index.json downloaded
Updating index: package_esp8266com_index.json downloaded
Updating index: package_adafruit_index.json downloaded
Updating index: package_seeeduino_boards_index.json downloaded

After you update the index,

Then you can search for boards like the ESP8266 or Adafruit boards:

arduino-cli core search esp8266
arduino-cli core search adafruit
arduino-cli core search seeed

Let's say you want to install support for ESP8266 boards, Adafruit AVR boards, and Adafruit SAMD boards. You can install those with:

arduino-cli core install adafruit:avr adafruit:samd
arduino-cli core install esp8266:esp8266
arduino-cli core install Seeeduino:avr Seeeduino:samd

After installing the support, you can view the list of boards that you have support installed for with:

arduino-cli board listall

At this point you should see boards like the Adafruit Trinket and NodeMCU listed.

List connected boards

Once your board is connected to your computer with a USB cable and the board support was installed in the previous step, you can list the boards connected to the computer, and it should list the connected boards, the serial port it is using, and the board name.

arduino-cli board list

Example output:

> arduino-cli board list
Port Type              Board Name       FQBN
COM9 Serial Port (USB) Arduino Leonardo arduino:avr:leonardo

NOTE: Not all boards will always show up. For example, my Seeeduino Nano does not show up when using board list, but does show up in the Device Manager and with the mode command line tool and I can still upload to the board.

For more information on connecting over serial and identifying what port/devices are attached, check out my tutorial How to Connect to a Serial Console.

Sketches

Once the tooling is all set up, you can start writing, compiling, and uploading sketches to your board. Let's look at each of those steps.

Create a sketch

The CLI tool comes with a handy command for creating new sketches. This command will create a new sketch for you in your %HOMEPATH\Documents\Arduino\ directory. All it does is create a directory and a .ino with the same file name and a blank void setup() {} void loop() {} file.

arduino-cli sketch new MySketch

Compile a sketch

Here is an example sketch you can use to test with. It is important to put your sketch inside a folder. When compiling and uploading, we will point to the directory containing the sketch and not the sketch itself.

// sketchbook/blink/blink.ino
// Example from https://www.arduino.cc/en/Tutorial/Blink

void setup() {
  pinMode(LED_BUILTIN, OUTPUT);
}

void loop() {
  digitalWrite(LED_BUILTIN, HIGH);
  delay(1000);
  digitalWrite(LED_BUILTIN, LOW);
  delay(1000);
}

Once you have the sketc saved, your board support installed, and the boards fully-qualified board name (FQBN) you can compile the sketch to the proper target. For my example, the FQBN is arduino:avr:leonardo and my sketch is stored in ./sketchbook/blink/blink.ino. I can compile the program with:

# Sketch file should be: sketchbook/blink/blink.ino
arduino-cli compile --fqbn arduino:avr:leonardo sketchbook/blink

The compiled binaries will be in the directory next to the sketch file.

Upload a sketch

To upload the sketch that was just compiled, you need to call upload and pass it the serial port, FQBN, and the directory with the compiled sketch files.

Note that if you are uploading to a board like the AdaFruit PyPortal M4 (SAMD51), you must double-tap the reset button to get it in to the right mode before uploading.

Here is an example of an upload command:

arduino-cli upload --port COM9 --fqbn arduino:avr:leonardo sketchbook/blink

If you need to get the FQBN, use arduino-cli board listall. If you don't see your board, you might need to search (arduino-cli core search <boardname>) and install (arduino-cli core install <name>) to find the board you need. If you can't even find the board in search, then you might need to follow the steps in the section named "Install third-party board support".

If you need to get the serial port/device name (e.g. COM4 or /dev/ttyACM0) use arduino-cli board list to list connected boards, or see my tutorial on How to Connect to a Serial Console.

Install library dependencies

If you want to use any libraries outside of the core Arduino libraries, you can find and install them with the CLI tool. To demonstrate this, we will install the Adafruit Neopixel library and write a test program.

First update your library index with:

arduino-cli lib update-index

Then search for a library, like neopixel:

arduino-cli lib search neopixel

Install the library by its name, for example "Adafruit NeoPixel":

arduino-cli lib install "Adafruit NeoPixel"

Confirm it is installed with:

arduino-cli lib list

Libraries are installed in your Documents\Arduino\libraries\ directory by default. Core libraries are stored in a different location. In Windows they are in an Arduino directory in the AppData\Local directory of your user's home.

To uninstall a library, use the name of the folder in the libraries directory, which might be different from the install name. For example, to uninstall "Adafruit Zero DMA Library" you must use

arduino-cli lib uninstall "Adafruit_NeoPixel"

Example: NeoPixel for PyPortal

To provide an example of how to use third-party library for a third-party board, let's look at how to use the NeoPixel library for the Adafruit PyPortal. This assumes you installed the "Adafruit NeoPixel" library in the previous step and installed the adafruit:samd core support from the earlier steps too. It also assumes you have a PyPortal, but the point is to demonstrate the process.

See my PyPortal CircuitPy Tutorial (AdaBox 011) for more details about the board. Also check out my NeoTrellis M4 CircuitPy Tutorial (AdaBox 010) for another Adafruit board example.

// Example adapted from https://github.com/adafruit/Adafruit_NeoPixel/blob/master/examples/simple/simple.ino
// sketchbook/blink/blink.ino
#include <Adafruit_NeoPixel.h>

#define PIN 2 // Pin 2 on PyPortal
#define NUMPIXELS 1  // Only one pixel on PyPortal

Adafruit_NeoPixel pixels(NUMPIXELS, PIN, NEO_GRB + NEO_KHZ800);

void setup() {
  pixels.begin();
}

void loop() {
  pixels.clear();
  pixels.show();
  delay(250);

  pixels.setPixelColor(0, pixels.Color(0, 255, 0));
  pixels.show();
  delay(250);
}

After writing the sketch, double-tap the reset button the PyPortal to get it in to the proper mode for upload. Then you can compile and upload the sketch using commands similar to these:

arduino-cli compile --fqbn adafruit:samd:adafruit_pyportal_m4 sketchbook/blink
arduino-cli upload --port COM6 --fqbn adafruit:samd:adafruit_pyportal_m4 sketchbook/blink

Be sure to replace the serial port and the sketch names as needed.