It can be used as an automation tool to:
This tool was primarily designed to reduce time spent duplicating projects in the Arduino Cloud. Working with the CLI allows you to quickly make 10+ copies of a Thing, or update sketches on 50+ boards simultaneously.
An example of a workflow using this tool can be:
command and setup a Thing and dashboard using the templates previously extracted.
Let's for example say that you have created a "smart plug" setup, that includes 100 devices in a large building. The firmware running on the devices is not optimal, and needs an update.
With the Arduino Cloud CLI tool, you can not only automate the initial setup of these devices, but also be able to automate the maintenance sequence as well.
If you are new to the Arduino Cloud as well, you can follow the Getting Started guide.
*This is needed only for certain commands, like OTA uploads.
Download and extract the latest release. Make sure it is in your machine's PATH, so that it can be used globally.
After installation, check that it is working by opening a terminal, and type:
The Arduino Cloud CLI has 5 main commands.
- credentials specific commands.
- dashboard specific commands.
- device specific commands
- Over The Air uploads.
- Thing specific commands.
Each command has a set of subcommands which we will be exploring in this guide.
Get your API key from the Arduino Cloud home page (bottom left corner of the page)
To authenticate with the Arduino Cloud, we will need to first set our credentials, using our
which is obtained from the Arduino Cloud API keys section.
To authenticate, begin with:
1arduino-cloud-cli credentials init
And enter your credentials.
This will create a
file in your Arduino Data directory.
To overwrite, we can use:
1arduino-cloud-cli credentials init --overwrite
It is also possible to use
as format, (default is yaml):
1arduino-cloud-cli credentials init --file-format json
As you may have multiple
existing, you can use the following command to locate the one that is currently being used:
1arduino-cloud-cli credentials find
To configure a device, you can use the following command:
1arduino-cloud-cli device create --name <deviceName> --port <port> --fqbn <deviceFqbn>
Here's follows the FQBN's list of the supported devices:
Arduino Nano 33 IoT
Arduino MKR WiFi 1010
Arduino Nano RP2040 Connect
Arduino Portenta H7 / Arduino Portenta H7 Lite connected / Arduino Portenta Machine Control
Arduino Nicla Vision
Arduino MKR GSM 1400
Arduino MKR NB 1500
To configure LoRaWAN® devices, use the additional
1arduino-cloud-cli device create-lora --name <deviceName> --frequency-plan <freqID> --port <port> --fqbn <deviceFqbn>
LoRaWAN® devices that are supported:
To find out what frequency to use for
flag, you can run:
1arduino-cloud-cli device list-frequency-plans
General devices is a virtual device that does not need to be attached to a physical board.
To see the full list of supported FQBNs (Fully Qualified Board Names), you can run the following command:
1arduino-cloud-cli device list-fqbn
To create a generic device, you can use the following command. Note that the
flag is optional: leaving this blank will set the fqbn to
1arduino-cloud-cli device create-generic --name <deviceName> --fqbn <fqbn>
Devices can be deleted using the device delete command.
This command accepts two mutually exclusive flags:
. Only one of them must be passed. When the
is passed, the device having such ID gets deleted:
1arduino-cloud-cli device delete --id <deviceID>
is passed, the devices having all the specified tags get deleted:
1arduino-cloud-cli device delete --tags <key0>=<value0>,<key1>=<value1>
Devices currently present on Arduino Cloud can be retrieved with:
1arduino-cloud-cli device list
It has an optional
flag that allows to list only the devices having all the provided tags:
1arduino-cloud-cli device list --tags <key0>=<value0>,<key1>=<value1>
Add tags to a device. Tags should be passed as a comma-separated list of
1arduino-cloud-cli device create-tags --id <deviceID> --tags <key0>=<value0>,<key1>=<value1>
Deletes specific tags of a device. The keys of the tags to delete should be passed in a comma-separated list of strings:
1arduino-cloud-cli device delete-tags --id <deviceID> --keys <key0>,<key1>
Things in the Arduino Cloud is the virtual twin of your hardware device. In a Thing, you create variables, attach device and add network credentials.
a template from existing Things, and output in a template file (
a Thing, based on a template.
a Thing. This command simply duplicates a Thing.
a device to a Thing (attach it).
Extract a template from an existing Thing.
The template is printed to stdout and its format depends on the global
1arduino-cloud-cli thing extract --id <thingID> --format <json|yaml>
Create a thing from a thing template.
Supported template formats are JSON and YAML. The name parameter is optional. If it is provided, then it overrides the name retrieved from the template:
1arduino-cloud-cli thing create --name <thingName> --template <template.(json|yaml)>
To clone a Thing (duplicating it), we can use the
command. Note that
is a mandatory flag.
1arduino-cloud-cli thing clone --name <thingName> --clone-id <thingToCloneID>
prints out information regarding your Things. It can be used to e.g. list out a Thing's ID, or list attached variables.
To display all Things with all variables, use:
1arduino-cloud-cli thing list --show-variables
To print a list of specific Things, we can use the
flag followed by the thing IDs, separated by comma.
1arduino-cloud-cli thing list --ids <thingOneID>,<thingTwoID>
Print out the Thing associated with a specific device.
1arduino-cloud-cli thing list --device-id <deviceID>
Print only the things that have all the specified tags:
1arduino-cloud-cli thing list --tags <key0>=<value0>,<key1>=<value1>
Things can be deleted using the thing delete command.
This command accepts two mutually exclusive flags:
. Only one of them must be passed. When the
is passed, the Thing with the matching ID will be deleted.
1arduino-cloud-cli thing delete --id <thingID>
is passed, the Things having all the specified tags get deleted:
1arduino-cloud-cli thing delete --tags <key0>=<value0>,<key1>=<value1>
Binding a device is the same as "attaching" a device to a Thing.
To bind a Thing to an existing device:
1arduino-cloud-cli thing bind --id <thingID> --device-id <deviceID>
Add tags to a Thing. Tags should be passed as a comma-separated list of
1arduino-cloud-cli thing create-tags --id <thingID> --tags <key0>=<value0>,<key1>=<value1>
Delete specific tags of a Thing. The keys of the tags to delete should be passed in a comma-separated list:
1arduino-cloud-cli thing delete-tags --id <thingID> --keys <key0>,<key1>
Dashboards are used to visualize and interact with data from your board. With the
template from a dashboard and output in a template file (
a dashboard from a template file.
Extract a template from an existing dashboard. The template is printed to stdout and its format depends on the global
1arduino-cloud-cli dashboard extract --id <dashboardID> --format <json|yaml>
Print a list of available dashboards and their widgets by using this command:
1arduino-cloud-cli dashboard list --show-widgets
Delete a dashboard with the following command:
1arduino-cloud-cli dashboard delete --id <dashboardID>
Dashboards can only be created from a template. Supported dashboard template formats are
parameter is optional. If it is provided, then it overrides the name retrieved from the template.
flag is used to override the template
placeholder with the actual ID of the Thing to be used.
1arduino-cloud-cli dashboard create2--name <dashboardName>3--template <template.(json|yaml)>4--override <thing-0>=<actualThingID-0>,5<thing-1>=<actualThingID-1>
Note that the
command requires a Thing ID, which is why we need to use the
is the Thing name you have in a template file that you have obtained using "dashboard extract". Note that in the command provided above, you can create a dashboard from more than one Thing.
is the Thing ID, which is something like
OTA (Over-The-Air) is the process of upgrading the firmware remotely.
, you can:
sketches to a board remotely.
sketches to several boards simultaneously, also remotely.
To upload a sketch, you will need to specify the
1arduino-cloud-cli ota upload --device-id <deviceID> --file <sketch-file.ino.bin>
Note that this is not your
file, but a binary file that you will need to generate. You will find instructions further down this document on how to do this.
The default OTA upload should complete in 10 minutes. Use
flag to extend this time up to one week (see an example sketch here):
1arduino-cloud-cli ota upload --device-id <deviceID> --file <sketch-file.ino.bin> --deferred
It is also possible to perform a mass ota upload through a specific command. The fqbn is mandatory.
To upload using a device
1arduino-cloud-cli ota mass-upload --fqbn <deviceFQBN> --device-ids <deviceIDs> --file <sketch-file.ino.bin>
You can also specify by using
(see the Tag a Device section.)
1arduino-cloud-cli ota mass-upload --fqbn <deviceFQBN> --device-tags <key0>=<value0>,<key1>=<value1> --file <sketch-file.ino.bin>
When uploading a sketch using OTA, you will need to compile the binary file (
) first. This is not a feature in the
, so you will need to use the following options:
, you can compile a sketch through the following command:
1arduino-cli compile -b arduino:samd:mkrwifi1010 /home/user/Arduino/MySketch
You can find out your board's FQBN by running
, a command that lists all boards and their corresponding FQBN.
arduino-cli board listall
You can also compile a file through any version of the Arduino IDE (not online).
will appear. The binary needed is located inside of this folder.
file, which is the file we can use to perform OTA.
The Arduino Cloud CLI is a tool that can primarily be used to extract a template from a single Thing or dashboard, and deploy it to several devices. It is also a tool for managing your fleet of devices, such as providing mass OTA uploads (such as firmware updates).
It is intended to be used as a supplementary tool for the Arduino Cloud web interface, but can well be used as a standalone tool to manage your devices, Things properties and dashboards.
The Arduino Cloud CLI can also be well combined with the Arduino CLI, a separate tool that brings the functionality of the Arduino IDE to your choice of terminal.
To recap, this tool can be used to: