The Arduino Cloud CLI is a tool developed to access features of the Arduino Cloud service from the terminal.
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:
device create
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:
1arduino-cloud-cli
The Arduino Cloud CLI has 5 main commands.
credentials
- credentials specific commands.dashboard
- dashboard specific commands.device
- device specific commandsota
- Over The Air uploads.thing
- Thing specific commands.Each command has a set of subcommands which we will be exploring in this guide.
arduino-cloud-cli credentials
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
clientId
and clientSecret
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
arduino-cloud-credentials.yaml
file in your Arduino Data directory. To overwrite, we can use:
1arduino-cloud-cli credentials init --overwrite
It is also possible to use
.json
as format, (default is yaml):1arduino-cloud-cli credentials init --file-format json
As you may have multiple
arduino-cloud-credentials.yaml
existing, you can use the following command to locate the one that is currently being used:1arduino-cloud-cli credentials find
arduino-cloud-cli device
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:samd:nano_33_iot
Arduino Nano 33 IoTarduino:samd:mkrwifi1010
Arduino MKR WiFi 1010arduino:mbed_nano:nanorp2040connect
Arduino Nano RP2040 Connectarduino:mbed_portenta:envie_m7
Arduino Portenta H7 / Arduino Portenta H7 Lite connected / Arduino Portenta Machine Controlarduino:mbed_nicla:nicla_vision
Arduino Nicla Visionarduino:samd:mkr1000
Arduino MKR1000arduino:samd:mkrgsm1400
Arduino MKR GSM 1400arduino:samd:mkrnb1500
Arduino MKR NB 1500 To configure LoRaWANĀ® devices, use the additional
create-lora
and the --frequency-plan
flag. This 1arduino-cloud-cli device create-lora --name <deviceName> --frequency-plan <freqID> --port <port> --fqbn <deviceFqbn>
LoRaWANĀ® devices that are supported:
arduino:samd:mkrwan1310
arduino:samd:mkrwan1300
To find out what frequency to use for
--frequency-plan
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
--fqbn
flag is optional: leaving this blank will set the fqbn to generic:generic:generic
. 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:
--id
and --tags
. Only one of them must be passed. When the --id
is passed, the device having such ID gets deleted:1arduino-cloud-cli device delete --id <deviceID>
When
--tags
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
--tags
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
<key>=<value>
items: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>
arduino-cloud-cli things
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.
With
arduino-cloud-cli
you can:extract
a template from existing Things, and output in a template file (.yaml
). create
a Thing, based on a template.clone
a Thing. This command simply duplicates a Thing.bind
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
--format
flag: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
clone
command. Note that --name
is a mandatory flag. 1arduino-cloud-cli thing clone --name <thingName> --clone-id <thingToCloneID>
The
thing list
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
--ids
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:
--id
and --tags
. Only one of them must be passed. When the --id
is passed, the Thing with the matching ID will be deleted.1arduino-cloud-cli thing delete --id <thingID>
When
--tags
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
<key>=<value>
items: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>
arduino-cloud-cli dashboard
Dashboards are used to visualize and interact with data from your board. With the
arduino-cloud-cli
you can:extract
template from a dashboard and output in a template file (.yaml
). create
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
--format
flag: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
.json
and .yaml
. The --name
parameter is optional. If it is provided, then it overrides the name retrieved from the template. The
--override
flag is used to override the template thing_id
placeholder with the actual ID of the Thing to be used.1arduino-cloud-cli dashboard create 2--name <dashboardName> 3--template <template.(json|yaml)> 4--override <thing-0>=<actualThingID-0>,5<thing-1>=<actualThingID-1>
Note that the
dashboard create
command requires a Thing ID, which is why we need to use the --override
option. <thing-0>
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.<actualThingID-0>
is the Thing ID, which is something like 8121w624-9d23-425f-6420-13e46214917b
arduino-cloud-cli ota
OTA (Over-The-Air) is the process of upgrading the firmware remotely.
With the
arduino-cloud-cli
, you can:upload
sketches to a board remotely. mass-upload
sketches to several boards simultaneously, also remotely.--deferred
flag.To upload a sketch, you will need to specify the
--device-id
and --file
. 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..ino
The default OTA upload should complete in 10 minutes. Use
--deferred
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
device-tags
(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 (
.bin
) first. This is not a feature in the arduino-cloud-cli
, so you will need to use the following options:Using
arduino-cli
, 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).
build
will appear. The binary needed is located inside of this folder.<sketchname>.bin
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:
thing list
).--tags <key0>=<value0>
command.