I tried Kiro CLI 2.0's headless mode — non-interactive agent execution with API key authentication

2026/4/13, Kiro CLI 2.0 was released.

https://kiro.dev/blog/cli-2-0/

The main new features are the following 3:

• Headless mode — Run non-interactively from CI/CD pipelines or scripts
• Windows support — Native operation on Windows 11
• Terminal UI (TUI) GA — Rich display and sub-agent monitoring

In this article, I will introduce the setup and execution of headless mode in an environment where Kiro Pro license is used with IAM Identity Center (SSO).

What is Headless Mode

Headless mode, added in Kiro CLI 2.0, is a feature that allows Kiro to run without an interactive terminal session by authenticating with an API key and passing prompts with the --no-interactive flag.

Previous Challenges

Until now, Kiro CLI authentication required an interactive browser sign-in (kiro-cli login). While persistent execution environments like Jenkins on EC2 could maintain sessions and use --no-interactive, Kiro was difficult to use in environments such as:

• AWS CodeBuild (temporary container environments launched from CodePipeline)
• AWS Lambda (serverless execution environment)
• AWS Step Functions (task execution within workflows)
• GitHub Actions (disposable runner environments for each job)

In these environments, it was practically impossible to incorporate Kiro into CI/CD pipelines because browsers couldn't be opened and there was no way to maintain sessions in advance.

Solution with API Keys

In headless mode, authentication is completed simply by setting an API key issued by the Kiro portal in the KIRO_API_KEY environment variable. No browser authentication is needed, and there's no worry about session expiration. This makes it possible to incorporate Kiro into CI/CD pipelines even in ephemeral execution environments like those mentioned above.

Prerequisites

This article assumes the following environment:

• Authentication method: Kiro usage via AWS IAM Identity Center (SSO)
• Billing: Kiro usage costs are included in AWS usage fees (AWS billing integration)
• Subscription: Kiro Pro / Pro+ / Power (API key authentication is available in these plans)
• Admin settings: API Keys generation is enabled in Kiro Console

Test Environment

Step 1: Admin Settings — Enable API Keys

Open the AWS Management Console Kiro settings screen with an IAM Identity Center administrator account and enable API key generation.

1. Sign in to the AWS Management Console
2. Open Kiro's Settings screen
3. Select the Kiro tab at the bottom
4. Toggle API keys to On in the Kiro settings section

Step 2: Generate an API Key

Once an administrator has allowed API Keys generation, users can create API keys. No special IAM permissions are required; any user linked to the Kiro application can create them.

2-1. Sign in to the Kiro portal

Access app.kiro.dev and select "Your organization."

2-2. Enter IAM Identity Center information

Enter the Start URL and Region, then click "Continue."

2-3. Sign in with SSO

Enter your username and password on the IAM Identity Center sign-in screen.

2-4. Open the API Keys section

After signing in, expand the API Keys section on the Account page.

2-5. Create a key

Enter an easily identifiable name in the Key name field and click "Create key."

2-6. Copy the key

Copy the generated API key (a string starting with ksk_).

Step 3: Basic Execution in Headless Mode

Set the API key as an environment variable and pass the prompt with the --no-interactive flag.

$ export KIRO_API_KEY=ksk_************************************
$ touch hoge
$ kiro-cli chat --no-interactive --trust-all-tools "List files in current directory"
All tools are now trusted (!). Kiro will execute tools without asking for confirmation.
Agents can sometimes do unexpected things so understand the risks.

Learn more at https://kiro.dev/docs/cli/chat/security/#using-tools-trust-all-safely

Reading directory: /Users/your-username/work/project (using tool: read, max depth: 0, max entries: 1000, excluding: defaults)
 ✓ Successfully read directory /Users/your-username/work/project (1 entries)
 - Completed in 0.0s

> There's just one file in the current directory:

- hoge (empty file, 0 bytes)

 ▸ Credits: 0.05 • Time: 6s

API key authentication worked normally, including tool execution (directory reading).

Step 4: Running a Security Review

As a practical use case for headless mode, I tried running a code security review.

Preparing Vulnerable Sample Code

I prepared code intentionally containing vulnerabilities.

mkdir -p sample-app && cat > sample-app/app.py << 'EOF'
import os
import subprocess

def get_user_data(user_id):
    query = "SELECT * FROM users WHERE id = " + user_id
    result = subprocess.call("echo " + query, shell=True)
    password = "admin123"
    api_key = "AKIAIOSFODNN7EXAMPLE"
    return result

def process_file(filename):
    f = open(filename, "r")
    data = f.read()
    return data

# TODO: Add input validation
# TODO: Implement proper error handling
# FIXME: This function is too slow
def calculate(x, y):
    return x / y
EOF

Model Selection

Since the /model command cannot be used in headless mode, specify the model in advance with settings.

# Set the model
$ kiro-cli settings chat.defaultModel claude-opus-4.6

# Confirm the setting
$ kiro-cli settings chat.defaultModel
claude-opus-4.6 (global)

Security Review with Claude Opus 4.6

Using --trust-tools=read,grep to grant read-only permissions to prevent file modifications.

$ kiro-cli chat --no-interactive --trust-tools=read,grep \
  "sample-app/app.py のセキュリティ脆弱性をレビューしてください。各問題について重大度（Critical/High/Medium/Low）と修正方法を日本語で一覧にしてください。"

> まずファイルの内容を確認します。
Reading file: /Users/your-username/work/project/sample-app/app.py, all lines (using tool: read)
 ✓ Successfully read 487 bytes from /Users/your-username/work/project/sample-app/app.py
 - Completed in 0.0s

> 以下がセキュリティレビューの結果です。

### セキュリティ脆弱性一覧

| # | 脆弱性 | 重大度 | 該当行 | 説明 |
|---|--------|--------|--------|------|
| 1 | SQLインジェクション | Critical | L5 | user_id を文字列結合でクエリに埋め込んでおり、任意のSQL文を実行される危険がある |
| 2 | OSコマンドインジェクション | Critical | L6 | subprocess.call(..., shell=True) にユーザー入力を直接渡しており、任意のコマンドを実行される |
| 3 | ハードコードされたパスワード | High | L7 | password = "admin123" がソースコードに平文で埋め込まれている |
| 4 | ハードコードされたAPIキー | High | L8 | AWSアクセスキーがソースコードに平文で埋め込まれている。リポジトリ経由で漏洩するリスクが高い |
| 5 | ファイルリソースの未クローズ | Medium | L12 | open() の戻り値を close() せず、with 文も使っていないためリソースリークが発生する |
| 6 | パストラバーサル | Medium | L11-13 | filename を検証せずに open() しており、../../etc/passwd 等で任意ファイルを読み取られる |
| 7 | ゼロ除算 | Low | L19 | y が 0 の場合に ZeroDivisionError が発生する。入力バリデーションもエラーハンドリングもない |

### 修正方法

1. SQLインジェクション — パラメータ化クエリ（プレースホルダ）を使う。
   cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))

2. OSコマンドインジェクション — shell=True を使わず、引数をリストで渡す。
   そもそもこの echo 呼び出し自体が不要なら削除する。
   subprocess.call(["echo", query], shell=False)

3. ハードコードされたパスワード — 環境変数やシークレットマネージャから取得する。
   password = os.environ["APP_PASSWORD"]

4. ハードコードされたAPIキー — 同様に環境変数やAWS Secrets Manager等から取得する。
   api_key = os.environ["AWS_ACCESS_KEY_ID"]

5. ファイルリソースの未クローズ — with 文を使う。
   with open(filename, "r") as f:
       data = f.read()

6. パストラバーサル — ファイルパスを正規化し、許可ディレクトリ内かを検証する。
   safe_dir = "/allowed/path"
   real = os.path.realpath(filename)
   if not real.startswith(safe_dir):
       raise ValueError("不正なファイルパス")

7. ゼロ除算 — 入力を検証してからの除算、またはエラーハンドリングを追加する。
   def calculate(x, y):
       if y == 0:
           raise ValueError("除数に0は指定できません")
       return x / y

 ▸ Credits: 0.39 • Time: 22s

Seven vulnerabilities were detected, with each item presented with the relevant line and correction code.

Comparison with DeepSeek 3.2

I ran the same prompt with DeepSeek 3.2 to check the differences between models.

$ kiro-cli settings chat.defaultModel deepseek-3.2
$ kiro-cli chat --no-interactive --trust-tools=read,grep \
  "sample-app/app.py のセキュリティ脆弱性をレビューしてください。各問題について重大度（Critical/High/Medium/Low）と修正方法を日本語で一覧にしてください。"

> sample-app/app.py の内容を確認しました。以下のセキュリティ脆弱性を確認しました：

| 脆弱性 | 重大度 | 修正方法 |
|---------|--------|----------|
| SQLインジェクション | Critical | パラメータ化クエリの使用 |
| シェルコマンドインジェクション | Critical | シェルコマンドの使用を避ける |
| ハードコード認証情報 | High | 環境変数/シークレットマネージャー |
| ファイル操作 | Medium | パス検証と正規化 |
| 例外処理 | Medium | 適切なエラーハンドリング |
| ログ記録 | Low | セキュリティログの実装 |

 ▸ Credits: 0.13 • Time: 21s

Model Comparison

Opus 4.6 excels in line number identification and code example specificity, but consumes about 3 times more credits. DeepSeek 3.2 detects major vulnerabilities while keeping costs down, making it a cost-effective choice for frequent execution in CI/CD cases.

Summary

I verified the setup and execution of Kiro CLI 2.0's headless mode in an IAM Identity Center (SSO) environment, from API key generation to execution.

Previously, browser authentication was required, making it difficult to use Kiro in ephemeral execution environments such as CodeBuild, Lambda, Step Functions, and GitHub Actions. With API key authentication in headless mode, Kiro can now be incorporated into CI/CD pipelines in these environments.

Security Considerations

• Minimize IAM role permissions: When specifying --trust-all-tools, Kiro can execute any command including the aws CLI. Since the IAM role permissions of the execution environment determine Kiro's operation range, grant only the minimum permissions necessary for the job
• Minimize tool permissions: For CI/CD, it is recommended to use --trust-tools=read,grep rather than --trust-all-tools, allowing only the necessary categories
• Secret management: Store API keys in each platform's secret management features (Secrets Manager, Repository secrets, etc.) and avoid direct inclusion in source code
• Regular rotation: Invalidate unused keys promptly in the Kiro portal

Reference Links

• Kiro CLI 2.0 Release Blog (English)
• Kiro CLI 2.0 Release Blog (Japanese)
• Kiro CLI 2.0 Changelog
• Headless Mode Documentation
• Authentication Methods Documentation
• API Key Governance Documentation