はじめに
Kiro CLI 2.0が2026年4月13日にリリースされました。Windows対応など大きなアップデートがいくつかありましたが、今回の目玉アップデートの一つがHeadless Modeです。
Headless Modeとは、ブラウザを使わずAPIキーだけでKiro CLIを非対話的に実行できる機能です。CI/CDパイプラインや自動化スクリプトでの利用が想定されています。
実は2.0以前にも --no-interactive を使用してログインする方法は提供されていましたが、認証にブラウザが必要だったためCI/CD環境での利用は事実上不可能でした。2025年12月時点でAWSのDeveloper AdvocateもCI/CDでのHeadless利用について「現時点では推奨できる方法がない」とコメントしており、コミュニティから長く求められていた機能がようやく正式対応された形です。
本記事では以下の4つの検証を行い、Headless Modeの動作を確認していきます。
- 検証①：ブラウザ認証なしでAPIキーだけで動くか
- 検証②：
--trust-toolsによる権限制御 - 検証③：コンテキストの渡し方
- 検証④：GitHub Actionsでの実用ユースケース（記事の英語翻訳自動化）
事前準備
プラン要件
Headless ModeのAPIキー認証はPro・Pro+・Powerプランのみ利用可能です。Freeプランでは使えません。
APIキーの発行
app.kiro.dev/account/usage にアクセスし、API Keysセクションからキーを発行します。
-
Key nameに任意の名前を入力（例：headless-test） - Create keyをクリック
- 表示されたキーをコピー（表示は一度限りなので必ず控える）
キーは作成時にしか表示されません。必ずコピーして安全な場所に保管してください。
Enterpriseの場合の注意点
Kiro Enterpriseを使っている場合、管理者がマネジメントコンソールの Settings > Kiro settings から「Enable users to generate API keys」をONにしていないとAPIキーが使えません。
今回の検証でわかったこととして、この設定はAPIキーの発行ではなく使用を制御しています。そのため、キーの発行自体はできるのですが、設定がOFFの状態では既存のキーでも認証エラーになります。CI/CDでHeadless Modeを使う場合は必ず管理者にONにしてもらう必要があります。
環境変数の設定
発行したキーを環境変数に設定します。
export KIRO_API_KEY=<発行したAPIキー>
検証①：ブラウザ認証なしで動くか
2.0の本質的な新機能を確かめるために、ブラウザ認証が一切ない環境から検証しました。GitHub Codespacesで新規環境を用意し、kiro-cli 2.0をインストールしてAPIキーだけで実行します。
# kiro-cli 2.0のインストール
curl -fsSL https://cli.kiro.dev/install | bash
# バージョン確認
kiro-cli --version
# kiro-cli 2.0.0
# KIRO_API_KEYを設定（ブラウザ認証は一切しない）
export KIRO_API_KEY=<APIキー>
# 実行
kiro-cli chat --no-interactive "Hello, are you working?"
結果：
> はい、動いてますよ！何かお手伝いできることはありますか？
▸ Credits: 0.04 • Time: 3s
ブラウザを一切開かずAPIキーだけで動作することが確認できました。
検証②：--trust-toolsによる権限制御
Headless Modeではユーザーがツールの使用を都度承認できないため、事前にツールの権限を指定する必要があります。
--trust-all-tools で全ツールを許可することもできますし、--trust-tools で使用するツールのみを許可するかを選べます。
# 全ツール許可（警告メッセージが表示される）
kiro-cli chat --no-interactive --trust-all-tools \
"カレントディレクトリのファイル一覧を教えて"
# 特定ツールのみ許可
kiro-cli chat --no-interactive --trust-tools=fs_read,grep \
"カレントディレクトリに.mdファイルがあれば探して教えて"
--trust-all-tools を使うと以下の警告が表示されます。
All tools are now trusted (!). Kiro will execute tools without asking for confirmation.
Agents can sometimes do unexpected things so understand the risks.
--trust-tools で許可しなかったツールの操作はブロックされます。例えば fs_read,grep のみ許可した状態でファイル作成を指示すると：
Command fs_write is rejected because it matches one or more rules on the denied list:
- non-interactive mode (no user to approve)
最小権限の原則に従い、CI/CDでは --trust-all-tools より --trust-tools で必要なものだけ許可するのが安全です。
指定できるツール名一覧
--trust-tools で指定できる主なツール名は以下の通りです。
| ツール名 | 内容 |
|---|---|
fs_read |
ファイル・ディレクトリの読み取り |
fs_write |
ファイルの作成・編集 |
execute_bash |
Bashコマンドの実行 |
glob |
globパターンによるファイル検索 |
grep |
正規表現によるテキスト検索 |
use_aws |
AWS CLIコマンドの実行 |
use_subagent |
サブエージェントへのタスク委任 |
web_search |
Web検索 |
web_fetch |
URLからのコンテンツ取得 |
read や write のような短縮形でも動作しましたが、正式なツール名は fs_read・fs_write のようです。
検証③：コンテキストの渡し方
CI/CDではビルドエラーのログなどをKiroに渡したいケースがあります。
パイプは動かない
公式ドキュメントには以下のようなパイプを使った例が記載されています。
# 公式ドキュメントの例
cat build-error.log | kiro-cli chat --no-interactive "Explain this build failure"
しかし実際に試したところ、パイプの内容がプロンプトにうまく渡せませんでした。
そこで、回避策としてファイル経由で読み込ませてみたところ問題なく実行できました。
回避策：ファイル経由でfs_readに読ませる
# エラーログをファイルに保存
./build.sh > build-error.log 2>&1 || true
# Kiroにファイルを読ませる
kiro-cli chat --no-interactive --trust-tools=fs_read \
"build-error.logを読んでエラーの原因と修正方法を教えて"
ファイル経由だとKiroが能動的にファイルを読みに行くため、こちらは問題なく動作するようです。
検証④：GitHub Actionsでの実用ユースケース
Headless Modeはシングルターン（1回のコマンド実行）の設計です。対話しながら作業を進めるインタラクティブな用途には向きませんが、事前にプロンプトを定義できるCI/CDと非常に相性が良いです。
今回は実用的なユースケースとして、記事リポジトリの日本語mdファイルを自動で英語翻訳するGitHub Actionsワークフローを作成してみました。
ワークフローの仕様
- トリガー：手動実行（
workflow_dispatch） -
articles/ja/配下のmdファイルのうち、フロントマターにstatus: ready-for-enがあるものを対象 -
articles/en/に対応ファイルがないか、ja側が新しい場合に翻訳を実行 - 翻訳後は自動でcommit & push
KIRO_API_KEYの設定
GitHub Actionsで使用するAPIキーはRepository Secretsに登録します。
リポジトリの Settings > Secrets and variables > Actions から KIRO_API_KEY という名前でAPIキーを登録します。
ワークフローの実行結果
試しに先日投稿したこちらの記事を英語翻訳させてみることにしました。
Notice: No EN file for 'CodexとClaudeが半日バトり続けた話.md' — will translate.
Translating: CodexとClaudeが半日バトり続けた話.md
> 英語版を articles/en/CodexとClaudeが半日バトり続けた話.md に保存しました。
▸ Credits: 0.30 • Time: 51s
Translated 1 file(s).
1ファイルあたり約54秒、0.30クレジットで翻訳が完了しました。翻訳品質も単純な直訳ではなく、英語として自然な構成に再編してくれたようです(私は英語が得意ではないのでClaudeとCodexに評価してもらった結果の批評です)
ガバナンス設定OFFでの挙動
Enterpriseの場合、Enable users to generate API keys をOFFにした状態でActionsを実行すると以下のエラーが発生し翻訳がスキップされます。
WARNING: Failed to retrieve MCP settings; MCP functionality disabled
Authentication failed. Your API key may be invalid or expired. Check your KIRO_API_KEY value.
注意点として、ワークフロー自体はSuccessになります。認証エラーで翻訳がスキップされても失敗扱いにならないため、気づきにくいです。エラーハンドリングを追加する場合はAnnotationsのNoticeを確認するか、翻訳件数が0の場合にワークフローを失敗させる処理を追加するとよいでしょう。
まとめ
今回の検証で確認できたことをまとめます。
Headless Modeで確認できたこと
| 項目 | 結果 |
|---|---|
| ブラウザ認証なし・APIキーのみで動作 | ✅ |
| --trust-toolsによる最小権限制御 | ✅ |
| パイプによるコンテキスト渡し | ❌（ファイル経由を推奨） |
| GitHub Actionsでの実用ユースケース | ✅ |
Headless Modeが向いているユースケース
- コードレビューの自動化
- テスト生成
- ビルドエラーの解析
- ドキュメント・記事の翻訳自動化
- 定期的なコードチェック
Headless Modeはシングルターン設計だからこそCI/CDとの相性が抜群です。プロンプトを事前に定義してAPIキーで認証するだけで、ブラウザなしに自動化パイプラインの中でKiroの力を使えるようになりました。
GitHub Actionsとの連携はまだ試せていないユースケースも多いので、引き続き検証していきたいと思います。
個人的に一番嬉しかったこと
移動中にふと気になったことをスマホからサッと実行したい、というのは以前からやりたいことでした。最近Claude Code on the Webも使えるようになり、やりたいことを叶えることができましたが、AWS環境を触る際はKiro CLI経由で使うようにしているため、スマホからKiroのタスクを実行したいニーズは変わらずありました。
2.0以前の状況：
Codespacesでkiro-cliをインストールしてログインを試みると、通常のブラウザ認証はCodespaces環境では動かないため --use-device-flow を使う必要があります。
kiro-cli login --license pro --use-device-flow \
--identity-provider https://xxxx.awsapps.com/start/ \
--region ap-northeast-1
# → URLとコードが表示される
# Code: FJPD-NXHD
# Open this URL: https://xxxx.awsapps.com/start/#/device?user_code=FJPD-NXHD
PCからであればURLを開いてデバイス認証が完了しますが、スマホからだとこのURLが開けず詰んでしまいます。
唯一の回避策は「PCで事前にログイン済みのCodespacesを開いたままにしておく」ことでしたが、複数のブランチからそれぞれCodespaces環境を作成して移動中に使いたいという目的とは相容れませんでした。
2.0以降：
CodespacesのSecretsにAPIキーを一度設定しておくだけで解決しました。
対話はできませんが、翻訳や定型タスクであれば十分です。移動中でも気軽に実行できるようになりました。
参考リンク