Arduino Cloud CLI

Get started with the Arduino Cloud CLI, a tool for the automation and mass-deployment of devices.

AUTHOR: Karl Söderby, Paolo Calao

LAST REVISION: 12/05/2023, 02:33 PM

Introduction

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:

Clone existing Things & Dashboards (by extracting its template).
Perform mass OTA uploads.
Create devices, things, variables & dashboards directly via the CLI.

What is the Arduino Cloud CLI?

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:

Create your application using the Arduino Cloud web interface. Here you can configure your device, create variables, enter network credentials, edit your sketch and deploy your first project.
With the Arduino Cloud CLI, extract templates of Things and dashboards you want to replicate.
Provision a device with the
```
device create
```
command and setup a Thing and dashboard using the templates previously extracted.
Download the sketch related to the Thing you extracted, and upload it to the device you created. This can also be done via the Arduino Cloud.
Whenever an update is required for a fleet of devices, you can use the OTA mass-upload tool to update all of your devices at once, without being connected to your computer.

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.

Requirements

*This is needed only for certain commands, like OTA uploads.

Installation

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

Overview

The Arduino Cloud CLI has 5 main commands.

```
credentials
```
- credentials specific commands.
```
dashboard
```
- dashboard specific commands.
```
device
```
- device specific commands
```
ota
```
- Over The Air uploads.
```
thing
```
- Thing specific commands.

Each command has a set of subcommands which we will be exploring in this guide.

Credentials

```
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

Device

```
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 IoT
```
arduino:samd:mkrwifi1010
```
Arduino MKR WiFi 1010
```
arduino:mbed_nano:nanorp2040connect
```
Arduino Nano RP2040 Connect
```
arduino:mbed_portenta:envie_m7
```
Arduino Portenta H7 / Arduino Portenta H7 Lite connected / Arduino Portenta Machine Control
```
arduino:mbed_nicla:nicla_vision
```
Arduino Nicla Vision
```
arduino:samd:mkr1000
```
Arduino MKR1000
```
arduino:samd:mkrgsm1400
```
Arduino MKR GSM 1400
```
arduino:samd:mkrnb1500
```
Arduino MKR NB 1500

LoRaWAN® Devices

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

Generic Devices (ESP32 / ESP8266)

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>

Delete a Device

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>

List Devices

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>

Tag Device

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>

Untag Device

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

```
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 Thing Template

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 Things

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)>

Clone Things

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>

List Things

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>

Delete Things

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>

Bind Thing to Device

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>

Tag a Thing

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>

Untag a Thing

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>

Dashboard

```
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 Dashboard Template

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>

List Dashboards

Print a list of available dashboards and their widgets by using this command:

1arduino-cloud-cli dashboard list --show-widgets

Delete Dashboards

Delete a dashboard with the following command:

1arduino-cloud-cli dashboard delete --id <dashboardID>

Create Dashboard

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

OTA (Over-The-Air)

```
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.
Schedule a preferred time (up to one week in advance) for an upload to happen, by using the
```
--deferred
```
flag.

Upload

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

.ino

file, but a binary file that you will need to generate. You will find instructions further down this document on how to do this.

Deferred Upload

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

Mass Upload

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>

Compile Sketches (.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:

Compile with Arduino CLI

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

arduino-cli board listall

, a command that lists all boards and their corresponding FQBN.

Compile with Arduino IDE

You can also compile a file through any version of the Arduino IDE (not online).

In the IDE, with your sketch open, navigate to Sketch > Export Compiled Binary. In your sketch folder, a new folder called
```
build
```
will appear. The binary needed is located inside of this folder.
To navigate to your sketch folder, navigate to Sketch > Show Sketch Folder. You will see the
```
<sketchname>.bin
```
file, which is the file we can use to perform OTA.

Summary

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:

Extract templates from your existing Things & dashboards previously created in the Arduino Cloud.
Perform the same actions as the Arduino Cloud but from a terminal (like creating/deleting devices, Things and linking them).
List all available components from the cloud (like
```
thing list
```
).
Tag your devices & Things with the
```
--tags <key0>=<value0>
```
command.

Contribute to Arduino

Join the community and suggest improvements to this article via GitHub. Make sure to read out contribution policy before making your pull request.

CONTRIBUTE

Missing something?

Check out our store and get what you need to follow this tutorial.

VISIT OUR STORE

Suggest Changes

The content on docs.arduino.cc is facilitated through a public GitHub repository. You can read more on how to contribute in the contribution policy.

EDIT THIS PAGE