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.

Authentication

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.

Running headless commands

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/"

CI/CD examples

GitHub Actions

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"

Other patterns

# 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.

Flags reference

Best practices

• 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.

Limitations

• 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.

Related

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