Migrating from Amazon Q CLI to Kiro CLI: A Practical Guide

Overview

This tutorial guides you through migrating from the recently sunset Amazon Q CLI to Kiro CLI, a more powerful and extensible terminal AI assistant. Unlike a simple 1:1 replacement, Kiro CLI offers custom agents, steering files, MCP server integration, and planning mode—features that address long-standing limitations of its predecessor. By following this guide, you'll not only replicate your existing workflows but significantly enhance your terminal productivity.

Prerequisites

What You'll Need

• An AWS account with access to an EC2 instance (or local Linux/macOS environment)
• Basic familiarity with command-line interfaces and AWS services
• A Kiro CLI license (free tier available for limited usage)
• Node.js version 18 or higher installed
• Permission to install system packages (e.g., sudo access on EC2)

Step-by-Step Instructions

1. Installing Kiro CLI

The recommended installation method uses npm. On your EC2 instance, run:

sudo npm install -g kiro-cli

Verify the installation:

kiro --version

If you encounter permission errors, consider using nvm to manage Node versions without sudo. Alternatively, download the standalone binary from the official releases page.

2. Authenticating with Your License

Kiro CLI requires a license key for full functionality. After purchasing or signing up for the free tier:

kiro auth login

Follow the interactive prompts to paste your key. For headless EC2 environments, you can set the KIRO_API_KEY environment variable:

export KIRO_API_KEY=your-key-here

3. Setting Up Steering Files

Steering files are YAML documents that define persistent rules for AI responses. Create a directory for your project:

mkdir -p ~/.kiro/steering && cd ~/.kiro/steering

Create a file called team-standards.yaml with your organization's best practices:

rules:
  - context: ec2
    instructions: "Always recommend Graviton instances (ARM64) unless explicitly requested otherwise."
  - context: ebs
    instructions: "Default volumes should be gp3. If io2 is requested, verify IOPS requirements."
  - context: tagging
    instructions: "Mandatory tags: Environment, Project, CostCenter, Owner"
  - context: lambda
    instructions: "Prefer ARM64 architecture, set memory between 128-3008 MB, and enable X-Ray tracing."

Load the steering file at startup:

echo "steering: ~/.kiro/steering/team-standards.yaml" >> ~/.kiro/config.yaml

4. Creating Custom Agents

Custom agents let you define specialized personas with restricted tool access and scoped permissions. To create a DevOps agent that only touches infrastructure files, create a file ~/.kiro/agents/devops.yaml:

name: DevOps Engineer
system_prompt: "You are a senior DevOps engineer. You may only modify files in /infrastructure/ and /terraform/. Never edit application code."
tools:
  - aws-cli
  - terraform
  - kubectl
  - docker
file_restrictions:
  allowed_paths:
    - /infrastructure/
    - /terraform/
  forbidden_patterns:
    - "*.js"
    - "*.py"
    - "src/"
parameters:
  temperature: 0.2
  max_tokens: 2000

Create a reviewer agent that cannot modify files:

name: Code Reviewer
system_prompt: "You are a thorough code reviewer. Read files, analyze them, and provide feedback. Under no circumstances may you write or modify any file."
tools:
  - read-file
  - list-directory
file_restrictions:
  read_only: true
parameters:
  temperature: 0.1
  max_tokens: 4000

Activate an agent with:

kiro agent use devops

5. Connecting MCP Servers for Real AWS Data

MCP (Model Context Protocol) servers allow Kiro to query live AWS services. Install the official AWS Cost Explorer MCP server:

kiro mcp install github:KiroAI/aws-cost-mcp

Configure credentials by editing ~/.kiro/mcp.yaml:

servers:
  aws-cost:
    region: us-east-1
    profile: default
  pricing:
    region: us-west-2
    profile: default

Test the connection:

kiro "Show me my top 5 services by spend last month"

This will pull real data from AWS Cost Explorer, not make estimates.

6. Using Planning Mode for Structured Tasks

Planning mode helps you gather requirements before execution. Press Shift+Tab to toggle between normal and planning modes. In planning mode, you can issue commands like:

kiro_plan "Design a VPC architecture for a microservices application"

Kiro will ask clarifying questions about CIDR blocks, subnets, routing, and security groups before generating Terraform code. Accept or modify the plan, then execute.

Common Mistakes

Mistake 1: Not Configuring AWS Credentials for MCP Servers

If MCP servers can't access AWS, you'll get generic responses instead of real data. Always verify your AWS CLI profile is correctly set in ~/.kiro/mcp.yaml. Test with a simple query like kiro "List my S3 buckets".

Mistake 2: Overly Permissive Agent Permissions

Creating agents without file restrictions can lead to accidental modification of non-infrastructure files. Start with strict allowed_paths and forbidden_patterns. You can always expand later.

Mistake 3: Ignoring Steering File Conflicts

Multiple steering files can create contradictory instructions. Use separate files for separate contexts (e.g., one for EC2, one for Lambda) and ensure the loading order is consistent. Test with a simple prompt to verify behavior.

Mistake 4: Forgetting to Activate the Correct Agent

After creating agents, you must explicitly switch to them using kiro agent use <name>. The default agent has no restrictions. Create an alias to always start with your DevOps agent.

Summary

This migration from Amazon Q CLI to Kiro CLI is more than a forced upgrade—it's an opportunity to gain custom agents, persistent steering rules, real-time AWS data via MCP servers, and structured planning mode. By following the steps above, you've installed Kiro, configured team standards, created role-specific agents, connected live data sources, and learned to use planning mode effectively. Avoid common pitfalls like credential misconfiguration and overly permissive agents. Kiro CLI not only replaces the old tool but transforms your terminal into a proactive, context-aware assistant.