← Back to all projects

KIRO DOCUMENTATION RESEARCH

The Definitive Technical Report on Kiro CLI: Architecture, Operations, and Agentic Workflows

1. Introduction: The Agentic Shift in Terminal Interfaces

The command line interface (CLI) has remained the foundational bedrock of computing for decades, largely unchanged in its fundamental paradigm: a user inputs a discrete command, and the system returns a discrete output. This synchronous, transactional model places the entire cognitive load on the operator, requiring rote memorization of syntax, flags, and pipe logic. However, the emergence of Large Language Models (LLMs) and agentic reasoning capabilities has precipitated a paradigm shift. Kiro CLI represents the vanguard of this shift, transforming the terminal from a passive execution environment into an active, intelligent workspace.1

Kiro CLI is not merely a text-completion engine; it is a comprehensive agentic environment that integrates context awareness, multi-step planning, and autonomous tool execution directly into the shell. By formally replacing the Amazon Q Developer CLI, Kiro has solidified its position as a proprietary, enterprise-grade tool designed to streamline complex development workflows through “Agent Steering” and the “Model Context Protocol” (MCP).2 This report provides an exhaustive technical analysis of Kiro CLI, exploring its cognitive architecture, installation nuances, operational security, and advanced automation capabilities. It is designed for software architects, DevOps engineers, and senior developers seeking to master the next generation of terminal interaction.

1.1. From Amazon Q to Kiro: The Evolution

The transition from Amazon Q Developer CLI to Kiro CLI marks a significant evolution in product identity and capability. While Kiro retains the core DNA of its predecessor—such as deep integration with AWS services and the underlying Bedrock infrastructure—it introduces a distinct focus on “Agentic” workflows.

  • Licensing and Distribution: Kiro adopts a proprietary license, moving away from the Apache license of the Q Developer CLI. This shift accompanies a more robust support model and a free tier for individual developers utilizing a Builder ID.4
  • Feature Parity and Expansion: Kiro maintains feature parity with Q Developer (including authentication via Builder ID and IAM Identity Center) but expands capabilities significantly in areas like Custom Agents, Hooks, and experimental features like “Tangent Mode” and “Checkpoints”.4
  • Community Reception: The developer community has noted the seamless nature of the migration, with existing configurations often transferring without issue, though the rebranding signifies a deeper commitment to the “AI-as-Partner” model rather than just “AI-as-Assistant”.3

1.2. The Core Philosophy: Context, Agency, and Steering

Kiro CLI operates on three foundational pillars that distinguish it from standard shell auto-completers:

  1. Deep Context Awareness: Unlike tools that only see the current command line, Kiro maintains a persistent understanding of the project structure, file contents, git history, and user intent across long sessions. It utilizes a sophisticated tiered memory system to manage the finite context windows of LLMs.8
  2. Autonomous Agency: Kiro is capable of “Subagent” delegation. It can break down a high-level directive (e.g., “Refactor the auth module”) into constituent tasks, spawn sub-processes to research disparate parts of the codebase simultaneously, and execute changes with minimal human intervention.9
  3. Human Steering: Recognizing that “generic” code is often “bad” code in enterprise contexts, Kiro implements “Steering.” This allows teams to inject persistent architectural guidelines (via markdown files) that constrain and guide the AI’s output, ensuring adherence to specific coding standards and business logic.11

—

2. Infrastructure, Installation, and Environment Configuration

The robustness of an AI tool is defined by its ability to operate across diverse environments, from a developer’s local MacBook to a headless Linux server in an air-gapped data center. Kiro CLI’s installation architecture is designed to handle these variances, though it requires specific system configurations for optimal performance.

2.1. Local Workstation Architecture (macOS and Linux)

On local development machines, Kiro CLI acts as a shell wrapper, intercepting user input and managing the display layer (often using a pseudo-terminal or PTY to render rich text and interactive spinners).

macOS Implementation

The macOS installation is streamlined via a shell script (curl -fsSL https://cli.kiro.dev/install bash). This script detects the architecture (Intel vs. Apple Silicon) and pulls the appropriate binary. Post-installation, it modifies the shell profile (.zshrc or .bash_profile) to alias the kiro command and initialize the shell integration, which enables features like “Ghost Text” (inline suggestion) and command history analysis.1

Linux Capability and the glibc Constraint

Linux support is comprehensive but comes with a critical technical dependency: glibc.

  • Standard Build: The primary binary is linked against glibc 2.34 or newer. This covers most modern distributions (Ubuntu 22.04+, Fedora 35+, Amazon Linux 2023).
  • Legacy Support (The Musl Build): For older environments (e.g., CentOS 7, older Debian) or lightweight container distributions (Alpine Linux), the standard binary will fail due to missing symbols. Kiro provides a “musl” build—statically linked against the Musl C library—which removes the dependency on the system’s dynamic linker. This ensures portability across virtually any Linux kernel.12
  • AppImage: For users preferring isolation, Kiro offers an AppImage. This encapsulates the application and all its dependencies (fuse, libs) into a single executable file, requiring only chmod +x to run. This is ideal for immutable infrastructure or systems where the user lacks root privileges to install dependencies.12

2.2. The Headless Server Challenge

A primary use case for Kiro CLI is remote development—editing code directly on a cloud instance via SSH. However, this environment lacks a web browser, creating an authentication deadlock for modern OAuth flows.

The Device Flow Solution

Kiro resolves this using the OAuth 2.0 Device Authorization Grant.

  1. Initiation: The user runs kiro-cli login --use-device-flow on the remote server.
  2. User Code: The server generates a short, verifiable alphanumeric code and displays a verification URL.
  3. Out-of-Band Auth: The user opens this URL on their local laptop (where they have browser access), logs in via their identity provider (GitHub, Google, AWS Builder ID), and enters the code.
  4. Polling: Meanwhile, the remote CLI polls the auth server. Once the user confirms on the laptop, the server issues an access token to the remote CLI, and the session begins.13

SSH Tunneling and Port Forwarding

For Kiro to fully function over SSH, specifically for features that might require callbacks or local server communication, the SSH daemon on the remote host must be configured correctly.

  • AllowStreamLocalForwarding yes: This allows the forwarding of Unix domain sockets. Kiro likely uses this to communicate between its agent process and the shell integration script without exposing TCP ports to the public network.
  • AcceptEnv Q_SET_PARENT: This directive allows the SSH client to pass specific environment variables to the remote session, ensuring that context (like the parent process ID) is correctly maintained across the connection.13

2.3. Enterprise Network Configuration

In corporate environments, direct internet access is often blocked. Kiro CLI respects standard proxy environment variables, ensuring traffic to LLM endpoints (AWS Bedrock, Anthropic API) is routed correctly.

Table 1: Proxy Configuration Matrix 12

Variable Protocol Usage Scenario Example Format
HTTP_PROXY HTTP Unencrypted traffic (rare for APIs) http://proxy.corp.net:8080
HTTPS_PROXY HTTPS Encrypted traffic to AI providers http://user:pass@proxy.corp.net:8080
NO_PROXY Local Bypassing proxy for localhost/internal localhost,127.0.0.1,.local

Best Practice: In “Man-in-the-Middle” (MITM) SSL proxy environments (common in enterprise), ensure the corporate root CA certificate is installed in the system’s trust store, as Kiro’s underlying Rust/Go network stack will validate SSL certificates.

—

3. Cognitive Architecture: Models and Reasoning Strategies

Kiro CLI is not bound to a single “brain.” It employs a flexible cognitive architecture that allows users to balance intelligence, speed, and cost. This section details the model hierarchy and the reasoning strategies employed by the agent.

3.1. The Model Hierarchy

Kiro leverages the Claude family of models from Anthropic, likely served via AWS Bedrock, optimizing them for different operational tiers.15

Table 2: Model Characteristics and Use Cases

Model Cost Factor Intelligence Latency Ideal Use Case
Claude Haiku 4.5 0.4x Medium Very Low Syntax highlighting, simple shell commands, “linting” logic, real-time feedback loops.
Claude Sonnet 4.5 1.3x High Medium General coding, refactoring functions, writing unit tests, debugging standard errors. State-of-the-art on SWE-bench.
Claude Opus 4.5 2.2x Very High High System architecture design, complex cross-file refactoring, understanding obscure legacy code, creative writing.
Auto (Router) 1.0x Variable Variable The default mode. Dynamically routes queries to Haiku or Sonnet based on complexity analysis.

Insight: The “Auto” router is the most economically efficient choice for 90% of users. It effectively acts as a semantic classifier, determining if a prompt requires “deep thought” (Opus/Sonnet) or “fast retrieval” (Haiku). Users should manually override this only when they know a task requires the absolute highest capability (forcing Opus) or lowest cost (forcing Haiku).15

3.2. Subagents and Parallel Processing

One of the most significant architectural innovations in Kiro CLI v1.23+ is the implementation of Subagents. In a standard LLM chat, a single linear conversation history grows indefinitely, eventually consuming the context window and degrading performance (“forgetting” early instructions).

  • The Subagent Solution: When faced with a complex task (e.g., “Map out the dependencies of this entire monorepo”), Kiro can spawn a Subagent. This is an independent LLM session with its own fresh context window.
  • Parallelism: The main agent acts as an orchestrator, delegating tasks to subagents. For example, Subagent A can analyze the frontend code while Subagent B analyzes the backend schema. They run in parallel, and only their summarized findings are reported back to the main agent. This keeps the primary context clean and allows for processing datasets far larger than a single context window could hold.10

3.3. The Planning Agent Workflow

For objectives that are vague or multifaceted, Kiro employs a Planning Agent. This agent operates on a distinct “Reasoning Loop” compared to the standard execution agent.9

  1. Requirements Gathering: The agent initiates a dialogue, asking multiple-choice or open-ended questions to clarify the user’s intent (e.g., “Do you want to use Jest or Mocha for testing?”).
  2. Research & Analysis: It autonomously utilizes tools like grep, glob, and read to explore the codebase and understand the current state.
  3. Plan Generation: It outputs a structured implementation plan, broken down into atomic steps (e.g., “Step 1: Create interface”, “Step 2: Implement mock”, “Step 3: Update controller”).
  4. Handoff: Only after the user approves the plan does it hand off control to the Execution Agent, which processes the steps sequentially.

This separation of “Thinking” (Planning) and “Doing” (Execution) significantly reduces the error rate in complex coding tasks.

—

4. Context Management Engineering

The “Context Window” is the scarcest resource in modern AI. Kiro CLI implements a sophisticated context management strategy that moves beyond simple First-In-First-Out (FIFO) buffers, utilizing a tiered approach to maximize relevance.8

4.1. The Tiered Context Architecture

Tier 1: Session Context (Ephemeral)

This is the immediate working memory. It contains the current chat history and any files explicitly added via /context add.

  • Behavior: It is volatile and disappears when the session ends.
  • Cost: Consumes tokens immediately.
  • Usage: Debugging a specific error log, or working on a temporary script.8

Tier 2: Agent Resources (Persistent)

This represents the “Long Term Memory” of a specific agent. Defined in the agent’s configuration file under resources, these files are loaded every time the agent starts.

  • Mechanism: Using file:// URIs (e.g., file://README.md, file://docs/api_spec.md).
  • Usage: Project standards, architecture diagrams, and “Steering” documents. This ensures the agent never “forgets” the core rules of the project.8

Tier 3: Knowledge Bases (Retrieval-Augmented Generation)

When a project exceeds the context limit (e.g., >10MB or thousands of files), “stuffing” the context is impossible. Kiro utilizes Knowledge Bases.

  • Mechanism: Kiro indexes the codebase into a vector database (likely local or cloud-synced depending on config).
  • Semantic Search: When a user asks a question, Kiro performs a semantic search against this index, retrieving only the relevant chunks of code.
  • Efficiency: This allows the agent to “know” about a 1GB codebase while only loading 10KB of relevant text into the model’s context window.
  • Trigger: Users enable this via kiro-cli settings chat.enableKnowledge true.6

4.2. Git-Awareness and Temporal Context

Kiro CLI is deeply integrated with Git. It does not just see the files; it sees the history.

  • Diff Awareness: Kiro can analyze git diff to understand exactly what changes the user has made since the last commit. This is crucial for generating commit messages or reviewing code.
  • Branch Awareness: It knows which branch is active, helping it understand if it is working on a feature branch or production.17
  • Implication: This prevents hallucinations where the AI suggests editing a file that was deleted in a recent commit, or fails to notice a merge conflict.

4.3. Context Hygiene Best Practices

Managing context is an active engineering task.

  1. Use .gitignore: Kiro respects .gitignore by default. Ensure irrelevant large files (logs, binaries, node_modules) are ignored to prevent them from polluting the context or vector index.
  2. Explicit Context Removal: Use /context remove or /context clear when switching tasks within the same session. Carrying over context from a “Frontend debugging” task to a “Backend SQL optimization” task will confuse the model.8
  3. Monitoring: Regularly use /context show to visualize token usage. If the context is >75% full, performance (latency and accuracy) will degrade.

—

5. Tooling, Capabilities, and Permissions

An agent is only as powerful as the tools it can wield. Kiro CLI exposes a rich set of built-in tools and a robust permission system to govern them.

5.1. Built-in Toolset

Kiro comes pre-equipped with foundational tools that allow it to interact with the OS and the web.

Table 3: Core Built-in Tools 19

Tool Functionality Default Permission
read Reads file contents. Trusted (in local cwd)
write Creates or overwrites files. Prompt (Requires confirmation)
shell Executes bash/zsh commands. Prompt (Requires confirmation)
glob Finds files matching patterns. Trusted
grep Searches file contents via regex. Trusted
aws Executes AWS CLI commands. Prompt
web_fetch Retrieves URL content (max 10MB). Prompt
report Opens GitHub issue template. Trusted

Insight: The distinction between glob/grep (Trusted) and shell (Prompt) is a deliberate security design. The AI can look for information autonomously to answer a user’s question, but it cannot change the state of the system or execute arbitrary code without explicit human approval.

5.2. The Permission System: Trust vs. Safety

Kiro implements a “Human-in-the-Loop” security model.

  • Per-Request Mode: By default, every time the agent wants to use a sensitive tool (like write or shell), it pauses and asks the user: “I want to run npm install. Allow? (y/n)”.
  • Trusting Tools: For high-velocity sessions, a user can relax these constraints using the /tools trust <tool> command. For example, /tools trust shell allows the agent to execute commands autonomously for the duration of the session.
  • The Danger Zone: The command /tools trust-all removes all safeguards. While convenient, it is highly discouraged, especially in environments with production access, as a hallucinating AI could theoretically execute destructive commands.20

5.3. Slash Commands: The Control Plane

Slash commands provide the interface for managing the session and the agent’s behavior.

  • /chat: Manages session history (resume, save, load).
  • /model: Switches the underlying cognitive model (e.g., from Auto to Opus).
  • /agent: Switches the active persona (e.g., from Default to “Security Auditor”).
  • /context: Manages the ephemeral memory tier.
  • /tangent: (Experimental) Enters a side-conversation stack.
  • /code: Manages the Language Server Protocol (LSP) integrations for code intelligence.21

5.4. Multimodal Capabilities

Kiro CLI is not limited to text. It supports multimodal input, specifically images. Users can drag and drop images into the terminal (supported in modern terminal emulators) or use the /paste command to insert an image from the clipboard.

  • Use Case: A developer can take a screenshot of a UI bug or a complex cloud architecture diagram and ask Kiro: “Analyze this diagram and generate the Terraform code to deploy it.” The model (likely Sonnet or Opus) processes the visual data and converts it into structural code.22

—

6. Extending Capabilities via Model Context Protocol (MCP)

The Model Context Protocol (MCP) is the architectural bridge that transforms Kiro from a “File Editor” into a “System Integrator.” MCP is an open standard that decouples the AI agent from the tool implementation, allowing Kiro to connect to any external system—databases, cloud APIs, issue trackers—without needing custom hardcoded logic in the CLI binary.24

6.1. The MCP Architecture

  • Host: Kiro CLI acts as the MCP Host.
  • Server: Lightweight processes (written in Python, Node.js, etc.) that expose Resources (data), Prompts (templates), and Tools (functions).
  • Transport: Communication occurs over stdio (standard input/output), meaning the MCP server runs locally as a subprocess of Kiro, inheriting its environment context.24

6.2. Configuring MCP Servers

MCP servers are defined in mcp.json files, which can exist at the global level (~/.kiro/settings/mcp.json) or workspace level (.kiro/settings/mcp.json).

Deep Dive: Configuration Structure

JSON

{
“mcpServers”: {
“postgres-local”: {
“command”: “uvx”,
“args”: [“mcp-server-postgres”, “postgresql://user:pass@localhost:5432/mydb”],
“disabled”: false,
“env”: {
“PGSSLMODE”: “disable”
}
},
“github-integration”: {
“command”: “npx”,
“args”: [“-y”, “@modelcontextprotocol/server-github”],
“env”: {
“GITHUB_TOKEN”: “ghp_xxxxxxxxxxxx”
}
}
}
}

In this configuration:

  1. Postgres: The agent gains the ability to query the local database. It can inspect schemas (“What tables are in this DB?”) and write complex SQL queries.
  2. GitHub: The agent can read issues, check PR status, and search the repo history remotely.24

6.3. Advanced MCP Governance

In enterprise settings, allowing an AI to connect to arbitrary databases or APIs is a risk. Kiro supports MCP Governance via the MCP Registry.

  • Registry Support: Organizations can host private MCP registries.
  • Policy Enforcement: Administrators can define which MCP servers are allowed, mandating that only approved, security-audited servers are loaded by the CLI.
  • Scoping: MCP servers can be scoped. A “Production Database” MCP server might be restricted to specific high-privilege agents or require stricter approval flows than a “Local Dev” server.9

—

7. Custom Agents and Steering: Engineering the Persona

While the default agent is capable, “Custom Agents” combined with “Steering” allow for the creation of specialized virtual engineers. This is where Kiro shifts from a tool to a platform.

7.1. Anatomy of a Custom Agent

Custom agents are defined in JSON files in .kiro/agents/. They are not just prompts; they are runtime configurations.

Example: The “Security Auditor” Agent

JSON

{
“name”: “sec-auditor”,
“description”: “Specialist in identifying OWASP vulnerabilities.”,
“model”: “claude-opus-4.5”,
“prompt”: “You are a rigid security auditor. Focus solely on input validation, auth flows, and secret management.”,
“tools”: [“read”, “grep”, “report”],
“allowedTools”: [“read”, “grep”],
“resources”: [“file://docs/security_standards.md”],
“mcpServers”: [“sonar-qube-connector”]
}

  • Model Selection: Forces the use of “Opus” for maximum reasoning depth, even if it’s slower.
  • Tool Restriction: This agent cannot write files or execute shell commands. It is read-only by design, preventing accidental modification during an audit.
  • Resource Injection: It automatically loads the company’s specific security standards into context.26

7.2. Steering: The Psychology of Compliance

Steering involves influencing the AI’s behavior via persistent markdown files in .kiro/steering/.

  • product.md: Defines the Intent. “This application is a fintech banking portal. Accuracy and transaction safety are prioritized over performance.”
  • tech.md: Defines the Constraints. “Use TypeScript strict mode. Do not use any. Use zod for validation.”
  • structure.md: Defines the Topology. “All database logic resides in /src/db. Controllers must be thin.”

Best Practice: Write steering files in “Positive Constraint” language. Instead of saying “Don’t write bad code,” say “Ensure all async functions utilize try/catch blocks with structured logging.” The AI follows explicit structural patterns better than negative prohibitions.11

—

8. Automation and Hooks: The Nervous System

Hooks allow Kiro CLI to react to events. They act as the nervous system, triggering reflexes based on the agent’s actions. This enables the “Best Practices Boilerplate” methodology, where automation enforces quality constraints.28

8.1. The Hook Lifecycle

Hooks are scripts triggered by specific events:

  • AgentSpawn: When the agent starts.
  • PreToolUse: Before a tool runs (Blocking).
  • PostToolUse: After a tool runs (Non-blocking).
  • UserPromptSubmit: When the user types.

8.2. The Three-Tier Automation Strategy

To balance automation with performance, Kiro recommends a tiered hook strategy 28:

Tier 1: Automatic (Safety & Formatting)

  • Trigger: PostToolUse (specifically on write).
  • Action: Run prettier --write on the changed file. Run eslint --fix.
  • Benefit: The code generated by the AI is instantly formatted and linted before the user even reviews it.

Tier 2: Manual (Process & Documentation)

  • Trigger: User Intent (via slash command or specific prompt).
  • Action: Generate a commit message based on git diff. Run a spell-check on README.md.
  • Benefit: Automates administrative overhead.

Tier 3: Deep Analysis (Quality & Security)

  • Trigger: PreToolUse (on aws or shell deployment commands).
  • Action: Run a comprehensive security scan (e.g., trivy or bandit).
  • Blocking: If the scan fails, the hook returns exit code 2, blocking the deployment and forcing the AI to fix the vulnerability first.

8.3. Designing a Security Blocking Hook

A simple yet critical hook is the “Command Sanitizer.”

  • Hook: PreToolUse on shell.
  • Logic: A python script receives the command as stdin. If the command contains rm -rf /, drop database, or other destructive patterns, it exits with an error.
  • Result: The AI receives the error “Command Blocked by Policy” and must propose a safer alternative.29

—

9. Advanced Workflows: Spec-Driven Development and Property-Based Testing

Kiro CLI enables methodologies that were previously too labor-intensive for rapid development cycles.

9.1. Spec-Driven Development (SDD)

SDD flips the coding process: write the docs first, code second.

  1. Requirements (requirements.md): The user writes a high-level need.
  2. Design (design.md): The Planning Agent generates a technical design, validating it against tech.md.
  3. Tasking (tasks.md): The Plan Agent breaks the design into atomic units.
  4. Implementation: The Execution Agent iterates through tasks.md, marking them as done.
    • Why Kiro? Kiro maintains the alignment between the code and the spec. If the implementation drifts from the requirements.md, Kiro can detect this discrepancy during its review cycle.30

9.2. Property-Based Testing (PBT) - The “Yellow Prince” Case Study

Property-Based Testing involves defining general “truths” about a system and letting the computer generate thousands of random inputs to find edge cases.

  • The Scenario: In a game engine (“Yellow Prince”), a rule states: “If a player moves from Room A to Room B, they must be able to move back to Room A.”
  • The Implementation: Instead of writing one test case, the user asks Kiro: “Write a PBT suite for the movement logic.” Kiro generates a test using a library like Hypothesis (Python) or FsCheck (.NET).
  • The Bug: The PBT suite runs 100 random room layouts. It finds a scenario where a one-way door traps the player.
  • The Fix: Kiro analyzes the “shrunk” counter-example (the minimal failing case) and patches the World.Build() logic to ensure bidirectional linking.
  • Impact: This finds bugs that a human writing manual unit tests would never anticipate.32

9.3. Tangent Mode and Checkpoints (Experimental)

  • Tangent Mode (/tangent): Allows the user to fork the conversation. If you are deep in a refactor but need to ask “How does Python’s asyncio work again?”, you hit Tangent Mode. You ask the question, get the answer, and exit. The main context stack is unaffected by this detour, preserving token space.6
  • Checkpoints: This features snapshots the filesystem state. Before a risky refactor, the user creates a checkpoint. If the AI hallucinates and breaks the build, the user can instantly rollback the filesystem to the clean state, functioning like a local, ephemeral Git commit.6

—

10. Troubleshooting, Logging, and Maintenance

Maintaining a healthy AI workflow requires diagnostics.

10.1. The doctor Command

kiro-cli doctor is the first line of defense. It checks:

  • Shell Integration: Is the script sourced in .zshrc?
  • Auth: Is the token valid?
  • Connectivity: Can it reach bedrock.us-east-1.amazonaws.com?
  • Permissions: Can it write to ~/.kiro?
    Running kiro-cli doctor --strict is recommended for CI/CD pipelines to fail fast on configuration drift.14

10.2. Log Analysis

Logs are typically stored in $TMPDIR/kiro-log/ (Mac) or /tmp/kiro-log/ (Linux).

  • Verbose Mode: Running kiro-cli -vvv enables trace-level logging. This is essential for debugging OAuth Device Flow issues or SSH port forwarding failures, revealing the raw handshake data.
  • LSP Logs: /code logs reveals the internal state of the Language Server. If “Go to Definition” fails, these logs will show if the underlying gopls or pyright server has crashed.33

—

11. Conclusion

Kiro CLI creates a new category of developer tooling. It is not an IDE plugin, nor is it a simple CLI wrapper. It is an Agentic Runtime Environment. By combining the reasoning power of models like Claude Opus with the execution capabilities of the shell and the governance of Steering and Hooks, it allows for a “Human-Commander, AI-Executor” workflow.

For the modern developer, mastering Kiro CLI is not just about learning commands; it is about learning to manage Context, define Constraints, and architect Agents. The transition from manual coding to steering autonomous agents is the future of software engineering, and Kiro CLI provides the foundational infrastructure to make that future accessible today.

Works cited

  1. Get started - CLI - Docs - Kiro, accessed December 22, 2025, https://kiro.dev/docs/cli/
  2. aws/amazon-q-developer-cli: Agentic chat experience in your terminal. Build applications using natural language. - GitHub, accessed December 22, 2025, https://github.com/aws/amazon-q-developer-cli
  3. Kiro Did It: Kiro Goes GA - And Replaces My Favorite CLI! - DEV Community, accessed December 22, 2025, https://dev.to/bhatiagirish/kiro-did-it-kiro-goes-ga-and-replaces-my-favorite-cli-5ec9
  4. Upgrading from Amazon Q Developer CLI - CLI - Docs - Kiro, accessed December 22, 2025, https://kiro.dev/docs/cli/migrating-from-q/
  5. Using Amazon Q Developer on the command line, accessed December 22, 2025, https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line.html
  6. Experimental features - CLI - Docs - Kiro, accessed December 22, 2025, https://kiro.dev/docs/cli/experimental/
  7. What’s difference between Amazon Q developer CLI and Kiro CLI : r/aws - Reddit, accessed December 22, 2025, https://www.reddit.com/r/aws/comments/1p1o3i6/whats_difference_between_amazon_q_developer_cli/
  8. Context management - CLI - Docs - Kiro, accessed December 22, 2025, https://kiro.dev/docs/cli/chat/context/
  9. Subagents, Plan Agent, Grep/Glob Tools, and MCP Registry - Kiro, accessed December 22, 2025, https://kiro.dev/changelog/subagents-plan-agent-grep-glob-tools-and-mcp-registry/
  10. Changelog - Kiro, accessed December 22, 2025, https://kiro.dev/changelog/
  11. Steering - CLI - Docs - Kiro, accessed December 22, 2025, https://kiro.dev/docs/cli/steering/
  12. Privacy and security - CLI - Docs - Kiro, accessed December 22, 2025, https://kiro.dev/docs/cli/privacy-and-security/
  13. The essential guide to installing Amazon Q Developer CLI on Linux …, accessed December 22, 2025, https://dev.to/aws/the-essential-guide-to-installing-amazon-q-developer-cli-on-linux-headless-and-desktop-3bo7
  14. CLI commands - CLI - Docs - Kiro, accessed December 22, 2025, https://kiro.dev/docs/cli/reference/cli-commands/
  15. Model selection - CLI - Docs - Kiro, accessed December 22, 2025, https://kiro.dev/docs/cli/chat/model-selection/
  16. accessed December 31, 1969, https://kiro.dev/docs/cli/chat/subagents/
  17. Trusted Git Context for AI Agents & IDEs - GitKraken MCP, accessed December 22, 2025, https://www.gitkraken.com/mcp
  18. Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more. - GitHub, accessed December 22, 2025, https://github.com/yamadashy/repomix
  19. Built-in tools - CLI - Docs - Kiro, accessed December 22, 2025, https://kiro.dev/docs/cli/reference/built-in-tools/
  20. Managing tool permissions - CLI - Docs - Kiro, accessed December 22, 2025, https://kiro.dev/docs/cli/chat/permissions/
  21. Slash commands - CLI - Docs - Kiro, accessed December 22, 2025, https://kiro.dev/docs/cli/reference/slash-commands/
  22. Bring Kiro agents to your terminal with Kiro CLI, accessed December 22, 2025, https://kiro.dev/blog/introducing-kiro-cli/
  23. accessed December 31, 1969, https://kiro.dev/docs/cli/chat/images/
  24. Model Context Protocol (MCP) - CLI - Docs - Kiro, accessed December 22, 2025, https://kiro.dev/docs/cli/mcp/
  25. Kiro Agentic AI IDE: Beyond a Coding Assistant - Full Stack Software Development with Spec Driven AI AWS re:Post, accessed December 22, 2025, https://repost.aws/articles/AROjWKtr5RTjy6T2HbFJD_Mw/%F0%9F%91%BB-kiro-agentic-ai-ide-beyond-a-coding-assistant-full-stack-software-development-with-spec-driven-ai
  26. Creating custom agents - CLI - Docs - Kiro, accessed December 22, 2025, https://kiro.dev/docs/cli/custom-agents/creating/
  27. Agent configuration reference - CLI - Docs - Kiro, accessed December 22, 2025, https://kiro.dev/docs/cli/custom-agents/configuration-reference/
  28. Accelerating AI Development Workflows: The Kiro Best Practices …, accessed December 22, 2025, https://dev.to/kirodotdev/accelerating-ai-development-workflows-the-kiro-best-practices-boilerplate-4h6o
  29. Hooks - CLI - Docs - Kiro, accessed December 22, 2025, https://kiro.dev/docs/cli/hooks/
  30. Automating made easy with Kiro CLI - DEV Community, accessed December 22, 2025, https://dev.to/aws/automating-made-easy-with-kiro-cli-1p78
  31. Best practices - IDE - Docs - Kiro, accessed December 22, 2025, https://kiro.dev/docs/specs/best-practices/
  32. Building Smarter With Kiro: A Hands-On Look at Property-Based …, accessed December 22, 2025, https://medium.com/@codingmatheus/building-smarter-with-kiro-a-hands-on-look-at-property-based-testing-76fab8f00cc4
  33. Code Intelligence - CLI - Docs - Kiro, accessed December 22, 2025, https://kiro.dev/docs/cli/code-intelligence/

Key Points on Kiro CLI

  • Kiro CLI is an AI-powered terminal tool from AWS that serves as a successor to Amazon Q Developer CLI, offering backwards compatibility but with enhanced features like agentic workflows and spec-driven development.
  • It excels in automating coding tasks, debugging, and infrastructure management, but research suggests it performs best when users provide detailed context and break complex problems into smaller steps to avoid inconsistent results.
  • Evidence leans toward strong integration with AWS services via MCP (Model Context Protocol), making it suitable for cloud-based workflows, though it may require careful configuration for non-AWS environments.
  • The tool supports multimodal inputs like images and handles experimental features for advanced use, but users should be diplomatic about its limitations, such as occasional need for manual intervention in debugging.

Overview of Core Functionalities

Kiro CLI allows interactive AI chats in the terminal, where you describe tasks in plain language, and the AI generates code, plans projects, or automates workflows. It uses models like Claude Sonnet 4.5 for reasoning, with an “Auto” mode that balances cost and performance. Built-in tools handle file reading/writing, shell commands, AWS interactions, and web searches, all configurable for security.

Getting Started and Basic Usage

Install via a curl script for macOS/Linux, then run kiro-cli to start a chat. Authenticate with GitHub, Google, or AWS accounts. For simple tasks, type queries like “Generate a Python script to fetch weather data.” Use slash commands (e.g., /help) for quick actions like switching models or managing sessions. For AWS users, it seamlessly replaces Q CLI with a single update command.

Tips for Effective Control

Control access by trusting tools (e.g., /tools trust read) to skip confirmations, but start restrictive for security. Customize via settings (e.g., kiro-cli settings chat.defaultModel claude-sonnet-4.5) and monitor context usage to avoid token limits. For remote SSH servers, run Kiro CLI directly on the server after installation, leveraging built-in shell tools for local execution—avoid piping sensitive data across connections.

Ideas for Practical Applications

Use it for quick automations like link replacements in markdown files or GitHub stats fetching. For complex workflows, combine planning agents for task breakdowns with subagents for parallel execution (e.g., analyzing multiple API endpoints simultaneously). In data science, generate reproducible pipelines; in web dev, scaffold React apps with spec-driven planning to ensure alignment with requirements.

Comprehensive Guide to Kiro CLI: Functionalities, Best Practices, and Advanced Workflows

Kiro CLI, developed by AWS as a successor to Amazon Q Developer CLI, represents a significant evolution in AI-assisted terminal-based development tools. Released in its general availability form around November 2025, it integrates agentic AI capabilities to handle everything from simple code generation to complex, multi-step automations. This guide synthesizes information from official documentation, changelogs, and community articles to provide a thorough explanation of its functionalities, practical tips, best practices, and creative ideas for usage. It covers controlling the tool, building complex workflows, integrating with remote SSH servers, and exploring its full potential across domains like web development, data science, and cloud infrastructure.

Core Architecture and Setup

Kiro CLI operates as an interactive chat interface in the terminal, powered by models from the Claude family (e.g., Haiku 4.5 for speed, Opus 4.5 for complex reasoning). The “Auto” mode, recommended for most users, intelligently routes tasks to optimize cost (up to 23% savings over Sonnet 4) while maintaining quality. Installation is straightforward on macOS/Linux via curl -fsSL https://cli.kiro.dev/install | bash, with authentication supporting GitHub, Google, AWS Builder ID, or IAM Identity Center for enterprise use.

Configuration spans global (~/.kiro/), project (.kiro/), and agent scopes, with priorities resolving conflicts (e.g., project overrides global). Use kiro-cli settings to manage options like chat.defaultModel or telemetry.enabled. For upgrades from Q CLI, run q update for seamless migration, preserving MCP configs.

Table: Configuration Scopes and Examples

Scope Location Use Case Example Priority in Conflicts
Global ~/.kiro/ Default model for all projects Lowest
Project .kiro/ Workspace-specific MCP servers Medium
Agent .kiro/agents/ Tool permissions for a debugging agent Highest

Key Functionalities

Kiro CLI’s capabilities are divided into chat interactions, agents, tools, and extensions.

  1. Interactive Chat and Model Management
    • Start with kiro-cli chat for natural-language queries (e.g., “Build a REST API for user authentication”). Supports multimodal inputs like images via /paste.
    • Model selection: Switch via /model (e.g., Haiku for speed at 0.4x cost, Opus for advanced tasks at 2.2x). Set defaults with /model set-current-as-default.
    • Context management: Add files/patterns with /context add (e.g., src/**/*.js); view with /context show. Compact long conversations via /compact.
  2. Agents and Subagents
    • Custom Agents: Create via /agent generate or kiro-cli agent create --name <name>, configuring tools, prompts, and resources in JSON. Examples include backend-specialist for API tasks or aws-expert for infrastructure. Switch with /agent swap or start via --agent <name>.
    • Planning Agent: Activated by /plan or Shift+Tab; gathers requirements interactively, researches codebases, and hands off structured plans to execution agents. Operates read-only.
    • Subagents: Run parallel tasks with progress (e.g., analyzing multiple endpoints); default subagent handles general work.
  3. Built-in Tools and Permissions
    • Core tools: read/write for files, shell for commands, aws for CLI calls, web_search/web_fetch for internet access. grep/glob for fast searches respecting .gitignore.
    • Manage permissions with /tools (e.g., /tools trust-all); configure restrictions like allowedPaths in agent JSON.
    • Code Intelligence: Initialize LSP servers with /code init for go-to-definition, diagnostics, etc., supporting languages like TypeScript, Rust, Python.
  4. Model Context Protocol (MCP)
    • Extends tools with external servers (e.g., AWS docs, GitHub, PostgreSQL). Configure in mcp.json; examples include searching AWS docs or managing GitHub issues.
    • Governance: Control toolsets via env variables; security via fine-grained tokens.
  5. Steering and Persistent Context
    • Use .kiro/steering/ markdown files (e.g., tech.md for frameworks, api-standards.md for conventions) to enforce patterns across sessions. Global vs. workspace scopes for team consistency.
  6. Experimental Features
    • Knowledge Management: Semantic search over files/PDFs with /knowledge.
    • Tangent Mode: Explore side topics without polluting main context (Ctrl+T).
    • TODO Lists: Auto-generate and manage with /todo.
    • Thinking Tool: Shows step-by-step reasoning.
    • Checkpointing: Snapshot changes for rollback with /checkpoint.
    • Delegate: Background tasks with progress monitoring. Toggle via /experiment.
  7. CLI Commands and Slash Commands
    • Core: kiro-cli chat for sessions, kiro-cli translate for shell commands from natural language, kiro-cli doctor for diagnostics.
    • Slash: /agent for management, /mcp to list servers, /changelog for updates.

Tips and Best Practices

  • Security: Use per-request permissions for sensitive tools like shell or aws; review tool usage logs. Avoid /tools trust-all in production.
  • Performance: Start with Auto model; monitor credits with /usage. For large codebases, initialize LSP early.
  • Prompting: Provide rich context (logs, diffs, screenshots); use EARS format for specs (e.g., “WHEN [condition] THEN THE SYSTEM SHALL [behavior]”). Iterate prompts for refinements.
  • Maintenance: Update via kiro-cli update; use kiro-cli diagnostic for issues. Report bugs with /issue.
  • Team Use: Share steering files and agents in repos for consistency; use global scopes for organization-wide standards.

Ideas for Usage and Complex Workflows

  • Spec-Driven Development: For apps like weather forecasts, start with specs to generate requirements, designs, and tasks; implement via agents. Workflow: Define EARS rules → Refine design → Execute tasks → Deploy with Terraform via MCP.
  • Property-Based Testing (PBT): Write specs, run PBT with “Run property-based tests for [spec]”; fix failures via counterexamples. Ideal for data science pipelines or algorithms.
  • Automation and Debugging: Automate link replacements or GitHub stats fetching; debug with full context (logs, diffs). Complex flow: Use planning agent → Subagents for parallel debugging → Delegate background logs analysis.
  • AWS Integration: Manage infrastructure with aws tool or MCP (e.g., query docs, pricing). Workflow: Spec policy → Use automated reasoning for validation → Deploy via CDK hooks.
  • Data Science and AI Workflows: Generate ML pipelines or property tests; use knowledge bases for semantic search over datasets/PDFs.
  • Open Source Contributions: Analyze repos via MCP GitHub server; generate PRs with specs.
  • Remote SSH Servers: Install Kiro CLI on the server (via curl); run chats for local tasks. For hybrid: Use delegate for background remote commands via shell tool (e.g., ssh user@host 'command'), but secure with allowedCommands restrictions. Complex: Plan agent on local → Execute via subagents piping to SSH.
  • Boilerplate and Hooks: Use best practices boilerplate for auto-testing/linting on save; customize hooks for CI/CD integration. Workflow: Trigger hooks on file events → Parallel subagents for builds → Checkpoint for rollbacks.

Table: Example Complex Workflow for AWS App Deployment

Step Functionality Used Details
1. Planning Planning Agent Gather requirements interactively; generate step-by-step plan.
2. Context Setup Steering + Knowledge Load tech.md for AWS standards; index PDFs for API docs.
3. Execution Custom Agent + MCP Use aws-expert agent; query pricing via MCP for cost estimates.
4. Parallel Tasks Subagents + Delegate Run background Terraform validation; parallel code generation for Lambda/CloudFront.
5. Testing Hooks + PBT Auto-test on save; run property tests on specs.
6. Deployment Shell Tool + Checkpoint Execute CDK deploy; snapshot changes for rollback.
7. Monitoring Tangent Mode Explore side issues (e.g., logs) without disrupting main flow.

Kiro CLI shines in structured, agentic development but requires thoughtful prompting and configuration for optimal results.

Key Citations