はじめに (対象読者・この記事でわかること)

この記事は、ArduinoをCLI（コマンドラインインターフェース）で開発したいと考えているmacOSユーザーを対象にしています。特に、Arduino IDE 2.0に同梱された「arduino-cli」コマンドをHomebrewや公式スクリプトで導入しても「command not found」や「Permission denied」に悩まされている方に最適です。

この記事を読むことで、macOS特有のセキュリティ制限（Gatekeeper／XProtect）を回避しながら、Arduino CLIを正しいパスにインストールする方法がわかります。また、ボード定義の追加、スケッチのアップロード、ライブラリ管理まで一貫してターミナルだけで行えるようになります。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。 - macOSのターミナル（zsh）の基本的な操作（cd, ls, chmodなど） - Arduinoのスケッチ（.inoファイル）の基礎知識 - Homebrewのインストールと使い方（brewコマンド）

Arduino CLIとは？なぜGUIではなくCLIを使うのか

Arduino CLIは、Arduino IDEの裏側で動いていた「ビルド・ボード管理・ライブラリ解決」をターミナルだけで完結させる公式ツールです。GUI版IDEと完全に互換であり、ビルド結果も同一です。

CI/CD（GitHub Actionsなど）で自動ビルド・自動テストを回したい、複数のボードに対して同時にファームウェアを書き込みたい、VS Codeの統合ターミナルからワンコマンドで烧き込みたい、といった要求に応えます。GUIを起動するよりも明らかに高速で、Raspberry Piなどのリモート環境でも動作します。

macOSでArduino CLIを導入する際の正しい手順とハマりどころ

ステップ1：Homebrewでインストールする際の注意点

多くの記事では以下のように紹介されていますが、これだけでは不十分です。

Bash

brew install arduino-cli

このコマンドでインストールすると、arduino-cliは/opt/homebrew/bin（Apple Siliconの場合）または/usr/local/bin（Intel Macの場合）に配置されますが、初回起動時にボード定義ファイルのダウンロードが失敗するケースが多発します。理由は、macOSの保護機構「Gatekeeper」がダウンロードした実行ファイルを検証し、署名がないと判断してネットワークアクセスをブロックするためです。

正しい手順は、インストール後に明示的に実行許可を与えることです。

Bash

brew install arduino-cli
xattr -dr com.apple.quarantine $(which arduino-cli)

これで、Gatekeeperの検証対象から外れ、ボードマネージャが正常に動作します。

ステップ2：コアとボード定義を追加する

GUI IDEと同様、CLIでも利用したいボードのコアを追加する必要があります。例えばESP32を使う場合：

Bash

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

ここで「Error downloading index」と表示される場合、ほぼ100％プロキシ・社内ネットワークの証明書問題です。macOSのキーチェーンに入っている自社ルートCAを信頼させるには、以下の環境変数を追加します。

Bash

export ARDUINO_CLI_CERTIFICATE=/Library/Keychains/System.keychain

ステップ3：スケッチをコンパイル＆アップロードする

適当なディレクトリにBlink.inoを作成し、

Bash

arduino-cli compile --fqbn esp32:esp32:esp32 Blink
arduino-cli upload -p /dev/cu.SLAB_USBtoUART --fqbn esp32:esp32:esp32 Blink

この時点で「Permission denied」が出る場合、カーネル拡張（kext）またはシリアルドライバの署名が原因です。Silicon Labs CP210xやFTDIの公式ドライバを再インストールし、macOSの「セキュリティとプライバシー」画面で「許可」ボタンを押すことを忘れないでください。

ハマった点やエラー解決

エラー1：zsh: command not found: arduino-cli

原因
Homebrewでインストールしたにもかかわらずパスが通っていない。特にM1/M2 Macでは/opt/homebrew/binがデフォルトPATHに含まれていない。

解決策
~/.zshrcに以下を追加して再ログイン。

Bash

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

エラー2：Error: unknown command "core" for "arduino-cli"

原因
2022年頃にサブコマンド体系が刷新された古い記事を参考にしてarduino-cli coreを打っているが、brewで入ったバージョンが古い。

解決策
brewで最新版に更新。

Bash

brew upgrade arduino-cli

エラー3：アップロード時にesptool.pyが見つからない

原因
ESP32コアに付属するesptoolが~/Library/Arduino15/packages/以下にダウンロードされるが、パーミッションが600になっており実行できない。

解決策
パーミッションを一括で修正。

Bash

chmod -R 755 ~/Library/Arduino15/packages/esp32/tools/esptool*

まとめ

本記事では、macOSでArduino CLIを使う際に遭遇する「Gatekeeper」「PATH」「パーミッション」「証明書」という4つの壁を突破する方法を解説しました。

  • インストール後にxattr -dr com.apple.quarantineでGatekeeperを回避
  • Apple Siliconでは/opt/homebrew/binをPATHに追加
  • 社内プロキシ環境ではARDUINO_CLI_CERTIFICATEでキーチェーンを参照
  • ボードアップデート後にchmodで実行権限を復活

この記事を通して、ターミナルだけでArduinoスケッチのビルド・烧き込み・ライブラリ管理が完結できるようになり、CI/CDやリモート開発の選択肢が広がりました。

次回は、VS Codeのタスク連携とGitHub Actionsで複数ボード向けに並列ビルドする方法を紹介します。

参考資料