For users who prefer to use their own text editor, there is a command line interface version of the Arduino. “arduino-cli is an all-in-one solution that provides builder, boards/library manager, uploader, discovery and many other tools needed to use any Arduino compatible board and platforms.” It allows you to work with your favorite text editor, and to program in a text-only mode. The gitHub repository for the project includes a pretty good getting started guide to the arduino-cli on the main page, but there are a few extra steps you may want to take to set things up for more convenience. These instructions are written for MacOS, but should work on any POSIX operating system, and might work on Windows with the Linux Subsystem for Windows or with Cygwin, an older collection of Linux command line tools for Windows
Note that as of Sept. 2018, the arduino-cli is still in alpha, meaning that features are still subject to change.
Download the Application
From the gitHub repository, download the latest stable release of arduino-cli. Unzip the resulting download and move the unzipped application to your Applications directory (Linux users may prefer to move it to /usr/bin or /usr/local/bin). Then open the Terminal app (MacOS) or a shell window (Linux) to set things up.
Configure Your Command Line Environment
For those new to command line interfaces, there are a few terms that are helpful to know as well. The command line interface for MacOS is called a shell, specifically the bash shell.There are other shell environments for Linux and Unix (sometimes you’ll hear these collectively referred to as POSIX systems; here’s a longer introduction to command line interfaces in POSIX systems), but the bash shell is one of the most common. The parameters of the shell are called environment variables, and for the bash shell on MacOS, they are stored in a file called .bash_profile. They’re different for each user, so the .bash_profile file is kept in each user’s home directory. The path to this directory is /Users/username on MacOS, or /home/username on Linux. The shortcut for the home directory is ~. For example, ~Documents/ is the path to your Documents folder. When you’re on the command line, you can always get back to the home directory by typing cd and then pressing enter. You can check what directory you are in by typing pwd (for print working directory)
It’s helpful to add a few modifications to your command line environment to make arduino-cli easier to work with. First, open .bash_profile in your favorite text editor. The dot at the beginning of the filename means this is hidden file, so it won’t show up when you list files. To see it using the command line list command (ls), type ls -a and you’ll see all the hidden files. To open any file in your text editor, type
open -a editorName filename
Replace editorName with the name of your editor, For example, to open the .bash profile in XCode, type open -a editorName .bash_profile.
That open trick is so useful that you’ll want to add a shortcut to your profile. At the end of the file, add the following line:
alias xcode="open -a xcode"
Change the alias name and the editor name as you see fit. Now you can open your editor from the command line. This is useful for other development activities, like working in node.js, p5.js, or Python. Next you need to add the Applications directory to your PATH environment variable so that the shell knows where to find it. Add a new line to the file as follows:
export PATH=${PATH}:/Applications
Arduino-cli does not include the built-in examples that come with the original Arduino graphic IDE. If you’ve installed the original IDE, you have them, but you might want to create an shortcut in your Arduino sketches directory to get to them. Here are the paths to the examples for MacOS, Windows, and Linux:
MacOS: (assuming you installed the Arduino IDE in your applications folder already): /Applications/Arduino.app/Contents/Java/examples
Windows 10: C:\Users\”USERNAME”\AppData\
Linux: ~arduino-1.8.x/examples
To create the shortcut, change directories to your sketch directory and type:
ln -s /Applications/Arduino.app/Contents/Java/examples
and you’ll then have be able to get to them directly from the sketches directory. On Linux or Windows, change the path accordingly.
Finally, if you find the default shell prompt too long, you can add a custom shell prompt. For example, the default MacOS shell prompt is computer-name:directory username$. This appears after you run every process on the command line, before you get to run a new process. To shorten the command prompt to a single $, add this line to your .bash profile:
export PS1="$ "
The $ prompt is common enough that you’ll usually see it at the beginning of any command line instructions in tutorials. If you see it, type what follows it at your command prompt.
To put these changes into effect, save your .bash_profile file, type exit on the command line to close your command line session, then re-open a new shell window. In the new window, you should see that the command prompt is now just a $ symbol. To test your editor shortcut, type
$ touch foo.txt
This will create a new file called foo.txt in your current directory. Then type
$ xcode foo.txt
This should launch XCode (or whatever editor you chose) and open the file foo.txt.
Using arduino-cli
To use arduino-cli on the command line, type its name followed by whatever parameters you want to use. If you type arduino-cli with no parameters, you’ll get a list of the commands available. The application that you downloaded is probably not just called arduino-cli, however. It’s probably something longer, like arduino-cli-0.2.2-alpha.preview-osx. Fortunately, you don’t have to type the whole name. The shell will auto-complete any command you type if it can when you press the tab key. If you type ard then press tab, it should autocomplete the name of the program. In this tutorial, the application name will be shortened to arduino-cli.
To create a new sketch, type:
$ arduino-cli sketch new SketchName
This will create a new sketch in the default Arduino sketch directory. On MacOS, this directory is ~Documents/Arduino/, so the sketch would be in ~Documents/Arduino/. To get to the directory to work on this new sketch, type:
$ cd ~Documents/Arduino/SketchName
Now that you’ve got your command line environment set up, the getting started with arduino-cli guide will take you through the steps of creating a new sketch, configuring the environment, and uploading it. Below is a summary of the commands you’ll use the most.
New Sketch: arduino-cli sketch new mySketch – creates a new sketch called mySketch in the default Arduino sketch directory
List Available boards: arduino-cli board list – list all boards attached to the computer. This is equivalent to getting the port list in the Arduino graphic IDE.
List All Known Boards: arduino-cli board listall – list all boards in your boards manager. This is equivalent to getting the boards list in the graphic IDE. This produces a long list, so if you wanted to search it for a particular subset, you might use the POSIX grep command like so:
$ arduino-cli board listall | grep mkr
The preceding command would list all known boards with the substring mkr in their name.
Compile: arduino-cli compile -b board:name path/to/sketch – compile the sketch for the given board name. This is equivalent to the Verify command in the graphic IDE. You don’t need the sketch path if you’re already in the sketch directory. For example, to compile the sketch in the current directory for the Uno:
$ arduino-cli compile -b arduino:avr:uno
Or for the MKRZero:
$ arduino-cli compile -b arduino:samd:mkrzero
Attach Board: arduino-cli board attach board:name – attaches a specific board name to a sketch. This is equivalent to choosing a board in the graphic IDE. If you do this when you first set up a new sketch, you won’t need to give a board name every time every time you compile, you can just type
$ arduino-cli compile
Upload: arduino-cli upload -p portname – upload compiled sketch to the portname given. This is equivalent to uploading in the IDE. Note that this command does not re-compile before uploading. For example:
$ arduino-cli upload -p /dev/cu.usbmodem1411
Find a core: arduino-cli core search coreName – searches for known processor architectures. You can search by processor type, like AVR or M0, or you can search by board name, like Mega or MKR. For example:
$ arduino-cli core search mkr
Install a core: arduino-cli core install coreName – installs a core once you find it. ou must use the full core name, though. For example the core search for MKR above resulted in a core called arduino:samd. To install it, type:
$ arduino-cli core install arduino:samd
Find a library: arduino-cli lib search libraryName – searches the Arduino library manager index for libraries containing the word libraryName. For example, the following will list all MQTT-related libraries in the index:
$arduino-cli lib search mqtt
Install a library: arduino-cli lib install libraryName – install a library that’s listed in the Arduino library manager index. For example:
$ arduino-cli lib install WiFiNINA
or for libraries with multiple word names, use double quotes around the name like so:
$ arduino-cli lib install "Arduino Low Power"
For more information, see the arduino-cli guide. Check back frequently for changing features until it is out of alpha.
Using the Serial Port
On MacOS and Linux, the command line allows you to read input from a serial port just as you would from a file, using the cat command. cat /dev/cu.usbmodemXXXX will open an Arduino’s serial port, if no other application has it open already. control-C will close it.