arduino-cliは、Arduinoのスケッチをコンパイルしてマイコンへ書き込むまでをターミナルだけで行う公式ツールです。2026年11月10日に1.6.0が公開され、2日後のArduino IDE 2.3.11も同梱するCLIを1.6.0へ上げました。この記事は1.6.0を手元のmacOSで動かして確かめたコマンドと出力、エラー文を元に、インストールからCI自動化までを順に説明します。
まとめ：arduino-cli 1.6.0の要点
- 最新版：1.6.0（2026-11-10）。Windows on ARM64向けのバイナリが加わった。
arduino-cli versionで手元の版を確認できる。 - 最小の流れ：
core update-index→core install→board listでFQBNを確認 →compile -b→upload -p。 - つまずきやすい点：Linuxの
dialoutグループ、FQBNの綴り、コア未導入のplatform not installed。 - 版の固定：
sketch.yamlのプロファイルにコアとライブラリの版を書けば、別の環境でも同じ版でビルドできる。 - 自動化：機械可読の出力は
--json。GitHub Actionsはsetup-arduino-cliかcompile-sketchesで組む。
arduino-cliとArduino IDEの関係と最新版1.6.0
arduino-cliはGo言語製の単一バイナリ（GPL-3.0）で、GUIが無いためRaspberry PiやCIのランナーでも同じコマンドで動きます。
Arduino IDE 2.xとの関係（同梱・共有・別管理）
Arduino IDE 2.xは内部でarduino-cliを daemon モードで起動して使っています。IDE 2.3.11の package.json は同梱版を "version": "1.6.0" と指定しています。
併用するときに知っておきたいのは、共有されるものと別管理のものの境目です。コアやツールを置くデータディレクトリ（Linuxは ~/.arduino15、macOSは ~/Library/Arduino15、Windowsは AppData\Local\Arduino15）は両者が同じ既定値を使うため、IDEで入れたコアはCLIからも見えます。一方、IDE 2.xは自分用の arduino-cli.yaml をIDEの設定フォルダ（.arduinoIDE）に持ちます。CLIで追加したボードマネージャURLはIDEの設定には反映されないため、IDE側でも同じURLを登録してください。
1.xの版ごとの変更点
1.0.0は2024年6月12日に公開されました。以後のマイナー版で入った変更のうち、日常の作業に効くものを抜き出すと次のとおりです（各版のGitHubリリースノートより）。
| 版 | 公開日 | 主な変更 |
|---|---|---|
| 1.0.0 | 2024-06-12 | 初の1.x安定版 |
| 1.4.0 | 2025-12-09 | profileコマンド群を追加 |
| 1.5.0 | 2026-05-19 | 変更が無ければ前処理を省略 |
| 1.5.1 | 2026-06-05 | 再コンパイル漏れの修正 |
| 1.6.0 | 2026-11-10 | Windows ARM64・GITHUB_TOKEN対応 |
1.6.0のリリースノートには、インデックスURLの末尾がファイル名でなくてもよくなった点や、インストール中の電源断で壊れたファイルを残さない修正も並びます。1.5.1はソースを変えても再コンパイルされない不具合の修正版なので、1.5.0のままの環境は上げておきます。
arduino-cliに向く作業と向かない作業
向くのは、同じビルドや書き込みを繰り返す作業です。複数ボード向けのビルド、量産時の連続書き込み、プルリクエストごとのコンパイル確認は、スクリプトに書いた時点で手作業が消えます。
反対に、ボードを触るのが年に数回の人や、試行錯誤の段階の入門者には勧めません。IDEならボード選択やシリアルプロッタが画面で完結します。CLIは最初にFQBNとポート名を調べて指定する手間があり（後述の board attach で既定値を保存すれば以後は省略できます）、シリアルプロッタに当たる機能はありません。迷ったら、同じ操作を月に何回繰り返すかで決めてください。
arduino-cliのインストール（Windows・macOS・Linux）
公式のインストール手順が案内する方法は、Homebrew、インストールスクリプト、配布バイナリのダウンロードの3つです。
OS別のインストール方法
| OS | 方法 | 補足 |
|---|---|---|
| macOS・Linux | brew install arduino-cli | 補完ファイルも入る |
| macOS・Linux | install.sh | $PWD/binに入る |
| Windows x64 | msi または zip | zipはPATHを自分で追加 |
| Windows ARM64 | zip | 1.6.0から提供 |
| Debian・Ubuntu | .debパッケージ | GitHubリリースに添付 |
2026年11月13日時点で、Homebrewの安定版は1.6.0に更新済みです。インストールスクリプトは既定でカレントディレクトリの bin に入れるので、PATHの通ったディレクトリを BINDIR で指定します。版を固定したいときは引数で渡します。
brew update && brew install arduino-cli
# スクリプト（macOS/Linux、WindowsならGit Bash）
curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | BINDIR=~/.local/bin sh
# 版を指定する場合
curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh -s 1.6.0Windows ARM64版は1.6.0のリリースに arduino-cli_1.6.0_Windows_ARM64.zip として添付されていますが、公式ドキュメントのダウンロード表にはまだ行がありません。https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Windows_ARM64.zip は1.6.0のzipへ転送されることを確認しました。Intel Macで macOS_ARM64 版を展開すると bad CPU type in executable で起動しないので、CPUに合う配布物を選びます。
PATH・dialout権限の設定と動作確認
Windowsでzipを使った場合は、展開したフォルダをユーザー環境変数PATHに追加し、ターミナルを開き直します。開いたままのウィンドウには反映されません。
LinuxやUbuntuで書き込みが permission denied で止まる原因としてまず確かめるのは、シリアルポート（/dev/ttyACM0 など）を所有するグループにユーザーが入っているかです。公式FAQも、ポートのグループにユーザーを追加し、ログアウトしてログインし直す手順を案内しています。グループ名はディストリビューションで違うので ls -l で確かめます（Ubuntu・Debianでは dialout）。
ls -l /dev/ttyACM0 # 例: crw-rw---- 1 root dialout ...
sudo usermod -a -G dialout $USER
# 再ログイン後に確認
groups | grep dialout導入できたかは version で確かめます。1.6.0の表示は次のとおりです。CLIは24時間ごとに新しい版を確認して通知します。CIのログで邪魔になるなら、設定の updater.enable_notification か環境変数 ARDUINO_UPDATER_ENABLE_NOTIFICATION を false にします。
$ arduino-cli version
arduino-cli Version: 1.6.0 Commit: 50a0e80da Date: 2026-11-10T15:31:05Z初期設定とコア・ライブラリの導入
ビルドには、ボードの種類ごとのコア（ボード定義とコンパイラ一式）が要ります。
config initと設定ファイルの場所
arduino-cli config init は、データディレクトリに arduino-cli.yaml を作ります。公式の設定リファレンスによると、設定ファイルは --config-file フラグ、環境変数 ARDUINO_CONFIG_FILE、ARDUINO_DIRECTORIES_DATA の順に探され、複数あっても中身は合成されません。どのファイルが読まれたかは config dump --verbose の Using config file: 行で分かります。
キーはすべて環境変数でも上書きでき、名前は ARDUINO_ にキーを大文字・アンダースコア区切りでつなげます（directories.user なら ARDUINO_DIRECTORIES_USER）。CIで設定ファイルを置かずに済ませたいときに使えます。社内プロキシの内側では network.proxy にプロキシのURLを書きます。
ESP32コアの導入と追加URLの登録
Arduinoの標準インデックス（package_index.json）には、Arduino社のコアに加えてEspressifやSilicon Labsなど他社のコアも収録されています。2026年11月13日に追加URLを登録していない新規環境で試すと、core search esp32 に esp32:esp32 の3.3.12が出ました。Espressifのインストール手順は今もボードマネージャURLの登録を案内しており、開発版（package_esp32_dev_index.json）を使うときは登録が要ります。登録するなら、以前よく使われた raw.githubusercontent.com/espressif/.../gh-pages/ ではなく、現在の公式の案内にある次のURLにします。
arduino-cli core update-index
arduino-cli core search esp32
arduino-cli core install esp32:esp32
# Espressifの案内どおりURLを登録する場合
arduino-cli config add board_manager.additional_urls https://espressif.github.io/arduino-esp32/package_esp32_index.jsoncore search esp32 には、esp32:esp32 の3.3.12と、Arduino社が配布する arduino:esp32 の2.0.18-arduino.5の2つが出ます。Arduino Nano ESP32などArduino社のボードは後者、一般的なESP32開発ボードは前者です。M5Stackは自社のインデックス（https://static-cdn.m5stack.com/resource/arduino/package_m5stack_index.json）で独自コアを配布しており、登録すると m5stack:esp32（2026年11月13日時点で3.3.10・M5Core2やM5CoreS3など52機種）が選べます。M5Stackの機種の違いはM5Stackとは？種類・選び方とできることにまとめています。
初回の core update-index では、serial-discovery や、ネットワーク越しのボードを探す mdns-discovery などの探索ツールが自動で入ります（mDNSの仕組みはmDNSとは？UDP 5353・224.0.0.251の仕組みとDNS-SD）。
FQBNの調べ方とボード検出
FQBN（Fully Qualified Board Name）は、ボードを「パッケージ:アーキテクチャ:ボード」の3つ組で示す名前です。Arduino UNOは arduino:avr:uno、ESP32の汎用開発ボードは esp32:esp32:esp32 です。名前の一部で探すなら board listall が速く、接続中のボードは board list で調べます。
$ arduino-cli board listall uno
Board Name FQBN
Arduino UNO arduino:avr:uno
Arduino UNO Mini arduino:avr:unomini
Arduino UNO WiFi arduino:avr:unowifiboard list がFQBNを表示するのは、探索ツールがポートから読み取った属性（シリアルならUSBのベンダーIDと製品IDなど）が、導入済みコアのボード定義の upload_port.* と一致したボードだけです（公式仕様）。一致しないポートはFQBN欄が空のまま Unknown と表示されるので（手元のMacではBluetoothのシリアルポートがこの表示でした）、汎用のUSBシリアル変換チップを積んだ互換機などは board listall で型番から選びます。
ライブラリの導入と版の指定
ライブラリは lib search で探し、lib install で入れます。名前の後ろに @版 を付けるとその版が入り、入っている版は置き換えられます。
$ arduino-cli lib install [email protected]
Downloading [email protected]...
Installing [email protected]...
Replacing [email protected] with [email protected]...
Installed [email protected]ここで入れた版はユーザーのライブラリフォルダ全体に効くため、プロジェクトAは1.2.1、Bは1.3.0という分け方はできません。プロジェクトごとに版を固定するなら、後述するsketch.yamlのプロファイルを使います。更新が出ているコアとライブラリは arduino-cli outdated で一覧できます。
スケッチのコンパイルと書き込み
compileとuploadの基本構文
arduino-cli core update-index
arduino-cli core install arduino:avr
arduino-cli sketch new Blink
arduino-cli compile -b arduino:avr:uno Blink
arduino-cli upload -p /dev/ttyACM0 -b arduino:avr:uno Blink
# ビルドと書き込みを続けて行う
arduino-cli compile -u -p /dev/ttyACM0 -b arduino:avr:uno BlinkポートはWindowsなら COM3、Linuxなら /dev/ttyACM0 や /dev/ttyUSB0、macOSなら /dev/cu.usbmodem… の形です。sketch new で作った雛形（Blink）をUNO向けにビルドすると、フラッシュ32,256バイト中444バイト、RAMはグローバル変数9バイトと表示されました。手元のIntel Macでは、初回のビルドに9.74秒、ソースを変えずに再実行すると0.85秒でした（コア導入直後・1回ずつの計測）。
-e（--export-binaries）を付けると、スケッチのフォルダの build/arduino.avr.uno/ に .hex・.elf やブートローダー込みの .with_bootloader.hex が出力されます。
board attachによる既定のボード・ポートの記録
毎回 -b と -p を打つのが面倒なら、board attach でスケッチに既定値を記録します。実行するとスケッチのフォルダに sketch.yaml ができ、default_fqbn: arduino:avr:uno が書き込まれました。以後は arduino-cli compile Blink だけでビルドできます。
arduino-cli board attach -b arduino:avr:uno -p /dev/ttyACM0 Blinkmonitorによるシリアル出力の確認
書き込んだボードの出力は monitor で読みます。ボーレートは --config（-c）で渡し、ポートが受け付ける設定項目は --describe で一覧できます。--timestamp を付けると各行に時刻が付くので、ログを保存して後から見比べるときに使えます。
arduino-cli monitor -p /dev/ttyACM0 --config 115200
arduino-cli monitor -p /dev/ttyACM0 --describe
arduino-cli monitor -p /dev/ttyACM0 -c baudrate=115200 --timestampsketch.yamlのプロファイルによる版の固定
版を固定していないと、コアやライブラリの新版が出た時点でCIが別の版を取ってきて、昨日通ったビルドが今日落ちることがあります。arduino-cliには、スケッチごとに使うコアとライブラリの版を sketch.yaml に書く「ビルドプロファイル」があります。公式の仕様では、プロファイルにFQBN、コアの版、ライブラリの版、書き込み先のポートまで書けます。
–dump-profileによる依存バージョンの書き出し
いちばん手早いのは、今の環境でビルドしたときの版をそのまま書き出す方法です。Servoライブラリを使うスケッチで実行すると、コアとライブラリの版がプロファイルの形式で出てきました。
$ arduino-cli compile -b arduino:avr:uno ServoTest --dump-profile
profiles:
uno:
fqbn: arduino:avr:uno
platforms:
- platform: arduino:avr (1.8.8)
libraries:
- Servo (1.2.1)これを sketch.yaml に貼り、末尾に default_profile: uno を足せば、arduino-cli compile ServoTest だけでこの版の組み合わせでビルドされます。プロファイルでビルドすると、ライブラリはユーザーのライブラリフォルダとは別の場所に入り、出力に The library Servo has been added from sketch project. と出ます。ユーザー側に別の版が入っていても影響を受けません。
profileコマンドによるプロファイルの作成（1.4.0以降）
1.4.0からは、YAMLを手で書かずにコマンドでプロファイルを組めます。スケッチのフォルダが先に要るので、sketch new ProfDemo で作ってから（無いと profile create はエラーで終了します）次のコマンドを実行すると、上と同じ内容の sketch.yaml ができました。
arduino-cli sketch new ProfDemo
arduino-cli profile create ProfDemo -m uno -b arduino:avr:uno
arduino-cli profile lib add [email protected] -m uno --sketch-path ProfDemo
arduino-cli profile set-default uno --sketch-path ProfDemo1.6.0の profile --help は使用例に profile init と書いていますが、そのサブコマンドはありません。実行してもヘルプが表示されるだけで、終了コードは0です。スクリプトに組み込んで「成功したのにファイルができない」とならないよう、作成には profile create を使ってください。sketch.yaml はスケッチと一緒にGitへコミットし、コアやライブラリを上げるときはプロファイルの版を書き換えるコミットとして残すのが、版を固定する意味のある運用です。
スクリプトとCIによる自動化
–jsonによる実行結果のJSON出力
1.xの --help に載っているJSON出力のフラグは --json です。古い記事にある --format json は1.6.0でもまだ動きますが、ソースでは隠しフラグ扱い（Hidden = true）になっており、ヘルプには出ません。新しく書くスクリプトは --json にそろえてください。
$ arduino-cli compile -b arduino:avr:uno Blink --json | jq '.builder_result.executable_sections_size'
[
{ "name": "text", "size": 444, "max_size": 32256 },
{ "name": "data", "size": 9, "max_size": 2048 }
]compileのJSONには success、compiler_out、compiler_err、builder_result、upload_result が入ります。フラッシュ使用量を毎回記録すれば、ライブラリ更新でサイズが急に増えたことに気づけます。このほか arduino-cli daemon で起動するとgRPCのAPIを公開し、Arduino IDE 2.xもこの方式でCLIを使っています。
GitHub Actionsのワークフロー例
公式アクション arduino/setup-arduino-cli の最新は2024年7月のv2.0.0で、version の既定値は 1.x です。プッシュのたびにコンパイルが通るかを確かめる最小構成は次のとおりです。GITHUB_TOKEN を環境変数に渡すと、1.6.0はGitHubからのダウンロードにこのトークンを使い、ダウンロード回数の制限にかかりにくくなります。
name: arduino-build
on: [push, pull_request]
jobs:
compile:
runs-on: ubuntu-latest
strategy:
matrix:
fqbn: [arduino:avr:uno, esp32:esp32:esp32]
env:
FQBN: ${{ matrix.fqbn }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
ARDUINO_UPDATER_ENABLE_NOTIFICATION: "false"
steps:
- uses: actions/checkout@v7
- uses: arduino/setup-arduino-cli@v2
with:
version: "1.6.0"
- uses: actions/cache@v6
with:
path: ~/.arduino15
key: arduino15-${{ matrix.fqbn }}-${{ hashFiles('**/sketch.yaml') }}
- run: |
arduino-cli core update-index
arduino-cli core install "${FQBN%:*}"
- run: arduino-cli compile -b "$FQBN" ./MySketch${FQBN%:*} はFQBNの末尾のボード名を落として esp32:esp32 のようなコア名にするシェルの書き方です。esp32:esp32 は標準インデックスにあるので追加URLは不要です。M5Stackのように追加URLが要るコアは、設定ファイルを作らず環境変数 ARDUINO_BOARD_MANAGER_ADDITIONAL_URLS で渡します。キャッシュから ~/.arduino15 を戻した後に config init を実行すると、Config file already exists で終了コード1になるためです。setup-arduino-cliの version を省くと既定の 1.x で最新の1.x系が入るので、記事と同じ条件にするなら上のように固定します。
注意点が1つあります。setup-arduino-cli v2.0.0の action.yml は using: "node20" のままで、2024年11月を最後に更新されていません。GitHubは2026年9月23日の告知で、ランナーからNode 20を外し、JavaScriptアクションはNode 24で動かすと発表しました。このアクションはGitHub側の切り替えに頼って動いている状態です。ワークフローで警告やエラーが出たら、上のインストールスクリプトを run で直接実行するか、コンポジットアクションの arduino/compile-sketches（v1.1.4・2026-11-11）へ切り替えます。compile-sketchesは fqbn・platforms・libraries・sketch-paths を入力に取り、プルリクエストでのフラッシュ使用量の増減を報告する enable-deltas-report も備えています。CI全般の組み方はGitHub Actionsでビルド・自動テストを設定する方法で、組み込み機器のビルド・書き込みを含むパイプラインの設計を任せたい場合はDevOps・CI/CD導入支援で相談を受けています。
よくあるエラーと対処（1.6.0の実際のエラー文）
以下は1.6.0で実際に出したエラー文です（日本語環境でも英語のまま出ました）。
Platform ‘arduino:avr’ not found: platform not installed
Error during build: Platform 'arduino:avr' not found: platform not installed
Try running `arduino-cli core install arduino:avr`FQBNは正しいのに、そのコアが入っていない状態です。表示どおり core install で解消します。M5Stackの独自コアのように標準インデックスに無いコアは、URLを登録して core update-index を実行するまで core install も見つからずに失敗します。順番は、URL登録、インデックス更新、コア導入です。
Invalid FQBN: board not found
Error during build: Invalid FQBN: board arduino:avr:unoo not foundコアは入っているのに、ボード名の部分が違うときのエラーです。board listall で正しい綴りを確かめます。パッケージ名とアーキテクチャ名まで間違えている場合は、上の platform not installed として出るので、2つの文言で「コア不足」か「綴り違い」かを見分けられます。
no upload port provided・permission denied
Failed uploading: no upload port provided-p を付け忘れたときの表示です。board attach で既定のポートを記録しておけば省略できます。ポートを指定しても弾かれる場合は、充電専用でないUSBケーブルか、board list にポートが出ているか、Linuxなら dialout に入っているか、の順に確かめます。
ライブラリのヘッダーが見つからない・ダウンロードが失敗する
fatal error: Xxx.h: No such file or directory は、ライブラリが入っていない、#include のヘッダー名やパスが違う、プロファイルでビルドしているのに libraries に書き忘れている、などで起きます。プロファイルを使っている場合は、ユーザーのフォルダに入っているライブラリは参照されません。ダウンロードで止まるときはプロキシ（network.proxy）を設定し、原因が分からなければ --log-level debug でどの段階で止まったかを出力させます。
よくある質問
arduino-cliとArduino IDEは併用できますか？
できます。コアは共有され、追加のボードマネージャURLだけは両方に登録が要ります（理由は「Arduino IDE 2.xとの関係」の節）。
最新バージョンの確認と更新はどうしますか？
手元の版は arduino-cli version、最新版はGitHubのリリース一覧で確認します（2026年11月13日時点は1.6.0）。CLI本体はHomebrewなら brew upgrade arduino-cli、スクリプトやzipなら新しいバイナリへの置き換えで更新します。arduino-cli update はコアとライブラリのインデックスの更新、arduino-cli upgrade は導入済みのコアとライブラリの更新で、どちらもCLI本体は更新しません。
公式ドキュメントのURLが0.35になっているのはなぜですか？
検索結果に出る arduino.github.io/arduino-cli/0.35/ は1.0より前の版の文書で、最新は /latest/ です。ただし2026年11月13日時点の /latest/ は1.5の文書で、1.6.0で加わったWindows ARM64版もダウンロード表にはまだありません。
Arduino Pro CLIは別の製品ですか？
別製品ではありません。arduino.ccのPro向けページが紹介しているのは同じarduino-cliで、製品に組み込む企業向けに商用ライセンスの問い合わせ窓口がある点だけが加わります。
VS Codeと組み合わせて使えますか？
使えます。tasks.json に arduino-cli compile と upload を登録すればショートカットでビルドと書き込みができます。補完は、IDE 2.xの補完を担うarduino-language-serverが、Language Server Protocol対応のエディタならIDEの外でも使えるとREADMEで案内されています。
