CLI commands

This page provides a comprehensive reference for all Kiro CLI commands and their arguments.

Global arguments

These arguments work with any Kiro CLI command:

Commands

kiro-cli agent

Manage agent configurations. Agent name is now a positional argument for create, edit, and other subcommands.

Syntax:

kiro-cli agent [SUBCOMMAND] [AGENT_NAME] [OPTIONS]

Subcommands:

Examples:

kiro-cli agent list

# v1.26.0+: Agent name as positional argument
kiro-cli agent create my-agent
kiro-cli agent edit my-agent
kiro-cli agent edit  # Defaults to current agent

# Previous syntax (still supported)
kiro-cli agent validate ./my-agent.json
kiro-cli agent set-default my-agent

New in v1.26.0:

• Agent name is now a positional argument (e.g., kiro-cli agent create my-agent instead of --name my-agent)
• edit command defaults to editing the current agent when no argument is provided

kiro-cli chat

Start an interactive chat session with Kiro. When no subcommand is specified, kiro defaults to kiro-cli chat.

Syntax:

kiro-cli chat [OPTIONS] [INPUT]

Arguments:

Examples:

# Start interactive chat
kiro-cli 

# Ask a question directly
kiro-cli chat "How do I list files in Linux?"

# Non-interactive mode with trusted tools
kiro-cli chat --no-interactive --trust-all-tools "Show me the current directory"

# Resume previous conversation
kiro-cli chat --resume

# Open session picker to choose which session to resume
kiro-cli chat --resume-picker

# List all saved sessions
kiro-cli chat --list-sessions

# Use specific agent
kiro-cli chat --agent my-agent "Help me with AWS CLI"

kiro-cli translate

Translate natural language instructions to executable shell commands using AI.

Syntax:

kiro-cli translate [OPTIONS] [INPUT...]

Arguments:

Examples:

kiro-cli translate "list all files in the current directory"
kiro-cli translate "find all Python files modified in the last week"
kiro-cli translate "compress all log files older than 30 days"
kiro-cli translate -n 3 "search for text in files"

kiro-cli doctor

Diagnose and fix common installation and configuration issues.

Syntax:

kiro-cli doctor [OPTIONS]

Arguments:

Examples:

kiro-cli doctor
kiro-cli doctor --all
kiro-cli doctor --strict

kiro-cli update

Update Kiro CLI to the latest version.

Syntax:

kiro-cli update [OPTIONS]

Arguments:

Examples:

kiro-cli update
kiro-cli update --non-interactive

kiro-cli theme

Get or set the visual theme for the autocomplete dropdown menu.

Syntax:

kiro-cli theme [OPTIONS] [THEME]

Arguments:

Examples:

kiro-cli theme --list
kiro-cli theme dark
kiro-cli theme light
kiro-cli theme system

kiro-cli integrations

Manage system integrations for Kiro.

Syntax:

kiro-cli integrations [SUBCOMMAND] [OPTIONS]

Subcommands:

Options:

• --silent / -s: Suppress status messages
• --format / -f: Output format (for status command)

Examples:

# Install kiro command router (v1.26.0+)
kiro-cli integrations install kiro-command-router

# Check integration status
kiro-cli integrations status

# Uninstall silently
kiro-cli integrations uninstall --silent

Kiro Command Router (v1.26.0+)

The kiro command router is a unified entry point that routes the kiro command between CLI and IDE based on your preference.

Problem it solves: By default, the kiro command launches Kiro IDE. Many users prefer it to launch the CLI since they use the app icon to open the IDE.

Installation:

# Install the router
kiro-cli integrations install kiro-command-router

# Set CLI as the default
kiro set-default cli

# Or set IDE as the default
kiro set-default ide

After installation:

• kiro - Launches your default (CLI or IDE)
• kiro-cli - Always launches CLI
• kiro-ide - Always launches IDE

Use cases:

• CLI-focused workflows where you primarily use the terminal
• Quick access to CLI without typing kiro-cli every time
• Flexibility to switch defaults based on your current project or workflow

kiro-cli inline

Manage inline suggestions (ghost text) that appear as you type.

Syntax:

kiro-cli inline [SUBCOMMAND] [OPTIONS]

Subcommands:

Examples:

kiro-cli inline enable
kiro-cli inline disable
kiro-cli inline status
kiro-cli inline set-customization
kiro-cli inline show-customizations --format json

kiro-cli login

Authenticate with Kiro CLI service using Builder ID, Identity Center, or social login (Google, GitHub).

Syntax:

kiro-cli login [OPTIONS]

Options:

Authentication Methods:

Local Environment:

• Opens browser for unified auth portal
• Select authentication method interactively
• Login-selection flags (e.g., --license, --social) are generally ignored locally; the browser flow controls the method

Remote Environment (SSH/Terminal):

• Uses device flow automatically
• Shows device code and URL
• Complete authentication on another device
• CLI polls for completion

Examples:

# Basic login (opens browser locally, shows device code remotely)
kiro-cli login

# Identity Center login
kiro-cli login --license pro --identity-provider https://my-org.awsapps.com/start --region us-east-1

# Social login
kiro-cli login --social google

# Force device flow (useful for SSH sessions)
kiro-cli login --use-device-flow

Troubleshooting:

• Already logged in error: Logout first with kiro-cli logout
• Browser doesn't open: Use --use-device-flow flag
• Authentication timeout: Restart the login process
• Identity Center fails: Verify URL and region with your administrator

kiro-cli logout

Sign out of Kiro CLI service and clear authentication credentials.

Syntax:

kiro-cli logout

Options:

What Gets Cleared:

• Authentication tokens
• Session credentials
• User profile information

What's Preserved:

• Agent configurations
• Saved conversations
• Settings
• MCP server configurations

Example:

kiro-cli logout

Output:

You are now logged out
Run kiro-cli login to log back in to Kiro CLI

Note: Logout is user-wide and affects all workspaces.

kiro-cli whoami

Display information about the current user and authentication status, including your email address for Builder ID, IAM Identity Center, and Social login types.

Syntax:

kiro-cli whoami [OPTIONS]

Options:

Output Information:

• Username/user ID
• Authentication method (Builder ID, Identity Center, Social)
• Session status
• Profile information

Examples:

# Check current user
kiro-cli whoami
# Logged in with Builder ID
# Email: user@example.com

kiro-cli whoami --format json
kiro-cli whoami --format json-pretty

Example Output (Identity Center):

Logged in with IAM Identity Center (https://my-org.awsapps.com/start)

Profile:
Q-Dev-Amazon-Profile
arn:aws:codewhisperer:us-east-1:...:profile/...

Example Output (Builder ID):

Logged in with Builder ID

Profile:
builder-id-username

Troubleshooting:

• Not logged in error: Login with kiro-cli login

kiro-cli settings

Manage kiro-cli configuration settings.

Syntax:

kiro-cli settings [SUBCOMMAND] [OPTIONS] [KEY] [VALUE]

Arguments:

Subcommands:

Examples:

# View all settings
kiro-cli settings list

# View all available settings
kiro-cli settings list --all

# Get a specific setting
kiro-cli settings telemetry.enabled

# Set a setting
kiro-cli settings telemetry.enabled true

# Delete a setting
kiro-cli settings --delete chat.defaultModel

# Open settings file
kiro-cli settings open

# JSON output
kiro-cli settings list --format json-pretty

kiro-cli diagnostic

Run diagnostic tests and generate system information report for troubleshooting.

Syntax:

kiro-cli diagnostic [OPTIONS]

Options:

The plain format outputs Markdown-formatted text.

Behavior:

• Without --force: Requires Kiro CLI app to be running (use kiro-cli launch first). Generates comprehensive diagnostics by connecting to the running app.
• With --force: Standalone command that works without the app running. Generates limited but faster diagnostics.

Output Information:

The diagnostic report includes:

• System information (OS, architecture, memory)
• Kiro CLI version and build details
• Configuration status
• Environment variables
• Installed dependencies
• Potential issues

Examples:

# Generate full diagnostic report
kiro-cli diagnostic

# JSON output
kiro-cli diagnostic --format json-pretty

# Limited output (faster)
kiro-cli diagnostic --force

Example Output (TOML format):

[q-details]
version = "1.23.0"
hash = "97d58722cd90f6d3dda465f6462ee4c6dc104b22"
date = "2025-12-18T16:49:27.015389Z (4d ago)"
variant = "full"

[system-info]
os = "macOS 15.7.1 (24G231)"
chip = "Apple M1 Pro"
total-cores = 10
memory = "32.00 GB"

[environment]
cwd = "/Users/user/project"
cli-path = "/Users/user/.cargo/bin/kiro-cli"
os = "Mac"
shell-path = "/bin/bash"
shell-version = "5.1.16"
terminal = "iTerm2"
install-method = "cargo"

[env-vars]
PATH = "..."
SHELL = "/bin/zsh"
TERM = "xterm-256color"

Troubleshooting:

• "Kiro CLI app is not running" error: Launch the app with kiro-cli launch or use --force flag for standalone diagnostics
• Diagnostic hangs: Use --force for faster limited output
• Permission errors: Run with appropriate permissions or ignore errors

Use Cases:

• Troubleshooting installation issues
• Providing information to support
• Verifying environment configuration
• Checking for potential problems

kiro-cli issue

Create a GitHub issue for feedback or bug reports.

Syntax:

kiro-cli issue [OPTIONS] [DESCRIPTION...]

Arguments:

Examples:

kiro-cli issue
kiro-cli issue "Autocomplete not working in zsh"

kiro-cli version

Display version information and changelog.

Syntax:

kiro-cli version [OPTIONS]

Arguments:

Examples:

kiro-cli version
kiro-cli version --changelog
kiro-cli version --changelog=all
kiro-cli version --changelog=1.5.0

kiro-cli mcp

Manage Model Context Protocol (MCP) servers.

Syntax:

kiro-cli mcp [SUBCOMMAND] [OPTIONS]

Subcommands:

kiro-cli mcp add

Add or replace a configured MCP server.

Arguments:

Example:

kiro-cli mcp add --name my-server --command "node server.js" --scope workspace

kiro-cli mcp remove

Remove an MCP server.

Arguments:

Example:

kiro-cli mcp remove --name my-server --scope workspace

kiro-cli mcp list

List configured MCP servers.

Syntax:

kiro-cli mcp list [SCOPE]

Example:

kiro-cli mcp list
kiro-cli mcp list workspace
kiro-cli mcp list global

kiro-cli mcp import

Import server configuration from a file.

Arguments:

Example:

kiro-cli mcp import --file config.json workspace

kiro-cli mcp status

Get the status of an MCP server.

Arguments:

Example:

kiro-cli mcp status --name my-server

Session management

Kiro CLI automatically saves all chat sessions on every conversation turn. You can resume from any previous chat session at any time.

From the command line

# Resume the most recent chat session
kiro-cli chat --resume

# Interactively pick a chat session to resume
kiro-cli chat --resume-picker

# List all saved chat sessions for the current directory
kiro-cli chat --list-sessions

# Delete a saved chat session
kiro-cli chat --delete-session <SESSION_ID>

From within a chat session

Use the /chat command to manage sessions:

# Resume a chat session (interactive selector)
/chat resume

# Save current session to a file
/chat save <FILE_PATH>

# Load a session from a file
/chat load <FILE_PATH>

The .json extension is optional when loading - Kiro will try both with and without the extension.

Custom session storage

You can use custom scripts to control where chat sessions are saved to and loaded from. This allows you to store sessions in version control systems, cloud storage, databases, or any custom location.

# Save session via custom script (receives JSON via stdin)
/chat save-via-script <SCRIPT_PATH>

# Load session via custom script (outputs JSON to stdout)
/chat load-via-script <SCRIPT_PATH>

Tips:

• Session IDs are UUIDs that uniquely identify each chat session
• Sessions are stored per directory, so each project has its own set of sessions
• The most recently updated sessions appear first in the list

Log files

Kiro CLI maintains log files for troubleshooting:

Locations:

• macOS: $TMPDIR/kiro-log/
• Linux: $XDG_RUNTIME_DIR or /tmp/kiro-log/

Environment Variables:

Control logging behavior with these environment variables:

Log Levels:

Set via KIRO_LOG_LEVEL environment variable:

• error: Only errors (default)
• warn: Warnings and errors
• info: Info, warnings, and errors
• debug: Debug info and above
• trace: All messages including detailed traces

Examples:

# Enable debug logging
export KIRO_LOG_LEVEL=debug
kiro-cli chat

# Disable colored output (useful for CI/CD, v1.26.0+)
export KIRO_LOG_NO_COLOR=1
kiro-cli chat

# Combined
export KIRO_LOG_LEVEL=debug
export KIRO_LOG_NO_COLOR=true
kiro-cli chat

# For fish shell
set -x KIRO_LOG_LEVEL debug
set -x KIRO_LOG_NO_COLOR 1
kiro-cli chat

New in v1.26.0: KIRO_LOG_NO_COLOR environment variable to disable colored log output, useful for CI/CD pipelines and log file processing.

Warning: Log files may contain sensitive information including file paths, code snippets, and command outputs. Be cautious when sharing logs.

Next steps

• Slash Commands Reference
• Settings Configuration
• Troubleshooting Guide