Complete Arduino CLI Tutorial: Installation, Use, and Tips

If you're interested in controlling your Arduino ecosystem from the terminal, the Arduino CLI is just what you're looking for: a set of utilities for compiling, uploading, and managing boards and libraries without opening the IDE. This practical guide brings together the essentials and the advanced so you can integrate it into your workflow, whether on Windows, Linux, Raspberry Pi, or within your favorite editor.

Unlike a graphical IDE, the CLI relies on commands that you can chain, automate, or invoke from other tools (like VS Code or scripts), and adds service modes like gRPC and Prometheus metrics. You will see how to create sketches, detect boards, install cores, add libraries and even expose services. for more sophisticated integrations.

What is Arduino CLI and why use it?

Arduino CLI concentrates key capabilities of the official ecosystem: board and library managers, sketch compiler, error detection, hardware and program loader, all in one command line tool. Although it does not always have 1:1 parity with the IDE, covers most needs and is also the heart of official products such as Arduino IDE and Arduino Web Editor.

The CLI is organized as a “command container” (subcommands), each with help available via help. This modular design makes it easy to discover options and fit the tool into automations, CI/CD or reproducible flows.

Beyond interactive use, it can run as a gRPC service with Prometheus metrics support, opening the door to programmatic integrations and observability. It is an all-in-one solution for Arduino compatible boards and for third-party platforms through additional indexes.

Installation on Windows, Linux, and Raspberry Pi (and WSL considerations)

On Linux, a clean way is to use the script official installation from your user folder, taking advantage of ~/.local/bin to avoid administrator privileges. From your home directory, run:

cd ~/.local
curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh

On macOS, there is a package via Homebrew, while on Windows, you can download the executable published by Arduino and place it in a folder included in your PATH. On Windows, add the EXE folder to the PATH environment variable to invoke it from any terminal.

On Raspberry Pi, the CLI runs particularly smoothly and lightweight compared to the IDE, allowing you to edit with Geany or Code OSS without loading Java. The experience in Pi is usually better than with the traditional IDE for consumption and speed.

With classic WSL (WSL1) board detection often fails, so even if the CLI is installed, you won't be able to easily upload to the board; in WSL2 the result can be similar depending on the configuration. USB. To avoid problems, run the upload from native Windows or Linux with real access to the serial port.

Getting started: built-in help and configuration file

The CLI organizes its functions into subcommands with context-sensitive help. To view global or subcommand help:

arduino-cli help
arduino-cli <comando> --help

A configuration file is not required, but it saves typing and makes behavior more predictable. Initialize a base configuration with:

arduino-cli config init

This step generates a YAML (e.g. arduino-cli.yaml or .cli-config.yml) with important keys. Adjust these two options specifically:

• sketchbook_path: your Arduino notebook directory (where you keep sketches, manual libraries, and additional hardware).
• arduino_data: location where the CLI stores board manager and library data (normally this does not need to be changed).

Additionally, you can define additional package indexes (third-party cores) under board_manager and customize metric parameters if you use daemon mode. Centralizing these routes avoids inconsistencies between IDE and CLI.

Create and edit a new sketch

To generate the structure of a project, the CLI can create a folder and a .ino with the basic skeleton. Use the modern variant of the sketch subcommand:

arduino-cli sketch new MiPrimerSketch

You'll also find references to the classic new command; in both cases, you'll get a directory with MyFirstSketch.ino ready to edit. Open the .ino in your favorite editor and modify the initial code as needed.

If you prefer to set an explicit path, include the full directory at the end of the command. The CLI will respect your sketchbook_path when you do not specify absolute paths.

Detect your license plate, update indexes, and understand the FQBN

After a recent installation, it is advisable to update the cache of available platforms and libraries. Run:

arduino-cli core update-index
arduino-cli lib update-index

Connect the board via USB and check if the system detects it. List plates connected with:

arduino-cli board list

If your board appears with its FQBN (Fully Qualified Board Name), you already know which core to install and which identifier to use to compile/upload. The FQBN follows the manufacturer:architecture:board format, for example arduino:avr:uno.

When the system displays Unknown as the license plate, you will still be able to board if you know the correct FQBN. To see all supported boards and their FQBNs:

arduino-cli board listall

Install the appropriate core (example arduino:samd)

If your board belongs to the SAMD family (like MKR1000), install its core. For example:

arduino-cli core install arduino:samd

Check that it is installed correctly by listing available platforms. Check the installation with:

arduino-cli core list

Once the appropriate core is installed, you can compile and upload for that board family with its FQBN. This step is essential before the first compilation.

Add third-party cores (ESP8266, ESP32, NRF52, etc.)

For boards supported by external communities, add additional index URLs in the CLI configuration under board_manager.additional_urls. Example with ESP8266 (adding the public URL of the core):

board_manager:
  additional_urls:
    - https://arduino.esp8266.com/stable/package_esp8266com_index.json

If you have local indexes, you can include file paths instead of URLs. For example, for an NRF52832 packet stored on your computer:

board_manager:
  additional_urls:
    - file:///ruta/a/tu/package_nrf52_index.json

From that point on, commands that operate on those cores will automatically use the additional sources defined in the YAML. As a punctual alternative, add the –additional-urls option to each command:

arduino-cli core install esp8266:esp8266 --additional-urls https://arduino.esp8266.com/stable/package_esp8266com_index.json

You can also use file paths with –additional-urls for local packages. Remember to repeat the option in each command that affects that core. if you haven't put it in the configuration file.

Useful note on popular hardware: The ESP32 family integrates low-energy WiFi and Bluetooth (with Xtensa LX6/LX7 or RISC-V CPU variants, single or dual core), and incorporates RF front-end and power management. It is a frequent target for the CLI due to its power/price balance..

Compile and upload a sketch

To compile, specify the target FQBN; you can compile from the sketch folder or by passing the path. Example for Arduino Uno:

arduino-cli compile --fqbn arduino:avr:uno "C:/Users/tu.usuario/Documents/Arduino/cli_test"

Add -v for greater verbosity or define an artifact directory with –build-path (on Windows, absolute path). Useful flags: -vy –build-path to save .hex and objects.

To upload, specify the serial port with -p next to the FQBN. Example on Windows (COM18):

arduino-cli upload -p COM18 --fqbn arduino:avr:uno "C:/Users/tu.usuario/Documents/Arduino/cli_test"

On Linux, the typical port will look like /dev/ttyACM0 or /dev/ttyUSB0. Check your user's permissions on the serial device if an access error appears.

Search and install libraries

Before reinventing the wheel, explore the library manager—there are thousands ready to use. Search by keyword with:

arduino-cli lib search debouncer

If you like one, install it by name. For example, for a pushbutton decoupler like FTDebouncer. Install with:

arduino-cli lib install FTDebouncer

These libraries are then made available to your sketches and will be integrated by the CLI during compilation. Keep indexes up to date with lib update-index to see what's new.

Daemon mode, gRPC, and Prometheus metrics

The CLI can act as a gRPC server, ideal for integrations from other programs or services. Throw it with:

arduino-cli daemon

In the official repository you will find a client_example directory with example code to consume the API. The gRPC reference documents available services and messages if you want to implement your own client.

Daemon mode exposes a metrics endpoint at http://localhost:9090/metrics ready for Prometheus to pick up. Metrics options are managed in the metrics section of the configuration file., so you can adjust them without recompiling.

Integrate Arduino CLI with VS Code

A very convenient use is to invoke the CLI from VS Code with tasks to compile and upload, while maintaining a modern editing experience. Configure tasks that call compile and upload with your FQBN and port, and you will have keyboard shortcuts for all.

If the CLI can't locate your sketchbook or IDE managers, the YAML configuration file helps resolve paths. Remember to set sketchbook_path and arduino_data so that the environment is unified between IDE, CLI and editor.

On Windows, the downloaded binary may have a long version name; rename it to arduino-cli.exe if you prefer and place it in a folder in your PATH. Avoiding names with spaces simplifies tasks and scripts who invoke him.

Linux and Raspberry Pi Basics Useful for Arduino CLI

Since you're going to be using a terminal, it's a good idea to refresh the basic commands for GNU/Linux and Raspbian (Debian for Raspberry Pi). These shortcuts will make you more agile with the CLI and with system administration.

Concepts: GNU/Linux is a free, cross-platform, multitasking operating system with the Linux kernel and tools from the GNU Project; Raspbian (now Raspberry Pi OS) is its variant designed for the Raspberry Pi SBC. Recommended documentation: TLDP, Raspberry Pi guides and Wikipedia on file hierarchy.

Getting Started with the Command Line (Terminal): Practice file navigation and manipulation. Useful commands to get started:

• Navigation: ls, cd, pwd.
• Directories and files: mkdir, rm, mv, cp.
• See/read: cat, more, less, tail.
• Permissions and owners: chmod, chown.
• System and info: w, free, df, ps, uname, kill.
• Terminal editors: vi, vim, emacs, nano.

Recommended exercise: create an info.txt with a short text, save it, and read it from the terminal with cat or less. You will consolidate editing, reading and basic permissions in a practical way.

General and administration commands on Raspberry Pi: from updating the system to Boot of the graphical environment. Some essentials:

• apt-get update and apt-get upgrade to maintain packages.
• clear to clear the screen, date to display the date.
• find / -name test.txt to locate files.
• nano test.txt for quick editing.
• poweroff, reboot, shutdown -h now or at a specific time.
• raspi-config for Raspberry Pi options.
• startx to start the graphical interface.

Working with the file system: understand paths, permissions, and file transfers. Common commands and examples:

• cat prueba.txt to see the contents.
• cd /abc/xyz to change directories.
• cp file.txt /home/pi/file.txt to copy.
• ls -l to list with details and permissions.
• mkdir test_folder to create folders.
• mv file.txt /home/pi to move or rename.
• rm test.txt and rmdir test_folder to delete.
• scp user@10.0.0.32:/path/file.txt to copy via SSH.
• touch to create an empty file.

Network and connectivity: interface diagnostics and network scanning. Key tools:

• ifconfig/iwconfig to check IP and wireless status.
• iwlist wlan0 scan (and with grep ESSID) for available networks.
• nmap to scan devices and ports on your network.
• ping 8.8.8.8 or ping http://www.google.es to check connectivity.
• wget http://www.miweb.com/prove.txt to downloads via HTTP.

System and package information: Monitor resources and versions to avoid surprises when compiling or uploading. Reference commands:

• cat /proc/meminfo, /proc/partitions and /proc/version for system details.
• df -hy df / for disk space.
• dpkg –get-selections | grep XXX to view related installed packages.
• free for available memory, top for real-time processes.
• hostname -I for IP, lsusb for USB devices.
• vcgencmd measure_temp and vcgencmd get_mem arm/gpu on Raspberry Pi.
• Up arrow (UP) to recall the last command.

Users and Groups: Control permissions and sudo to manage serial devices and deployments. User creation and checks:

• useradd -c "Username" -g group -d /home/user -s /bin/bash username
• su – username to log in as that user
• whoami, who and lastlog for basic auditing

Kernel and services: Remember that the kernel manages memory, CPU, and peripherals, and you can update it on the Pi according to the official documentation. For modern services, systemd is the reference (see the Raspberry Pi guide).

Bash for Productivity: Tab completion and history save you tons of time, and scripts allow for automation. history lists recent commands and you can create aliases or redirects according to the TLDP guide.

Cron Automation: Schedule recurring tasks for nightly builds or deployments. Important: Use crontab -e instead of editing /etc/crontab directly; check logs if something goes wrong and follow best practices.

Webmin: If you're into browser administration, you can install it and manage users, Apache, PHP, MySQL, DNS, Samba, DHCP, etc. After installing dependencies, go to https:// :10000 to use the interface.

Extra tips and quick resources

• Official documentation: The CLI links to installation guides, getting started, and gRPC references; it's worth reading to learn all the flags. The combination of built-in help and online documents accelerates learning.
• Working on Windows: If the downloaded binary comes with a long version name (e.g. arduino-cli-0.2.2-alpha…), you can rename it to arduino-cli.exe and place it in C:\Program Files\Arduino CLI or similar. Add that folder to the system or user PATH.
• Mixed environments: While WSL isn't ideal for uploading to boards, you can build in WSL and upload from Windows, or move artifacts between machines. Divide and conquer if your flow requires it (build in CI, upload locally).
• Additional indexes: When working with ESP8266/ESP32/NRF52, set additional_urls in the YAML to avoid repeating –additional-urls every time. Take care of duplicates and index order to avoid conflicts between versions.
• Continuous integration: Daemon mode and the gRPC interface allow you to orchestrate builds and uploads in pipelines. Exposing metrics at http://localhost:9090/metrics makes it easier to monitor your system. and detect bottlenecks.

With this foundation, you'll be able to move with ease: from creating and compiling sketches, installing official or third-party cores, to uploading via serial port and automating entire flows with gRPC and metrics. Jumping to the CLI will give you fine-grained control, reproducibility, and powerful integration with your editors and scripts., both on Windows and Linux or Raspberry Pi.