CircleCIを活用する中で、小さなフラストレーションになりがちなのが、「パイプライン定義ファイルの変更作業」です。新しいテストやビルドジョブなどを.circleci/config.ymlファイルに追加し、新しいGitブランチにコミット、それをpushした後に実行される CircleCIのパイプライン実行結果を見て、YAMLファイルをさらに修正する・・・

１回の試行に数分かかり、何度も調整を行うことによって気がつけば30分1時間と時間が経っていることも少なくありません。

この記事では、CircleCI の設定ファイルを高速でデバッグするための仕組みとして、 CircleCI Local CLIを紹介します。CircleCIでのローカルデバッグ方法を理解して、「CIファイルの変更作業が億劫になって、最適化されていないパイプラインを使い続ける。」こんなケースのない、効率的な開発体験に挑戦しましょう。

CircleCI Local CLIでpush前にパイプラインを検証する

CircleCI の Local CLIは、あなたのローカルマシン上で動作する開発ツールです。これを利用することで、コードをリポジトリにプッシュする前に、ローカル環境で管理・テスト・デバッグできます。

CircleCI Local CLI をローカルにインストールする

インストール方法は CircleCIのドキュメントに、環境ごとのコマンドが紹介されています。

macOSを利用している場合は、Homebrewを利用してインストールできます。

brew install circleci

Windowsを利用している場合、 Chocolatey というパッケージ管理システムが利用できます。

choco install circleci-cli -y

CLIのセットアップは、circleci setupコマンドで

インストールしたCLIとCircleCIアカウントの連携には、circleci setupコマンドを実行します。実行すると、CircleCIのAPIトークン入力を求められます。

% circleci setup
CircleCI API Token   ✘

API Tokenは、CircleCIのWeb UIから取得できます。https://circleci.com/account/api にアクセスし、Personal API Tokenを生成してください。

APIトークンには名前をつけることができます。この手のAPIトークンは、ユースケースやサービスごとに発行する方が安全ですので、「Local CLI用に発行したトークンであること」を名前に明記しましょう。

あとは発行されたAPIトークンをコピーし、コマンドに入力します。

% circleci setup
CircleCI API Token ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
API token has been set.

この後、CircleCI Hostについて質問があります。これはセルフホスト型の CircleCI である CircleCI Serverを利用している人向けの設定項目です。無料プランのあるクラウド版を利用している場合、ここはデフォルト値の「https://circleci.com」のままエンターキーを押しましょう。

CircleCI Host https://circleci.com  ✔

これでセットアップは完了します。

CircleCI host has been set.
Setup complete.
Your configuration has been saved to /Users/hidetaka/.circleci/cli.yml.

設定ファイルはユーザーディレクトリ内に作られた.cirlceciフォルダにYAMLで保存されます。以下のようなファイルが追加されていますので、もし設定内容をチェックしたい場合や、直接変更したい場合はこのファイルを使いましょう。

% cat /Users/hidetaka/.circleci/cli.yml
host: https://circleci.com
endpoint: graphql-unstable
token: CCIPAT_xxxx
rest_endpoint: api/v2
tls_cert: ""
tls_insecure: false
orb_publishing:
    default_namespace: ""
    default_vcs_provider: ""
    default_owner: ""

設定が完了したかどうかは、circleci info orgコマンドなどでチェックできます。

 circleci info org
+--------------------------------------+-----------------+
|                  ID                  |      NAME       |
+--------------------------------------+-----------------+
| 0ffedcab-9999-4ea2-a76e-123456789abc | hidetaka-cci    |
+--------------------------------------+-----------------+

これで設定が完了しました。なお、初回実行時、テレメトリー（利用状況データ収集）への同意を求められます。これは circleci telemetry enable/disable でいつでも変更可能です。

パイプラインの設定を、ローカルで検証する

Local CLIの設定が完了しました。では早速 CLI を活用しましょう。もっともシンプルなユースケースは、「変更した.circleci/config.ymlファイルを検証する」ことです。circleci config validateコマンドを実行してみましょう。

% circleci config validate
Config file at .circleci/config.yml is valid.

このコマンドを使うと、CircleCIのパイプライン定義に問題がないかをチェックできます。これにより構文エラーなどの明確な設定エラーについて、ローカルで迅速に検証できます。

例えば以下のエラーを見てみましょう。

% circleci config validate
Error: config compilation contains errors: config compilation contains errors:
        - Error calling workflow: 'sandbox_orb_workflow'
        - Cannot find a definition for job named sandbox_orb

エラーを読むと、「sandbox_orb_workflowというワークフローの中にあるsandbox_orb Jobが見つからない」と書かれています。よって.circleci/config.ymlファイルのjobsブロックをチェックし、sandbox_orb が定義されているかや、typoがないかなどをチェックする必要があります。

もしCursor / Claude Code / KiroなどのAIコーディング型IDEを使っている場合は、エラーメッセージをAIに渡すことで、原因調査を効率的に進めることも可能です。

壊れたパイプライン定義をpushさせないためには、Git Hookを利用して検証を必須にすることもできます。うまくLocal CLIとGit Flowを組み合わせて予防的な開発フローを実現しましょう。

CircleCI Local CLIで、ジョブをローカル実行する

Local CLIには、ファイルの検証以外のユースケースもあります。「このジョブ、本当にちゃんと動くのかな？」という不安を解消するために、実際にジョブをローカルで実行してみましょう。

circleci local execute <job-name>

<job-name>は、.circleci/config.ymlのjobsブロックに定義した名前を入力しましょう。以下のYAMLを定義している場合、<job-name>はsay-helloが利用できます。

version: 2.1

jobs:
  say-hello:
    docker:
      - image: cimg/base:current
    steps:
      - checkout
      - run:
          name: "Say hello"
          command: "echo Hello, World!"

workflows:
  say-hello-workflow:
    jobs:
      - say-hello

これでシンプルなジョブの動作確認についても、ci testのようなコミットを作ってgit pushする必要なくローカルで検証できます。ただしこのコマンドについては、いくつかの制約が存在します。

• Workflowsの制限: Workflows全体をオーケストレーションすることはできず、一度に実行できるのは単一のジョブのみです。
• オンライン機能の制限: 以下のCircleCIプラットフォームとの連携が必要なコマンドは、ローカル実行時にはスキップされます。
  • save_cache（キャッシュの保存）
  • restore_cache（キャッシュの復元）
  • store_artifacts（成果物の保存）
  • store_test_results（テスト結果の保存）
• Secretsの制限: Web UIで設定した暗号化された環境変数は利用できません。ただし、-e フラグでローカル指定は可能です。

CircleCI Local CLIの便利コマンド

そのほかにも、IDEやコマンドラインで開発する上で知っておくと便利なコマンドがいくつか用意されています。

ブラウザでプロジェクトを開く

以下のコマンドを実行するだけで、そのプロジェクトのCircleCIダッシュボードページがデフォルトのブラウザで開きます。

circleci open


CircleCIのプロジェクトページをブックマークしたり、TOPページからプロジェクトを探したりするよりも高速にページへアクセスできますので、ぜひ覚えておきましょう。

CLIのバージョン確認とアップデート

現在インストールされているCLIのバージョンを確認するには、以下のコマンドを使います。

circleci version


CLIを最新バージョンに更新するには、以下のコマンドを実行します。

circleci update


ただし、macOSでHomebrewを使用してインストールした場合、CLIのバージョン管理はHomebrewに委ねられるため、brew upgrade circleci を使用してください。

Orb管理コマンド

Local CLIは、Orbの開発と管理もサポートしています。

# Orb情報の取得
circleci orb info <namespace/orb@version>

# Orbの検証
circleci orb validate <path-to-orb.yml>

# Orbの処理（依存解決）
circleci orb process <path-to-orb.yml>


プライベートOrbを扱う場合は、Organization IDを指定します。

circleci orb validate --org-id <org-id> orb.yml

CircleCIが提供する2つのCLIコマンドについて

この記事では、CLIコマンドのことを「Local CLI」と表記しました。これはCircleCIが提供するCLIコマンドがもう１つ存在するからです。

Environment CLI：CircleCIパイプラインの制御用 CLI

Environment CLIは、CircleCIのパイプライン内（コンテナやVM内）でのみ利用可能なCLIです。

こちらは Local CLIと異なり、以下のようなジョブ実行中の制御やオーケストレーションに関する機能を提供します。

• テストスイートを動的に分割し、並列実行を最適化する
• デプロイの進捗をCircleCIのUIに連携する
• 実行時に環境変数を文字列に置換する
• 条件に応じてタスクを制御する

項目	Local CLI	Environment CLI
実行場所	開発者のローカルマシン	CircleCIのコンテナまたはVM内
インストール	必要（brew、snapなど）	不要（実行環境にプリインストール済み）
主な目的	設定の検証、ローカルでのテスト、管理	パイプライン実行中の動的なオーケストレーション
主な用途	config.ymlの検証、ジョブのローカル実行、Orb管理、コンテキスト管理	テストの分割と並列化、デプロイ状況の追跡、環境変数の置換、タスクの制御

「ローカルPCで実行するなら、Local CLI」「CircleCIのパイプラインにて実行するなら、Environment CLI」、このように違いを覚えておくことで、「今どっちのCLIについて調べれば良いのか？」を迷わないようにできます。

本来の開発に集中するために、Local CLIをワークフローへ取り入れよう

CI / CDのパイプラインを整備するのは、意図しない不具合や変更を Production コードベースに取り入れない・リリースさせないことが目的です。意図しない変更やリリースを行うことで、顧客体験を損ない、企業の収益やブランドイメージを毀損し、それによって開発チームが獲得できるリソースや予算が削減されるリスクを、CI / CD パイプラインで軽減させます。しかし時に複雑なパイプライン定義は時に「CI / CDパイプラインの保守作業」という新しい差別化につながらない重労働を生み出します。「アプリのデプロイを行いたいのに、CircleCI / GitHub Actionsのワークフロー設定調整に時間を取られている」そんな経験は開発者の誰でも経験したことがあるでしょう。

CircleCI Local CLIが提供するバリデーション・ローカル実行の２コマンドは、この差別化に繋がらない作業を軽減します。CircleCIにpushして問題に気づく・修正を行うのではなく、ローカルで時に生成AIの力を借りながら高速に変更・検証を実施できます。

新しいCLIコマンドやツールを覚えるのは億劫になりがちですが、巡り巡って効率化につながる要素として、ぜひお試しください。