## File: README.md # arduino-cli 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. [](https://github.com/arduino/arduino-cli/actions/workflows/test-go-task.yml) [](https://github.com/arduino/arduino-cli/actions/workflows/publish-go-nightly-task.yml) [](https://github.com/arduino/arduino-cli/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml) [](https://codecov.io/gh/arduino/arduino-cli) ## Docs For guidance on installation and development, see the [User documentation]. ## Quickstart 1. [Install] the Arduino CLI 1. Follow the [Getting Started] guide to check out what the CLI can do 1. Browse the [Commands reference] to see all the available commands 1. Should you have an issue, read the [FAQ] page ## How to contribute Contributions are welcome! Please read the document [How to contribute] which will show you how to build the source code, run the tests, and contribute your changes to the project. :sparkles: Thanks to all our [contributors]! :sparkles: ### Testing builds [Nightly builds] are available for testing. ## Security If you think you found a vulnerability or other security-related bug in the Arduino CLI, please read our [security policy] and report the bug to our Security Team 🛡️ Thank you! e-mail contact: security@arduino.cc ## License Arduino CLI is licensed under the GPL-3.0 license. You can be released from the requirements of the above license by purchasing a commercial license. Buying such a license is mandatory if you want to modify or otherwise use the software for commercial activities involving the Arduino software without disclosing the source code of your own applications. To purchase a commercial license, send an email to license@arduino.cc [install]: https://arduino.github.io/arduino-cli/latest/installation [user documentation]: https://arduino.github.io/arduino-cli/latest/ [getting started]: https://arduino.github.io/arduino-cli/latest/getting-started/ [commands reference]: https://arduino.github.io/arduino-cli/latest/commands/arduino-cli [faq]: https://arduino.github.io/arduino-cli/latest/FAQ/ [how to contribute]: https://arduino.github.io/arduino-cli/latest/CONTRIBUTING/ [contributors]: https://github.com/arduino/arduino-cli/graphs/contributors [nightly builds]: https://arduino.github.io/arduino-cli/latest/installation/#nightly-builds [security policy]: https://github.com/arduino/arduino-cli/security/policy --- ## File: docs/index.md 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. In addition to being a standalone tool, Arduino CLI is the heart of all official Arduino development software (Arduino IDE, Arduino Web Editor). Parts of this documentation apply to those tools as well. ## Installation You have several options to install the latest version of the Arduino CLI on your system, see the [installation] page. ## Getting started Follow the [Getting started guide] to see how to use the most common CLI commands available. ## Using the gRPC interface The [client_example] folder contains a sample program that shows how to use the gRPC interface of the CLI. Available services and messages are detailed in the [gRPC reference] pages. [installation]: installation.md [getting started guide]: getting-started.md [client_example]: https://github.com/arduino/arduino-cli/blob/master/rpc/internal/client_example [grpc reference]: rpc/commands.md --- ## File: docs/getting-started.md Arduino CLI provides all the features you can find in the Arduino IDE. Let's see some examples. ## Before you start `arduino-cli` is a container of commands and each command has its own dedicated help text that can be shown with the `help` command like this: ```console $ arduino-cli help core Arduino core operations. Usage: arduino-cli core [command] Examples: arduino-cli core update-index Available Commands: download Downloads one or more cores and corresponding tool dependencies. install Installs one or more cores and corresponding tool dependencies. list Shows the list of installed platforms. search Search for a core in Boards Manager. uninstall Uninstalls one or more cores and corresponding tool dependencies if no longer used. update-index Updates the index of cores. upgrade Upgrades one or all installed platforms to the latest version. Flags: -h, --help help for core Global Flags: --additional-urls strings Comma-separated list of additional URLs for the Boards Manager. --config-file string The custom config file (if not specified the default will be used). --json Print the output in JSON format. --log Print the logs on the standard output. --log-file string Path to the file where logs will be written. --log-format string The output format for the logs, can be: text, json --log-level string Messages with this level and above will be logged. Valid levels are: trace, debug, info, warn, error, fatal, panic --no-color Disable colored output. Use "arduino-cli core [command] --help" for more information about a command. ``` ## Create a configuration file Arduino CLI doesn't strictly require a configuration file to work because the command line interface provides any possible functionality. However, having one can spare you a lot of typing when issuing a command, so let's go ahead and create it with: ```sh $ arduino-cli config init Config file written: /home/luca/.arduino15/arduino-cli.yaml ``` If you inspect the contents of `arduino-cli.yaml`, you'll find the available options with their respective default values. For more information, see the [configuration documentation]. ## Create a new sketch To create a new sketch named `MyFirstSketch` in the current directory, run the following command: ```sh $ arduino-cli sketch new MyFirstSketch Sketch created in: /home/luca/MyFirstSketch ``` A sketch is a folder containing assets like source files and libraries; the `new` command creates for you a .ino file called `MyFirstSketch.ino` containing Arduino boilerplate code: ```sh $ cat $HOME/MyFirstSketch/MyFirstSketch.ino void setup() { } void loop() { } ``` At this point you can use your favourite file editor or IDE to open the file `$HOME/MyFirstSketch/MyFirstSketch.ino` and change the code like this: ```c void setup() { pinMode(LED_BUILTIN, OUTPUT); } void loop() { digitalWrite(LED_BUILTIN, HIGH); delay(1000); digitalWrite(LED_BUILTIN, LOW); delay(1000); } ``` ## Connect the board to your PC The first thing to do upon a fresh install is to update the local cache of available platforms and libraries by running: ```sh $ arduino-cli core update-index Updating index: package_index.json downloaded ``` After connecting the board to your PC by using the USB cable, you should be able to check whether it's been recognized by running: ```sh $ arduino-cli board list Port Type Board Name FQBN Core /dev/ttyACM1 Serial Port (USB) Arduino/Genuino MKR1000 arduino:samd:mkr1000 arduino:samd ``` In this example, the MKR1000 board was recognized and from the output of the command you see the platform core called `arduino:samd` is the one that needs to be installed to make it work. If you see an `Unknown` board listed, uploading should still work as long as you identify the platform core and use the correct FQBN string. When a board is not detected for whatever reason, you can list all the supported boards and their FQBN strings by running the following: ```sh $ arduino-cli board listall mkr Board Name FQBN Arduino MKR FOX 1200 arduino:samd:mkrfox1200 Arduino MKR GSM 1400 arduino:samd:mkrgsm1400 Arduino MKR WAN 1300 arduino:samd:mkrwan1300 Arduino MKR WiFi 1010 arduino:samd:mkrwifi1010 Arduino MKRZERO arduino:samd:mkrzero Arduino/Genuino MKR1000 arduino:samd:mkr1000 ``` ## Install the core for your board To install the `arduino:samd` platform core, run the following: ```sh $ arduino-cli core install arduino:samd Downloading tools... arduino:arm-none-eabi-gcc@4.8.3-2014q1 downloaded arduino:bossac@1.7.0 downloaded arduino:openocd@0.9.0-arduino6-static downloaded arduino:CMSIS@4.5.0 downloaded arduino:CMSIS-Atmel@1.1.0 downloaded arduino:arduinoOTA@1.2.0 downloaded Downloading cores... arduino:samd@1.6.19 downloaded Installing tools... Installing platforms... Results: arduino:samd@1.6.19 - Installed arduino:arm-none-eabi-gcc@4.8.3-2014q1 - Installed arduino:bossac@1.7.0 - Installed arduino:openocd@0.9.0-arduino6-static - Installed arduino:CMSIS@4.5.0 - Installed arduino:CMSIS-Atmel@1.1.0 - Installed arduino:arduinoOTA@1.2.0 - Installed ``` Now verify we have installed the core properly by running: ```sh $ arduino-cli core list ID Installed Latest Name arduino:samd 1.6.19 1.6.19 Arduino SAMD Boards (32-bits ARM Cortex-M0+) ``` Great! Now we are ready to compile and upload the sketch. ## Adding 3rd party cores If your board requires 3rd party core packages to work, you can list the URLs to additional package indexes in the Arduino CLI configuration file. For example, to add the ESP8266 core, edit the configuration file and change the `board_manager` settings as follows: ```yaml board_manager: additional_urls: - https://arduino.esp8266.com/stable/package_esp8266com_index.json ``` If you have your package indexes locally installed, you can list their file path in the Arduino CLI configuration file. For example, to add the NRF52832 core, edit the configuration file and change the `board_manager` settings as follows: ```yaml board_manager: additional_urls: - https://arduino.esp8266.com/stable/package_esp8266com_index.json - file:///absolute/path/to/your/package_nrf52832_index.json ``` From now on, commands supporting custom cores will automatically use the additional URL from the configuration file: ```sh $ arduino-cli core update-index Updating index: package_index.json downloaded Updating index: package_esp8266com_index.json downloaded Updating index: package_nrf52832_index.json Updating index: package_index.json downloaded $ arduino-cli core search esp8266 ID Version Name esp8266:esp8266 2.5.2 esp8266 ``` Alternatively, you can pass a link to the additional package index file with the `--additional-urls` option, that has to be specified every time and for every command that operates on a 3rd party platform core, for example: ```sh $ arduino-cli core update-index --additional-urls https://arduino.esp8266.com/stable/package_esp8266com_index.json Updating index: package_esp8266com_index.json downloaded $ arduino-cli core search esp8266 --additional-urls https://arduino.esp8266.com/stable/package_esp8266com_index.json ID Version Name esp8266:esp8266 2.5.2 esp8266 ``` The same applies to the additional package index file provided by file paths: ```sh $ arduino-cli core update-index --additional-urls file:///absolute/path/to/your/package_esp8266com_index.json Updating index: package_esp8266com_index.json downloaded $ arduino-cli core search esp8266 --additional-urls file:///absolute/path/to/your/package_esp8266com_index.json ID Version Name esp8266:esp8266 2.5.2 esp8266 ``` ## Compile and upload the sketch To compile the sketch you run the `compile` command, passing the proper FQBN string: ```sh $ arduino-cli compile --fqbn arduino:samd:mkr1000 MyFirstSketch Sketch uses 9600 bytes (3%) of program storage space. Maximum is 262144 bytes. ``` To upload the sketch to your board, run the following command, using the serial port your board is connected to: ```sh $ arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:samd:mkr1000 MyFirstSketch No new serial port detected. Atmel SMART device 0x10010005 found Device : ATSAMD21G18A Chip ID : 10010005 Version : v2.0 [Arduino:XYZ] Dec 20 2016 15:36:43 Address : 8192 Pages : 3968 Page Size : 64 bytes Total Size : 248KB Planes : 1 Lock Regions : 16 Locked : none Security : false Boot Flash : true BOD : true BOR : true Arduino : FAST_CHIP_ERASE Arduino : FAST_MULTI_PAGE_WRITE Arduino : CAN_CHECKSUM_MEMORY_BUFFER Erase flash done in 0.784 seconds Write 9856 bytes to flash (154 pages) [==============================] 100% (154/154 pages) done in 0.069 seconds Verify 9856 bytes of flash with checksum. Verify successful done in 0.009 seconds CPU reset. ``` ## Add libraries If you need to add more functionalities to your sketch, chances are some of the libraries available in the Arduino ecosystem already provide what you need. For example, if you need a debouncing strategy to better handle button inputs, you can try searching for the `debouncer` keyword: ```sh $ arduino-cli lib search debouncer Name: "Debouncer" Author: hideakitai Maintainer: hideakitai Sentence: Debounce library for Arduino Paragraph: Debounce library for Arduino Website: https://github.com/hideakitai Category: Timing Architecture: * Types: Contributed Versions: [0.1.0] Name: "FTDebouncer" Author: Ubi de Feo Maintainer: Ubi de Feo, Sebastian Hunkeler Sentence: An efficient, low footprint, fast pin debouncing library for Arduino Paragraph: This pin state supervisor manages debouncing of buttons and handles transitions between LOW and HIGH state, calling a function and notifying your code of which pin has been activated or deactivated. Website: https://github.com/ubidefeo/FTDebouncer Category: Uncategorized Architecture: * Types: Contributed Versions: [1.3.0] Name: "SoftTimer" Author: Balazs Kelemen Maintainer: Balazs Kelemen Sentence: SoftTimer is a lightweight pseudo multitasking solution for Arduino. Paragraph: SoftTimer enables higher level Arduino programing, yet easy to use, and lightweight. You are often faced with the problem that you need to do multiple tasks at the same time. In SoftTimer, the programmer creates Tasks that runs periodically. This library comes with a collection of handy tools like blinker, pwm, debouncer. Website: https://github.com/prampec/arduino-softtimer Category: Timing Architecture: * Types: Contributed Versions: [3.0.0, 3.1.0, 3.1.1, 3.1.2, 3.1.3, 3.1.5, 3.2.0] ``` Our favourite is `FTDebouncer`, let's install it by running: ```sh $ arduino-cli lib install FTDebouncer FTDebouncer depends on FTDebouncer@1.3.0 Downloading FTDebouncer@1.3.0... FTDebouncer@1.3.0 downloaded Installing FTDebouncer@1.3.0... Installed FTDebouncer@1.3.0 ``` ## Using the `daemon` mode and the gRPC interface Arduino CLI can be launched as a gRPC server via the `daemon` command. The [client_example] folder contains a sample client code that shows how to interact with the gRPC server. Available services and messages are detailed in the [gRPC reference] pages. To provide observability for the gRPC server activities besides logs, the `daemon` mode activates and exposes by default a [Prometheus](https://prometheus.io/) endpoint (http://localhost:9090/metrics) that can be fetched for metrics data like: ```text # TYPE daemon_compile counter daemon_compile{buildProperties="",exportFile="",fqbn="arduino:samd:mkr1000",installationID="ed6f1f22-1fbe-4b1f-84be-84d035b6369c",jobs="0",libraries="",preprocess="false",quiet="false",showProperties="false",sketchPath="5ff767c6fa5a91230f5cb4e267c889aa61489ab2c4f70f35f921f934c1462cb6",success="true",verbose="true",vidPid="",warnings=""} 1 1580385724726 # TYPE daemon_board_list counter daemon_board_list{installationID="ed6f1f22-1fbe-4b1f-84be-84d035b6369c",success="true"} 1 1580385724833 ``` The metrics settings are exposed via the `metrics` section in the CLI configuration: ```yaml metrics: enabled: true addr: :9090 ``` [configuration documentation]: configuration.md [client_example]: https://github.com/arduino/arduino-cli/blob/master/rpc/internal/client_example [grpc reference]: rpc/commands.md [prometheus]: https://prometheus.io/