arduino-cliとは？インストールからコンパイル・書き込み・CI自動化まで実践ガイド

arduino-cliは、スケッチのコンパイルからマイコンへの書き込みまでをコマンドラインだけで完結させるArduino公式のツールです。Go言語製の単一バイナリで、GUIを持たないためサーバーやCI環境でも動きます。2024年9月に安定版の1.0が出て以降はAPIが固定され、本記事執筆時点の最新は1.5.1（2026年6月）です。ここではarduino-cliの位置づけから、OS別インストール、FQBN指定、compile／upload、ESP32コアの追加、GitHub ActionsでのCI自動化までを実コマンド付きで解説します。

まとめ：arduino-cliの要点

• 正体：Arduino IDEと同じコアを共有する公式のCLI。最新は1.5.1（1.x系はAPI安定）。arduino-cli version で確認できる。
• 使いどころ：複数台への一括書き込み、CI/CDでの自動ビルド、ヘッドレス環境。単発・入門用途ならIDEのままで十分。
• 最小の流れ：config init → core install → board list でFQBN確認 → compile --fqbn → upload -p。
• つまずきどころ：Linuxのdialoutグループ、WindowsのPATH、FQBN綴り間違いによる platform not installed。
• 自動化：--format json でスクリプト連携、arduino/setup-arduino-cli@v2 でGitHub Actionsに組み込む。

arduino-cliとは｜Arduino IDEとの違いと使いどころ

arduino-cliは、Arduino IDEが内部で行うコンパイル・書き込み処理をターミナルから直接呼び出すためのツールです。IDEとコア（ビルドエンジン）を共有するため、同じスケッチ・同じFQBNなら生成されるバイナリは一致します。違いは操作方法と、自動化への向き不向きにあります。

arduino-cliの定義と最新バージョン（1.x系）

arduino-cliはArduino社が開発するGPL-3.0のオープンソースで、数十MBの単一実行ファイルとして配布されます。常駐プロセスを持たず、必要なときにコマンドを叩く方式なので、Raspberry Piのような省リソース環境やクラウドVMでも動きます。2024年9月に1.0.0が出てAPIが固定され、以降はセマンティックバージョニングで更新されています（執筆時点の最新は1.5.1）。注意したいのは公式ドキュメントのURLがバージョン別に分かれている点で、検索で古い /0.35/ のページに当たることがあります。コマンド仕様を確認するときは /latest/ か現行バージョンのパスを見てください。

Arduino IDEとの機能差と使い分け

両者はコア機能を共有するため優劣ではなく役割で選びます。感覚で判断せず、下の観点で自分の作業に当てはめてください。

導入すべき開発者と見送るべきケース

arduino-cliが効くのは、同じ書き込み作業を月に何度も繰り返す人です。製造ラインでの一括書き込み、UnoとESP32など複数基板向けのビルド、push契機の自動コンパイルを回すチームなら、導入効果は明確に出ます。VSCodeなど好みのエディタと組み合わせたい場合にも向きます。

逆に、マイコンを触るのが年に数回のライトユーザーや、ターミナル操作に不慣れな入門者は、無理に乗り換えるべきではありません。ボード選択やエラー表示を視覚的に確認できるIDEのほうが学習効率が高く、教育現場でも初学者にはIDEを残す判断が合理的です。反復・自動化の必要がないのにコマンドを覚えるのは、学習コストだけ払って恩恵が薄い典型パターンになります。判断に迷ったら「同じ作業を月に何回繰り返すか」を数え、多いほどCLI化の価値が高い、と考えてください。

arduino-cliのインストール（Windows・macOS・Linux）

arduino-cliは主要3OSに対応し、推奨の入れ方が環境で変わります。導入後にPATHが通っていないと「コマンドが見つからない」で止まるため、入れ方と確認をセットで押さえます。

OS別インストール手順

macOS・LinuxはHomebrewかスクリプトの一行で完了します。スクリプト方式はインストール先フォルダを選べるため、バージョンを固定・共存させたいチーム運用に向きます。

brew install arduino-cli
# または（macOS/Linux/Git Bash）
curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh

PATH・dialout権限のつまずきと動作確認

WindowsではZIP展開後、実行ファイルを置いたフォルダをシステム環境変数PATHに追加し、ターミナルを開き直します。既存ウィンドウのままだと反映されません。書き込みで弾かれるのを避けるため、管理者権限が要る場所ではなくユーザー領域のフォルダに置くのが安全です。

Linuxで最も多い書き込み失敗は権限不足です。一般ユーザーが dialout グループに入っていないとシリアルポートへ書き込めません。次のように追加し、いったんログアウト・再ログインして反映させます。

sudo usermod -a -G dialout $USER   # 反映には再ログインが必要

導入直後は以下の3コマンドで確認します。特に board list は接続・ドライバ・権限をまとめて点検できます。

arduino-cli version      # バージョン表示（導入成功の確認）
arduino-cli help         # 利用可能なコマンド一覧
arduino-cli board list   # 接続中の基板とポート

初期設定とボード・ライブラリ管理

実用段階に入るには、設定ファイルの生成と、扱う基板コア・ライブラリの管理を押さえます。ここで環境を固めておくと、後のコンパイルとCI化が安定します。

config initとESP32など外部コアの追加

最初に arduino-cli config init を実行すると、YAML形式の設定ファイル（Linuxなら ~/.arduino15/arduino-cli.yaml）が生成されます。基板コアの追加URL、プロキシ、ログレベル、データ保存先などが1ファイルにまとまり、これをリポジトリで共有すればチーム全員が同じ条件で作業できます。

標準ではArduino純正コアしか入りません。ESP32やESP8266を扱うにはメーカー公式のボード定義URLを追加し、インデックスを更新してからコアを入れます。ESP32の公式URLは次のとおりです。

arduino-cli config set board_manager.additional_urls https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
arduino-cli core update-index
arduino-cli core install esp32:esp32
arduino-cli core list      # 導入済みコアの確認

ESP32基板の実例やハードウェア仕様はESP32を基盤としたM5Stack Core2のハードウェア仕様も参考になります。

FQBNの特定とボード検出

コンパイル・書き込みには、対象基板を一意に示すFQBN（Fully Qualified Board Name）が必須です。FQBNは「コア:アーキテクチャ:ボード」の形式で、Arduino Unoなら arduino:avr:uno、ESP32開発ボードなら esp32:esp32:esp32 のようになります。接続中の基板は board list、コアが対応する全FQBNは board listall で調べられます。

arduino-cli board list        # 接続基板とポート・推定FQBN
arduino-cli board listall     # 導入コアが対応する全FQBN

ライブラリ導入とバージョン固定

ライブラリも lib search で探し lib install で入れます。実務で重要なのはバージョン固定です。最新版を無条件に使うと、更新でビルドが突然壊れることがあります。名前のあとに @ で版を指定し、使用ライブラリと版をリポジトリに記録しておけば、誰がいつ環境を作っても同じ結果になります。

arduino-cli lib search servo
arduino-cli lib install "[email protected]"    # 版を固定して導入
arduino-cli lib list                      # 導入済みライブラリ確認

スケッチのコンパイルと書き込み

ここがarduino-cliの中核です。FQBNとスケッチフォルダを指定してビルドし、ポートを指定して書き込みます。

compileとuploadの基本構文

compile はFQBNとスケッチフォルダが最低限必要で、FQBNを省くとエラーになります。upload はこれに加えてポート指定（-p）が要ります。ポート名はWindowsが COM3、Linuxが /dev/ttyACM0 や /dev/ttyUSB0 の形式です。compile に -u を付ければ、コンパイル成功後にそのまま書き込みまで一括実行できます。

arduino-cli compile --fqbn arduino:avr:uno ./MySketch
arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:avr:uno ./MySketch
# コンパイル＋書き込みを一括
arduino-cli compile -u -p /dev/ttyACM0 --fqbn arduino:avr:uno ./MySketch

コンパイルが通ると使用フラッシュ・RAM容量が表示され、基板に収まるか把握できます。ビルドキャッシュにより2回目以降は変更のない部分の再コンパイルを省けるので、修正と書き込みを繰り返す試作では体感速度が上がります。

sketch newとmonitorで回す開発サイクル

新規スケッチは sketch new で雛形フォルダごと生成できます。書き込み後の動作確認は monitor で、基板からのシリアル出力をターミナルで読めます。ボーレートは -c baudrate= で指定します。「新規作成→編集→compile -u→monitor」の一連をスクリプト化すれば、立ち上げから検証までを1コマンドに畳めます。

arduino-cli sketch new MySketch
arduino-cli monitor -p /dev/ttyACM0 -c baudrate=115200

よく使うコマンド早見表と自動化オプション

コマンドは操作対象ごとにサブコマンドが分かれます。基板を扱う board、コアを扱う core、ライブラリを扱う lib が三本柱です。

主要コマンド早見表

各サブコマンドの後ろに -h を付ければオプションが確認でき、arduino-cli completion でbash・zsh・fish向けの補完スクリプトを生成すればタブ補完も効きます。暗記に頼らず作業を進められます。

JSON出力とdaemonモード

多くのコマンドは --format json で機械可読な出力に切り替わります。テキストを正規表現で解析すると表示変更で壊れますが、JSONならキー名で値を確実に取り出せるため、自動化スクリプトが安定します。例えば board list --format json で全ポートを抽出し、順に書き込む処理が堅牢に書けます。

arduino-cli board list --format json

さらに arduino-cli daemon で常駐サーバーとして起動すると、gRPC経由で外部プログラムから機能を呼べます。Arduino IDE 2.x自体もこのdaemonを内部利用しており、独自の書き込み管理ツールやWebサービスへ組み込みたい場合の基盤になります。組み込み開発をGo言語で行うならTinyGoとは何か？Go言語を組み込み/IoT開発向けに活用できる小型コンパイラとその魅力に迫る！も選択肢に入ります。

GitHub ActionsでのCI/CD自動化

arduino-cliはコマンドで完結するためCIと相性が良く、push契機で自動コンパイルを回せます。GitHub Actions全般の組み方はGitHub Actionsでビルド・自動テストを設定する方法も併せて確認してください。

setup-arduino-cliを使うワークフロー

公式アクション arduino/setup-arduino-cli（最新v2.0.0）でバイナリを用意し、コアを入れてコンパイルする最小構成が次です。コンパイル失敗はワークフロー失敗として記録され、壊れたコードがメインブランチへ入る前に検知できます。

name: Arduino Build
on: [push]
jobs:
  compile:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: arduino/setup-arduino-cli@v2
      - run: |
          arduino-cli core update-index
          arduino-cli core install arduino:avr
      - run: arduino-cli compile --fqbn arduino:avr:uno ./MySketch

複数ボードのマトリクスとキャッシュ

1つのスケッチを複数基板で検証するなら、strategy.matrix にFQBNを並べて並行ビルドします。基板ごとにジョブが分かれるため、どの基板で失敗したか一目で分かります。判断基準はプロジェクトが何種類の基板をサポートすると宣言しているかで、単一基板ならマトリクスは不要です。

CIでの典型的な失敗は、実行のたびにコアやライブラリを再ダウンロードして準備に数分かかることです。GitHub Actionsのキャッシュ機能でコア・ライブラリの保存先を保持し、キャッシュキーをコアのバージョンと連動させれば、更新時だけ取り直す運用にできます。ビルドが遅いと感じたら、まずキャッシュ設定の有無を疑ってください。加えて本体・コア・ライブラリの版をすべて固定すれば、「昨日通ったビルドが今日落ちる」を防げます。

よくあるエラーと解決策

使い込むと出会うエラーは、原因が数パターンに集約されます。切り分けの順序を持っておくと自力で解決できます。

platform not installedの原因と解決

「platform not installed」は、指定FQBNに対応するコアが未導入か、FQBNの綴り間違いが原因です。まず board listall でFQBNの正しさを確認し、未導入ならインデックス更新→コア導入の順で解消します。サードパーティ基板は、コア導入の前にボードマネージャの追加URL登録が必要です。

arduino-cli board listall
arduino-cli core update-index
arduino-cli core install esp32:esp32

ポート認識不可・書き込み権限

基板が board list に出ない、または書き込みで permission denied が出る場合は、物理接続→ドライバ→権限の順に切り分けます。まず充電専用でないケーブルか・別ポートで認識するかを確認し、次にWindowsではUSBシリアル変換チップのドライバ有無を確認します。Linux・macOSでドライバは正常なのに弾かれるなら権限不足が濃厚で、dialout グループへの追加で解消します。複数基板を同時に挿すとポートが紛らわしいので、1台ずつ挿して対応を確かめてください。

ライブラリ不足・プロキシ・ログでの切り分け

「No such file or directory」でヘッダーが見つからないのは、必要ライブラリの未導入か依存ライブラリの取りこぼしが典型です。エラーのヘッダー名から lib search／lib install で補います。社内ネットワークでダウンロードが失敗するときは、設定ファイルか環境変数にプロキシを登録すれば通ります。原因がつかめないときは --verbose や --log-level debug で内部動作を出し、どの段階で止まっているかを追うのが近道です。

arduino-cli compile --fqbn arduino:avr:uno ./MySketch --log-level debug

よくある質問

Arduino IDEが起動しないとき、arduino-cliで代替できますか？

できます。arduino-cliはIDEと同じコアを使うため、IDEが起動しなくても compile／upload でビルドと書き込みを続けられます。設定ファイルとインストール済みコアはIDEと共有されるので、環境を作り直す必要もありません。

WindowsでもLinuxと同じコマンドで使えますか？

コマンド体系は共通です。違うのはポート表記（Windowsは COM3、Linuxは /dev/ttyACM0 など）と、PATH追加の方法だけです。基本の compile／upload／board list はどのOSでも同じに動きます。

FQBNが分からないときはどう調べますか？

接続中の基板は arduino-cli board list で推定FQBNごと表示されます。自動検出されない基板は arduino-cli board listall で導入済みコアが対応する全FQBNを一覧し、手元の型番と突き合わせて選びます。

arduino-cliとArduino IDEは併用できますか？

併用できます。両者は設定ファイルとコアを共有するため、日常の試作はIDEで、量産やCIはarduino-cliで、と工程ごとに使い分けても二重管理になりません。ビルド結果も一致します。

最新バージョンの確認と更新はどうしますか？

導入済みの版は arduino-cli version で確認できます。最新版はGitHubのリリースページで公開され（執筆時点は1.5.1）、Homebrew導入なら brew upgrade arduino-cli、スクリプト・ZIP導入なら新しい実行ファイルへの置き換えで更新します。

関連記事

• GitHub Actionsでビルド・自動テストを設定する方法｜CI/CDワークフローの作り方
• ESP32を基盤としたM5Stack Core2のハードウェア仕様
• TinyGoとは何か？Go言語を組み込み/IoT開発向けに活用できる小型コンパイラとその魅力に迫る！