Configuration

Configuration keys¶

• board_manager
  • additional_urls - the URLs to any additional Boards Manager package index files needed for your boards platforms.
• daemon - options related to running Arduino CLI as agRPC server.
  • port - TCP port used for gRPC client connections.
• directories - directories used by Arduino CLI.
  • data - directory used to store Boards/Library Manager index files and Boards Manager platform installations.
  • downloads - directory used to stage downloaded archives during Boards/Library Manager installations.
  • user - the equivalent of the Arduino IDE's"sketchbook" directory. Library Manager installations are made to thelibraries subdirectory of the user directory.
• library - configuration options relating to Arduino libraries.
  • enable_unsafe_install - set totrue to enable the use of the--git-url and--zip-file flags witharduino-cli lib install. These are considered "unsafe" installation methods because they allow installing files that have not passed through the Library Manager submission process.
• logging - configuration options for Arduino CLI's logs.
  • file - path to the file where logs will be written.
  • format - output format for the logs. Allowed values aretext orjson.
  • level - messages with this level and above will be logged. Valid levels are:trace,debug,info,warn,error,fatal,panic.
• metrics - settings related to the collection of data used for continued improvement of Arduino CLI.
  • addr - TCP port used for metrics communication.
  • enabled - controls the use of metrics.
• sketch - configuration options relating toArduino sketches.
  • always_export_binaries - set totrue to makearduino-cli compile always save binaries to the sketch folder. This is the equivalent of using the--export-binaries flag.
• updater - configuration options related to Arduino CLI updates
  • enable_notification - set tofalse to disable notifications of new Arduino CLI releases, defaults totrue

Configuration methods¶

Arduino CLI may be configured in three ways:

1. Command line flags
2. Environment variables
3. Configuration file

If a configuration option is configured by multiple methods, the value set by the method highest on the above listoverwrites the ones below it.

If a configuration option is not set, Arduino CLI uses a default value.

arduino-cli config dump displays the current configuration values.

Command line flags¶

Arduino CLI's command line flags are documented in the command line help and theArduino CLI command reference.

Example¶

Setting an additional Boards Manager URL using the--additional-urls command line flag:

$ arduino-cli core update-index --additional-urls https://downloads.arduino.cc/packages/package_staging_index.json

Environment variables¶

All configuration options can be set via environment variables. The variable names start withARDUINO, followed by theconfiguration key names, with each component separated by_. For example, theARDUINO_DIRECTORIES_USER environmentvariable sets thedirectories.user configuration option.

On Linux or macOS, you can use theexport command to set environment variables. On Windows cmd, youcan use theset command.

Example¶

Setting an additional Boards Manager URL using theARDUINO_BOARD_MANAGER_ADDITIONAL_URLS environment variable:

$exportARDUINO_BOARD_MANAGER_ADDITIONAL_URLS=https://downloads.arduino.cc/packages/package_staging_index.json

Configuration file¶

arduino-cli config init creates or updates a configuration file with the currentconfiguration settings.

This allows saving the options set by command line flags or environment variables. For example:

arduino-cli config init --additional-urls https://downloads.arduino.cc/packages/package_staging_index.json

File name¶

The configuration file must be namedarduino-cli, with the appropriate file extension for the file's format.

Supported formats¶

arduino-cli config init creates a YAML file, however a variety of common formats are supported:

• JSON
• TOML
• YAML
• Java properties file
• HCL
• envfile
• INI

Locations¶

Configuration files in the following locations are recognized by Arduino CLI:

1. Location specified by the--config-file command line flag
2. Current working directory
3. Any parent directory of the current working directory (more immediate parents having higher precedence)
4. Arduino CLI data directory (as configured bydirectories.data)

If multiple configuration files are present, the one highest on the above list is used. Configuration files are notcombined.

The location of the active configuration file can be determined by running the command:

arduino-cli config dump --verbose

Example¶

Setting an additional Boards Manager URL using a YAML format configuration file:

board_manager:additional_urls:-https://downloads.arduino.cc/packages/package_staging_index.json

Doing the same using a TOML format file:

[board_manager]additional_urls=[ "https://downloads.arduino.cc/packages/package_staging_index.json" ]