Headless mode

Headless mode lets you run Kiro CLI as part of your CI/CD pipeline to automate code reviews, generate tests, or troubleshoot build failures — no interactive terminal required. Authenticate with an API key, pass a prompt, and Kiro executes it end-to-end.

Headless mode requires an API key set as the KIRO_API_KEY environment variable. If you haven't created one yet, follow the steps in Generate an API key.

For details on authentication precedence and checking your active credentials, see Authentication.

Pass --no-interactive along with your prompt:

kiro-cli chat --no-interactive "your prompt here"

Since there's no user to approve tool calls, use --trust-all-tools or --trust-tools to grant permissions upfront:

# Trust all tools
kiro-cli chat --no-interactive --trust-all-tools "Write tests for the auth module and run them"

# Trust only specific tool categories
kiro-cli chat --no-interactive --trust-tools=read,grep "Find all TODO comments in src/"

name: Kiro Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Kiro CLI
        run: curl -fsSL https://cli.kiro.dev/install | bash
      - name: Review PR changes
        env:
          KIRO_API_KEY: ${{ secrets.KIRO_API_KEY }}
        run: kiro-cli chat --no-interactive --trust-tools=read,grep "Review the changes in this PR for security issues"

# Generate and run tests
kiro-cli chat --no-interactive --trust-all-tools "Write tests for the auth module and run them"

# Troubleshoot a failing build
cat build-error.log | kiro-cli chat --no-interactive "Explain this build failure and suggest a fix"

Use --require-mcp-startup to fail fast if MCP servers can't connect — useful for pipelines that depend on external tools. See exit codes for handling failures in scripts.

Pass --output-format stream-json to receive run events as JSON Lines on stdout. Each line is a self-contained JSON object, making the output easier to process in scripts, logging pipelines, and CI jobs than formatted text.

kiro-cli chat --no-interactive --trust-all-tools --output-format stream-json "Summarize open TODOs in src/"

--output-format stream-json requires V2 or V3 (--engine v2 or --engine v3).

• Store KIRO_API_KEY as a secret in your CI/CD platform — never hardcode it in pipeline configs or commit it to source control.
• Use --trust-tools with specific categories instead of --trust-all-tools to follow the principle of least privilege.
• Add --require-mcp-startup when your pipeline depends on MCP servers to fail fast instead of hanging.
• Pipe context into your prompt for richer results — for example, git diff | kiro-cli chat --no-interactive "Review these changes".
• Check exit codes in your pipeline to handle failures gracefully.
• Rotate API keys regularly and revoke any that are no longer in use from the Kiro portal.

• You must provide an initial prompt as an argument.
• No mid-session user input is possible.
• Interactive slash commands (/model picker, /agent picker) are not available.
• Terminal UI features are disabled.

• Authentication — API key setup and authentication methods
• Exit codes — Handle failures in scripts
• CLI commands — Full CLI flag reference