Amazon Web Services ブログ

Kiro CLI をプログラムから実行する：ヘッドレスモードの紹介

本記事は 2026 年 4 月 13 日に公開された Brian Beach の「Run Kiro CLI programmatically: introducing headless mode」を翻訳したものです。

Kiro CLI を使ったことがある方なら、kiro-cli login を実行するとブラウザが開いて認証が走る、というお決まりの流れはご存じかと思います。手元で作業しているときはこれで十分ですが、ブラウザが開けない環境ではそうもいきません。CI/CD パイプラインや cron ジョブ、コンテナビルドといった自動化された処理では、そもそもブラウザを開けません。

こうした場面で役立つのがヘッドレスモードで、API キーを生成して環境変数に設定するだけで、Kiro CLI をブラウザなしで動かせるようになります。使えるツール、エージェント、機能はすべて同じです。

この記事では、ヘッドレスモードの仕組みを説明し、具体的な活用例として GitHub Actions で push のたびに自動実行されるコードレビューの構築方法を紹介します。

API キーの取得

サインインして、アカウント設定から API キーを生成してください。

環境変数 KIRO_API_KEY を設定しておくだけで、Kiro CLI はブラウザベースのログインフローを完全にスキップします。対話モードとヘッドレスモードの違いはこの環境変数ひとつだけです。

実践例：GitHub Actions による自動コードレビュー

ヘッドレスモードを実際に活用してみましょう。セキュリティの問題、バグ、ベストプラクティスの観点からコードをレビューするカスタム Kiro エージェントを作成し、GitHub Actions に組み込んで push のたびに自動実行されるようにします。

コードレビューエージェントの定義

Kiro では、カスタムエージェントを定義できます。エージェントとは、特定の役割、使用するツール、振る舞いの指示を持つペルソナです。リポジトリの .kiro/agents/code-reviewer.json に以下の内容を配置してください。

{
    "name": "code-reviewer",
    "description": "Code review agent that analyzes code for bugs, security issues, performance, and best practices",
    "prompt": "You are a senior code reviewer. For every review:
1. Check for bugs, logic errors, and edge cases
2. Identify security vulnerabilities
3. Flag performance issues
4. Evaluate readability and maintainability
5. Suggest concrete improvements with code examples

Be direct and actionable. Categorize findings by severity: critical, warning, suggestion. Always explain *why* something is an issue, not just *what*.",
    "tools": [
        "read",
        "grep",
        "glob",
        "code"
    ],
    "allowedTools": [
        "read",
        "grep",
        "glob",
        "code"
    ],
    "resources": [],
    "hooks": {},
    "welcomeMessage": "Ready to review code. Share a file path, paste a snippet, or point me at a PR."
}

いくつかポイントを補足します。

  • もっとも重要なのが prompt フィールドで、ここでシニアレビュアーとして振る舞い、指摘を重大度ごとに分類するようエージェントに指示しています。
  • tools はエージェントが使用できるツールの一覧です。allowedTools はその中で確認なしに使えるサブセットです。CI で無人実行するため、読み取り専用のツールを事前承認しています。

GitHub Actions の設定

まず、API キーを GitHub シークレットとして保存します。リポジトリの Settings → Secrets and variables → Actions に移動し、KIRO_API_KEY という名前でリポジトリシークレットを追加してください。

次に、.github/workflows/kiro-code-review.yml に以下の設定を追加します。

name: Kiro Code Review

on:
    push:
        branches: [ main ]

jobs:
    code-review:
        runs-on: ubuntu-latest
        steps:
          - name: Checkout code
            uses: actions/checkout@v5
            with:
                fetch-depth: 0

          - name: Install Kiro CLI
            run: curl -fsSL https://cli.kiro.dev/install | bash

          - name: Run Kiro code reviewer agent
            env:
                KIRO_API_KEY: ${{ secrets.KIRO_API_KEY }}
            run: |
                kiro-cli chat \
                    --agent code-reviewer \
                    --no-interactive \
                    "Review the files in this repository and provide a summary of findings"

チェックアウト、インストール、レビューの 3 ステップです。

  • curl -fsSL https://cli.kiro.dev/install | bash は、Linux や macOS マシンと同じ方法で CLI をインストールします。
  • --no-interactive は、対話型チャットセッションを開始せず、レスポンスを標準出力に出力して終了するよう Kiro に指示します。CI では結果を受け取って次に進むだけなので、このオプションが適しています。
  • 環境変数 KIRO_API_KEY は自動的に読み込まれるため、設定ファイルは不要です。

注意：筆者は main ブランチにブランチ保護を有効にしています。main に直接 push できる状態だと、エージェントの設定やこの設定自体を変更される可能性があります。

これで、リポジトリへの push のたびにコードレビューが自動実行されます。

実行結果の確認

実際の動作を示すために、いくつかの問題を含むサンプルの Flask アプリケーションにエージェントを実行してみました。エージェントはリポジトリの構造を調べ、ソースファイルとテンプレートを読み込み、分類されたレポートを返しました。

結果は、クリティカル 4 件、警告 6 件、提案 5 件でした。ハードコードされた SECRET_KEY や Jinja2 の |safe フィルタによる XSS 脆弱性から、HTML のタイポまで幅広くカバーしています。出力の一部を紹介します。

CRITICAL

1. Hardcoded secret key and plaintext credentials — flaskr.py:14-16

   SECRET_KEY='development key',
   USERNAME='admin',
   PASSWORD='default'

   The SECRET_KEY is hardcoded and weak. Flask uses this to sign session
   cookies — anyone who knows it can forge sessions and impersonate any user.

2. XSS vulnerability via |safe filter — show_entries.html:13

   {{ entry.text|safe }}

   The |safe filter disables Jinja2's auto-escaping. Any logged-in user can
   inject arbitrary JavaScript via the text field.

...

Summary

| Severity   | Count | Key themes                                    |
|------------|-------|-----------------------------------------------|
| Critical   | 4     | Hardcoded secrets, XSS, no CSRF, committed DB |
| Warning    | 6     | Auth flaws, test isolation, code duplication   |
| Suggestion | 5     | Typos, accessibility, packaging, schema        |

コードレビュー以外の活用

このコードレビューの仕組みはほんの一例です。ヘッドレスモードを使えば、Kiro CLI をあらゆる自動化に活用できます。

  • ドキュメント生成 — main へのマージのたびに、コードベースをスキャンしてドキュメントを生成・更新するエージェントを実行する。
  • 依存関係の監査 — 依存関係ファイルをレビューし、古いパッケージや脆弱性のあるパッケージを検出するエージェントを実行する。
  • マイグレーション支援 — コードベースに対してエージェントを実行し、フレームワーク移行で更新が必要なパターンを特定する。
  • PR サマリー — プルリクエストの変更内容を人間が読みやすい形で要約する。

パターンは常に同じです。API キー、カスタムエージェントの定義、そして CI 設定への 1 行の追加だけです。

始めましょう

ヘッドレスモードは、開発者が直接操作できない場所（パイプライン、スケジュールジョブ、自動化された処理）に Kiro CLI を導入します。必要なのは環境変数ひとつだけです。エージェントを定義し、CI 設定に組み込めば、これまで人手を待っていた作業を自動化できます。コードレビュー、ドキュメント生成、依存関係の監査など、セットアップはすべて同じです。API キーと 1 行のコマンドで始められます。詳しくはヘッドレスモードのドキュメントをご覧ください。

この記事は App Dev Consultant 宇賀神が翻訳しました。