circleci-cli

CircleCI の日常的な開発ワークフロー（CLI）

日々のサイクル：設定を変更 → コミット／プッシュ → 実行を確認 → 失敗を読む → 再実行。 ほとんどのコマンドは、現在の Git リモートからプロジェクトを、チェックアウト中のブランチからブランチを推測するため、 リポジトリ内では --project／--branch を指定することはほとんどありません。

データを返すすべてのコマンドで --json を使用でき、--jq '<expr>' を使えば、別途 jq を使わずに データをフィルタリングできます。人間向けの出力は Markdown です。ターミナルがない場合、CLI はページャーを省略し、色を無効にし、 プロンプトを表示する代わりに不足しているフラグを示して即座に失敗します（例：--value is required in non-interactive mode.）。そのため、事前に設定しておく必要はありません。

事前確認とサインイン

circleci version を実行し、続けて circleci auth me を実行します。$CIRCLE_TOKEN（保存済みのトークンより優先されます）を読み取り、 どのユーザーとして認証されるかを確認するため、認証状態の確認も兼ねています。使用可能なトークンがない場合は、 No CircleCI API token found で失敗します。

サインインするには、circleci auth login を実行します。ユーザーに API トークンを尋ねないでください。OAuth フローでユーザーから秘密情報を受け取る必要はなく、 トークンをチャットに貼り付けるよりもブラウザーで認証してもらうほうが安全です。ターミナルがない場合は、ユーザーのブラウザーで認証ページを開き、 同じ URL を標準エラー出力に表示してから、承認を待って最大 5 分間ブロックします。

• デフォルトより十分に長いタイムアウトを設定してバックグラウンドで実行するか、1～2 分で諦めてしまうフォアグラウンド呼び出しは避けてください。
• ユーザーにブラウザーでリクエストを承認するよう伝えてください。また、ブラウザーのウィンドウが手前に表示されない場合に備えて、表示された URL も伝えてください。ユーザーはあなたの出力ではなく、あなたの操作を見ています。
• 承認されたら、circleci auth me で確認してください。

--no-browser を指定すると、何も開かずに URL を表示します。CI と CIRCLE_NO_INTERACTIVE もブラウザーを開かないようにします。ブラウザーを操作するユーザーがいないためです。これらの環境では、代わりに CIRCLE_TOKEN を設定してください。

1. コミット前 — ローカルで検証する（迅速なフィードバック）

circleci config validate                       # lint .circleci/config.yml (default path); use -c <path> or - for stdin
circleci config process .circleci/config.yml   # expand orbs/params → the final compiled config
circleci config process .circleci/config.yml --pipeline-parameters params.yml   # process with pipeline params

• validate --org gh/<org> は、プライベート Orbs を解決するために必要です。
• -n/--next は、今後予定されている（破壊的変更となる可能性がある）設定変更をプレビューします。
• 新しいリポジトリの初期設定ファイルを生成するには、circleci config generate [path] を実行します（既存のファイルは上書きしません）。

便利な Git フック — 設定が無効な場合にプッシュをブロックします（.git/hooks/pre-push）：

#!/bin/sh
circleci config validate || { echo "Fix .circleci/config.yml before pushing"; exit 1; }

2. コミット、プッシュして、トリガーされた実行を確認する

git push                                        # your trigger fires a run
circleci run watch                              # watch the latest run on the current branch; blocks to completion
circleci run watch --sha "$(git rev-parse HEAD)"  # match the run for THIS commit (polls up to 2m for it to appear)
circleci run watch --failfast                   # bail the moment any job fails

run watch の終了コードを利用すると、スクリプトで処理できます：0 すべてのワークフローが成功 · 1 何らかの失敗 · 6 キャンセル · 7 設定が拒否された · 8 タイムアウト（--timeout、デフォルトは 30m）。次のようにつなげて実行できます：git push && circleci run watch --sha "$(git rev-parse HEAD)"。

3. パイプライン／実行を確認する

circleci run list                    # recent runs for this project (--limit, -b <branch>, -B current branch)
circleci run get                     # latest run on current branch: workflows → jobs, with status
circleci run get <run-id>            # a specific run
circleci my runs                     # YOUR recent runs across every project you can access
circleci run open                    # open the current branch's run in the browser

run get は、実行 → ワークフロー → ジョブのツリーを表示します。掘り下げるために ID を取得するには --json を追加します （workflows[].id、workflows[].jobs[].id）。これらの UUID は、以下のコマンドで使用します。

4. 失敗を掘り下げる

circleci run get --json --jq '.workflows[].jobs[] | select(.current_outcome=="failed") | {name,id}'   # failing jobs + UUIDs
circleci job output list <job-id>              # per-step logs (rendered; --tail N, default last 200 lines/step)
circleci job output get  <job-id> --step-num <N>   # full output of one step (--execution <i> for parallel runs)
circleci job get <job-id>                      # job metadata (status, timing, parallelism)
circleci testresult list <job-id>              # FAILED tests only by default (--all, --filter result=…, --sort, --limit)
circleci job artifact <job-id>                 # list artifacts; -o <dir> to download them

並列ジョブの場合、job output list --execution <index> を指定すると、対象のシャードのみに絞り込めます。

5. 実行に対処する

circleci workflow rerun <workflow-id>               # rerun the whole workflow from scratch
circleci workflow rerun <workflow-id> --from-failed # rerun only the failed jobs (workflow IDs come from `run get`)
circleci run cancel <run-number-or-id>              # stop a run (-f to skip the prompt)
circleci run trigger                                # manually trigger a run (current project/branch)
circleci run trigger -b <branch> --parameter deploy=true --parameter tier=2   # trigger with params (repeatable)
circleci workflow cancel <workflow-id>              # cancel a single workflow

対話的にデバッグする（ジョブに SSH 接続する）には、Web アプリから SSH を有効にして再実行します。CLI にそのためのフラグはありません。 circleci run open を使えば、すぐに該当ページを開けます。

トラブルシューティング — 各情報の確認方法

確認したいこと…	コマンド
プッシュはビルドされましたか？どの実行ですか？	circleci run watch --sha "$(git rev-parse HEAD)" / circleci run list -B
最新の実行全体のステータス	circleci run get
失敗したワークフロー／ジョブ	circleci run get --json --jq '.workflows[].jobs[] | select(.current_outcome=="failed")'
ステップが失敗した理由（ログ）	circleci job output list <job-id> → job output get <job-id> --step-num N
失敗したテスト	circleci testresult list <job-id>
ビルド出力／レポート	circleci job artifact <job-id> -o ./artifacts
プッシュ前の設定の問題	circleci config validate / circleci config process
UI とローカル環境で設定エラーが異なる場合	--org を指定して検証し、プライベート orb の解決方法を合わせます
最近自分が実行したものすべて	circleci my runs
ブラウザーで開く	circleci run open、circleci workflow open、circleci job open
プロジェクトの環境変数名	circleci envvar list
組織のコンテキストとそのシークレット	circleci context list、circleci context secret list <context>
パイプライン定義とそのトリガー	circleci pipeline list、続けて circleci project trigger list --pipeline-definition-id <id>
ここに記載されていない情報	references/api-coverage.md で、各 v3 エンドポイントに対応するコマンドを確認できます
CircleCI の機能／設定構文に関する質問	推測せず、circleci-config スキルまたは docs MCP を使用してください

注意点

• コマンドはデフォルトで git リモートのプロジェクトと現在のブランチを対象にします。リポジトリに cd してください。リポジトリ外では --project gh/<org>/<repo> と -b <branch> で対象を指定できます（注：--project を指定すると、run get／run open はチェックアウト中のブランチではなく、デフォルトで main ブランチを対象にします）。
• run watch --sha は実行が表示されるまで 最大 2 分間ポーリングします。プッシュ直後であれば想定どおりの動作です。
• ログ、テスト、アーティファクトの参照には、ジョブ番号ではなく ジョブ UUID（run get --json／workflow get で取得）を使います。
• run cancel には実行番号または UUID を指定します。番号でキャンセルする場合は --project を指定してください。
• circleci api <path> は /api/v3 を基準に相対パスを解決します。api で始まるパスはそのまま送信されます。必要な機能をカバーするコマンドがない場合にのみ使用してください。どのエンドポイントに対応するコマンドがあるかは references/api-coverage.md を確認してください。パス内の {project-id} と {org-id} は git リモートから設定されます。
• パイプラインの実行 1 回分を run と呼びます（run list、run get）。circleci pipeline は、run が実行する設定とチェックアウトソースを含むパイプライン 定義を管理するため、run は pipeline list では確認できません。
• run trigger（このスキル：推定されたプロジェクト／ブランチで run を開始）と、pipeline run --definition-id …（定義を指定して実行。オンボーディングスキルを参照）を混同しないでください。
• 実際の run と job output／testresult を確認してください。ステータスがグリーンなだけでは、ステップが意図したとおりに動作したとは限りません。

安全策

• 変更する前に読み取りましょう。 rerun／trigger／cancel の前に、読み取り専用コマンド（run get／list、job output、testresult、job artifact）を優先し、パイプラインの状態を変更する前に組織／プロジェクトの対象範囲を確認してください。
• 環境変数やトークンからシークレットの値をそのまま出力しないでください。 シークレットは op read／標準入力からパイプで渡してください。コマンドライン引数には絶対に渡さないでください（シェル履歴やログに漏れるためです）。
• コマンドをでっち上げないでください。 まず circleci help で確認し、サブコマンドが一覧にない場合は使用しないでください。トップレベルに trigger はありません。run の開始には run trigger を、定義に付属するトリガーの管理には project trigger を使います。api がない古いビルドでは、CircleCI アプリ／UI または接続された CircleCI MCP ツールでクラウドジョブのログを確認してください。
• 認証／権限エラーが発生した場合は、むやみに再試行せず、権限が不足している正確な範囲と、安全な解決方法（circleci auth login、User Settings で権限を更新するなど）を報告してください。

CLI で対応できない場合に CircleCI に報告する

circleci feedback は、CLI を開発しているチームにレポートを送信します。CLI 自体がタスクの妨げになった場合に送信してください。

• CircleCI 側の問題と思われるエラー：5xx エラー、または CLI が If this looks like a CircleCI problem, report it: circleci feedback … と続けるエラー。
• 機能の不足：circleci help と references/api-coverage.md を確認しても、必要な操作に対応するコマンドがない。
• わかりにくい出力：出力を読み違えた、またはほかで確認した情報と矛盾していた。

circleci feedback "run get --json listed no jobs for a run the web app shows with three" --tool "run get"

• 何をしようとしていたか、何を実行したか、何が起きたかを、1 つの引数として引用符で囲んで説明してください。--tool には、対象のコマンドを指定します。
• レポートにはユーザーの CircleCI ID が含まれるため、CLI の挙動は自分の言葉で説明し、秘密情報、環境変数の値、ログの抜粋は記載しないでください。
• ユーザーの設定やコードの問題、トークンや権限の不足はユーザー側の問題であり、レポートに含めないでください。
• 問題ごとにレポートを 1 件送信してから、タスクを続けてください。feedback が失敗した場合、または circleci help に表示されない場合は、送信せずに先へ進んでください。

結果を報告する

完了したら、次の内容を要約してください。

1. 実行したコマンドとその目的。
2. 主な出力：パイプライン、ワークフロー、ジョブの ID、ステータス、失敗したステップ。
3. 実施した操作（再実行／トリガー／検証）とその理由。
4. 残っている阻害要因と、次に推奨する CLI コマンド。
5. CircleCI に送信したフィードバックと、その内容。