Headless mode - CLI - Docs - Kiro Loading image... Product * About Kiro * IDE * CLI * Web * Mobile * Crew * Pricing * Downloads For * Enterprise * Startups * Students Community * Overview * Ambassadors * Discord * Events * Powers * Shop * Showcase Resources * Docs * Blog * Changelog * FAQs * Report a bug * Suggest an idea * Billing support Social * * * * * * * English Site Terms License Responsible AI Policy Legal Privacy Policy Cookie Preferences English Loading image... * Apps * CLI * Web * Enterprise * Pricing * Docs * Community * Resources SIGN IN DOWNLOADS Loading image... Get Started Installation Authentication Your first project Models Overview Available models Reasoning effort Features How Kiro works Specs Steering Hooks MCP Permissions Custom agents Agent Skills Powers Cloud sessions Compaction Kiroignore Checkpoints and rewind Built-in tools Configuration scopes IDE 1.x What's new in 1.0 Setup & First Run Editor Chat Experimental Troubleshooting 0.x reference CLI What's new in 3.0 Setup & First Run Terminal UI Chat Voice mode Headless mode ACP Auto complete Experimental 2.x reference Crew Quick start Installation Running 24/7 Chat Agent Capabilities Features Interfaces Apps System & storage Configuration Security Troubleshooting Web Setup & First Run Identity Center Connect your repositories Working with the agent Autonomous mode Automations Memory Configuration Sync Sandbox Mobile - Preview Overview Commands and Reference CLI commands Slash commands Built-in tools Exit codes Settings Billing Overview Managing your subscription Upgrading your plan Downgrading your plan Cancelling your plan Purchasing add-on credits Managing your payments Managing usage notifications Managing your taxes Contacting billing support Deleting your account Related questions Enterprise Concepts Onboarding quickstart Connecting your identity provider Deployment options Subscribe your team Manage subscriptions Governance Monitor and track Settings Managed updates Billing IAM Supported regions Privacy and Security Overview Data protection Code references Compliance validation Infrastructure security IAM permissions Firewalls, proxies, and data perimeters VPC endpoints (AWS PrivateLink) Guides Overview Language support Learn by playing Migration Migrating from Q Developer Migrating from VSCode Upgrading from Q CLI * Docs * * CLI * * Headless mode Copy page View as Markdown Headless mode Copy page View as Markdown 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 . Info API key authentication is only available for Kiro Pro, Pro+, Pro Max, and Power subscribers. If your subscription is managed by an administrator, they need to enable API key generation first. See API key governance . For details on authentication precedence and checking your active credentials, see Authentication . Info API keys are associated with your user account. Any governance rules configured by your Kiro administrator — including MCP server restrictions, model access policies, and web fetch permissions — apply to headless sessions the same way they apply to interactive ones. Running headless commands Pass --no-interactive along with your prompt: bash 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: bash # 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 yaml 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 bash # 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. Structured output 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. bash 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 ). Flags reference Flag Description --no-interactive Run without an interactive session. Requires a prompt as an argument --output-format stream-json Emit run events as JSON Lines on stdout for programmatic use (V2/V3 only) --trust-all-tools Auto-approve all tool calls without prompting --trust-tools=<categories> Auto-approve specific tool categories (e.g., read , grep , write ) --require-mcp-startup Fail immediately if any MCP server fails to connect 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 Page updated: August 26, 2026 Voice mode ACP