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 with your initial instruction. The instruction can be a positional argument or supplied through piped stdin. When stdin is piped and no positional argument is given, Kiro reads the full stream as the instruction:

# Positional argument
kiro-cli chat --no-interactive "your prompt here"

# Stdin only: pipe the entire instruction
printf '%s\n' "your prompt here" | kiro-cli chat --no-interactive

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 with the full instruction on stdin
{
  printf '%s\n\n' "Explain this build failure and suggest a fix:"
  cat build-error.log
} | kiro-cli chat --no-interactive --trust-tools=read

Use --require-mcp-startup when a non-interactive run depends on MCP tools. V2 and V3 wait for configured MCP servers before submitting the instruction. In V3, Kiro exits with code 3 if a server fails, its startup state cannot be determined, or it does not report a status within 30 seconds. Without the flag, Kiro logs MCP startup problems and continues. 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 (--agent-engine v2 or --agent-engine v3).

In V3, an interrupted non-interactive run writes a final interruption record to stream-json. Treat that final record as the end of the interrupted run instead of waiting for another completion record.

• 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, so the task stops before it begins instead of running without the expected tools.
• When using V2 or V3, supply your instruction as a positional argument or pipe it through stdin, but not both. V2 and V3 only read stdin when no positional argument is present.
• 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 a non-empty initial instruction, either as a positional argument or through piped stdin.
• 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