あらゆる開発者がこの瞬間を知っています。CIが赤くなり、選択を迫られます。ブラウザを開いてWeb UIをクリックし、run、ワークフロー、ジョブ、ステップ、ログの1行までたどっていくか。それとも、どうせ修正はそこで行うことになるターミナルに留まるか。
新しいCircleCI CLIは、まさにそのためにあります。バージョン1.0で、現在betaです。長年提供してきたCLIの改良版ではなく、Goでゼロから書き直したものです。ほとんどの部分は私が書いたので偏った見方かもしれませんが、初日からの目標は、開発者が実際に仕事をする方法、そして今ではエージェントが仕事をする方法に合わせた、本当に質の高い体験をつくることでした。
実際に試してみたい方は、cli.circleci.comから今すぐインストールできます。
ここでは、なぜゼロからやり直したのか、そして何を作ったのかを説明します。
リファクタリングではなく、再構築を選んだ理由
既存のCLIは長年にわたって開発者を支えてきましたが、多くの長寿命なツールと同じように、その過程で相応の技術的負債と使い勝手の粗さを積み重ねていました。
それでもパッチを当て続けなかった理由は、コーディングエージェントです。エージェントは、まさに一貫性が失われていた部分（予測可能なJSON、安定したexit codes、エージェントにとって読みやすいヘルプテキスト）に依存しています。そして人間のように、粗さを勘で乗り越えることはできません。エージェント（そして人間）にとって本当に優れたCLIにするには、その基盤そのものを見直す必要があり、そこまでやるなら、きちんとやるべきでした。
そこで、まっさらな状態から始めました。Goでゼロから書かれた新しいCLIで、最初のコミットからデザインルールを徹底しています。ここからは、そのルールについて説明します。
コードより先に、デザイン原則を
私たちはコードを書く前にデザインガイドを書きました。出力、エラー、フラグ、インタラクティブ性、堅牢性についての原則文書一式で、すべてのコマンドがこれに照らして検証されます。時代を感じさせる話ですが、このガイドはリポジトリのagents/ディレクトリに置かれています。CLIの構築を手伝ったコーディングエージェントへの指示書としても機能しているからです。
その哲学を一言で言えば、人間を第一に、コンポーザビリティはオプトインでというものです。ターミナルでは美しく表示され、出力をリダイレクトした瞬間にプレーンでパイプ可能になります。その上に、すべてのコマンドが満たすべき、譲れないルールがいくつか置かれています。
- データを返すコマンドはすべて
--jsonに対応する。例外なし。 - エラーは構造化されている。何が起きたか、なぜ起きたか、次に何を試すべきか、ドキュメントはどこにあるか。exit codesは安定していて、文書化されている。
circleci configはパイプラインのYAML、circleci settingはCLI自体の設定。この二つはもう二度と混ざらない。- コマンドのネストは最大 階層まで。それより深くなる場合は、トップレベルのエイリアスを用意する。
- すべてのコマンドには、実用的なヘルプテキストと、少なくとも3つの実例が付属する。
- テレメトリは開示され、オプトアウト可能で、CI環境では自動的に無効になる。
どれ一つを見ても、それ自体は特に目新しいものではありません。しかし、それらすべてが揃うことで、戦わなければならないツールと、味方だと感じられるツールの違いが生まれます。
エージェントのために作られている
この同じルールが、CLIをエージェントにとって読み取りやすいものにしています。一貫したJSON、安定したexit codes、次に何をすべきかを示すエラー、そしてエージェントが読めるヘルプテキスト（生成されたllms.txtもあります）。以下で紹介する機能は、あなたにとってと同じように、エージェントにとっても等しく機能します。
さらに一歩進んで、バイナリにはMCPサーバーが組み込まれており、1つのコマンドで、好きなエディタやアシスタントに接続できます。
circleci mcp claude enable # Claude Desktop
circleci mcp cursor enable # Cursor
circleci mcp vscode enable # VS Code
あなたのエージェントは、run、job、ステップの出力、テスト結果を調べるためのツールを手に入れます。別途インストールも、つなぎ込みのコードも必要ありません。
これでClaudeは、どこを見るべきか指示されなくても、失敗したjobを見つけ、ログを読み、修正をpushできるようになります。
トークンを貼り付けずにログイン
旧CLIとの最初の接点は、最悪の体験でした。Web UIに行き、個人用のAPI tokenを生成し、それをターミナルに貼り付ける。新しいフローはコマンド1つだけです。ホストを選ぶと、CLIがブラウザでのOAuthに引き渡してくれます。返ってきたtokenはシステムのkeyringに保存され、平文のファイルには決して置かれません。（個人アクセストークンの方が好みですか？そのフローも、矢印キー1つ分の距離に、今も残っています。）
ブラウザなしで、runを確認する
circleci run listは、git remoteから推測したプロジェクトの最近のrunを表示します。circleci run getは、あるrunの全体像（ワークフロー、ジョブ、結果、所要時間）を示し、circleci job getは1つのジョブに深く入り込み、ステップごとの所要時間やexit codesまで確認できます。
出力の形に注目してください。単一の平坦なテーブルではありません。すべてのコマンドはmarkdownレポートとしてレンダリングされ、見出し、リスト、テーブルがターミナル上でスタイリングされます。これにより、すべてを無理に表形式に押し込めることなく、構造化された情報を表示できます。
TUI: ブラウザタブなしの、日々のデバッグ
circleci run getを引数なしで実行すると、インタラクティブな体験が得られます。トリガー、ステータス、経過時間でフィルタリングできるrunピッカーから、runのワークフロー、ジョブ、ステップへと直接入り込めます。ステップの出力をページ送りし、失敗した箇所へすぐに移動できます。かつてWeb UIで6回クリックが必要だったループが、ターミナルの中だけで、わずか数回のキー入力に変わります。
charm/bubbletea スタックの上に構築されており、私自身の日々のデバッグの大部分では、これがWeb UIの代わりになっています。
--jsonと--jqを、あらゆる場所で
データを返すコマンドはすべて--jsonをサポートしています。このCLIの新機能として、--jqが組み込まれているため、スクリプト側にjqをインストールする必要はありません。また、出力はターミナルで見ているときは色付きになり、パイプで渡すときはプレーンになります。
成功しなかったすべてのジョブの名前を、1行で取得できます。
circleci run get --json --jq '.workflows[].jobs[] | select(.outcome != "success").name'
自分仕様にする
レンダリングされる出力にはテーマがあり、circleci setting set themeを実行すると、ライブプレビュー付きのピッカーが開きます。矢印キーで選択肢を移動すると、見出し、テーブル、インラインコードがリアルタイムでスタイルを変えていく様子を確認できます。テーマは、インタラクティブなフローだけでなく、レンダリングされるすべての出力に適用されます。
地味だけど大事な部分
なくなったときにだけ気づくような細部も、すべて用意されています。すでに設定済みのNO_COLORやPAGERは尊重されます。DO_NOT_TRACKはテレメトリを無効にします。TTY検出により、パイプに渡したときは出力が適切に簡略化されます。基本的なターミナルでは色がダウンサンプルされます。そしてCI=trueは非インタラクティブモードを意味し、スピナーも更新の催促も表示されません。
発見のしやすさも同様です。circleci help getting-startedで全体像をつかめ、circleci help environmentはすべての環境変数を文書化しており、どのエラーにも次の一歩の提案がついています。ターミナルが何をできるかを知るために、ターミナルを離れる必要は決してありません。
試してみる
CLIは現在beta版です。すべてのプラットフォーム向けのインストール方法は、cli.circleci.comをご覧ください。何か粗さを感じたら（助けにならなかったエラー、--jsonが用意されていないコマンド、パイプで壊れた出力など）、それこそ私たちが求めているフィードバックです。それらは、このCLIが自らに課している基準そのものです。issueを開いて、私たちにその基準を守らせてください。
