Kiro CLI headless mode tackles a familiar friction point in AI-assisted tooling: authentication that assumes a browser is always available. The CLI’s usual flow—kiro-cli login opening a browser—works fine at a desk, but it’s awkward (or impossible) in CI/CD, cron jobs, container builds, and other automated environments. Headless mode replaces that interactive step with a single environment variable: set KIRO_API_KEY, and the CLI skips browser-based login entirely.
Headless mode, in practical terms
The mechanics are as follows: an API key is generated from the Kiro web app, then provided to the CLI via KIRO_API_KEY. With that present, Kiro CLI runs non-interactively without any extra config files, swapping a “human in front of a browser” assumption for something that fits typical pipeline environments.
Example: a code review agent that runs on every push
The post’s main walkthrough pairs headless auth with a concrete automation pattern: a custom agent definition + a GitHub Actions workflow.
Defining a custom agent in-repo
Kiro agents can be checked into a repository as JSON—described as a “persona” with a job, tool access, and behavioral instructions. The example drops a code reviewer into:
.kiro/agents/code-reviewer.json
Two implementation details stand out:
- The
promptfield drives how the agent behaves, including acting like a senior reviewer and organizing findings by severity. - Tool access is explicitly controlled:
toolsenumerates what the agent can use, whileallowedToolsdefines what it can run without confirmation—important for unattended CI where “ask to proceed” isn’t an option.
Wiring it into GitHub Actions
To run the review on every push, the post stores the API key as a repository secret named KIRO_API_KEY (under GitHub’s Actions secrets). The workflow is then added at:
.github/workflows/kiro-code-review.yml
The pipeline:
- Installs using
curl -fsSL [https://cli.kiro.dev/install](https://cli.kiro.dev/install) | bash. - Runs the review uses
--no-interactiveso the CLI prints output to stdout and exits instead of starting an interactive session. KIRO_API_KEYpicks up automatically from the environment
There’s also a practical security note: with workflows and agent configs living in-repo, branch protection on main matters, since anyone who can push directly could modify the agent behavior or the CI workflow itself.
What the review output looks like
In the demo, the agent reviews a sample Flask app, exploring the repo and reading source files and templates before returning a categorized report. The sample findings include: a hardcoded SECRET_KEY, an XSS issue involving Jinja2’s |safe filter, and even smaller correctness problems like an HTML typo. The report is grouped by severity with counts (critical, warnings, suggestions).
Beyond code review: the broader automation pattern
The same building blocks—API key + custom agent + one-liner in CI—are positioned as reusable for other workflows, including:
- Documentation generation on merges
- Dependency audits for outdated or vulnerable packages
- Migration assistance to identify patterns needing updates
- PR summaries for human-readable change overviews
In other words, headless mode isn’t a separate feature so much as the missing piece that lets Kiro CLI operate cleanly where interactive auth previously blocked it.