CLI commands

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

These arguments work with any Kiro CLI command:

--v2 and --v3 cannot be combined, and at the root --v2 also conflicts with --legacy-ui. --v2 takes precedence over a saved chat.agentEngine value for that invocation without changing it. Both flags are also accepted on kiro-cli chat; an explicit harness on chat wins over a root shorthand.

Launch Kiro Crew or pass arguments to its command-line interface.

Syntax:

kiro-cli crew [--yes] [CREW_ARGUMENTS]...

On macOS and Linux, Kiro CLI prompts to install Crew when it isn't available. Kiro CLI consumes --yes or -y to install without the prompt. It forwards all other arguments after crew directly to Crew, without a -- separator. On Windows, install Crew separately before using this command.

Examples:

# Start the Crew gateway to get started
kiro-cli crew gateway

# Install when needed, skip the prompt, and start the gateway
kiro-cli crew --yes gateway

# Forward a Crew option directly
kiro-cli crew --version

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

# Validate an agent config
kiro-cli agent validate --path ./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

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

# Resume a specific session by ID
kiro-cli chat --resume-id abc123-def456

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

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

# List available models (plain text)
kiro-cli chat --list-models

# List available models (JSON output for scripting)
kiro-cli chat --list-models --format json

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

# Use the V3 harness for this session
kiro-cli chat --v3

# Use the V2 harness for this session, leaving your saved default unchanged
kiro-cli chat --v2

# Set the initial reasoning effort level at launch
kiro-cli chat --effort high "Refactor this module for testability"

Start Kiro CLI as an Agent Client Protocol server for an editor or other ACP client. The client spawns this command and talks to it over standard input and output. kiro-cli acp is a hidden subcommand: it does not appear in kiro-cli --help.

Syntax:

kiro-cli acp [OPTIONS]

Arguments:

A V2-only flag keeps the server on V2 when no harness is named. With --agent-engine v3, the V2-only flags are rejected.

Examples:

# Serve an ACP client on the saved or default harness
kiro-cli acp

# Serve an ACP client on V3 and sign in through the client
kiro-cli acp --agent-engine v3 --auth-method client

Update Kiro CLI to the latest version.

Syntax:

kiro-cli update [OPTIONS]

Options:

If a package manager installed Kiro CLI, for example a deb or rpm package, kiro-cli update prints how to update with that package manager and installs nothing, even with --force.

On macOS and Linux, if you cannot write to the directory that holds Kiro CLI, kiro-cli update installs nothing and tells you to run sudo kiro-cli update.

Examples:

kiro-cli update
kiro-cli update --check
kiro-cli update --force

Manage system integrations for Kiro. Available on macOS and Linux.

Syntax:

kiro-cli integrations <SUBCOMMAND> [OPTIONS] <INTEGRATION>

Subcommands:

Options:

• --silent / -s: Suppress status messages (for install, uninstall, and reinstall)
• --format / -f: Output format (for status command)

Put options before the integration name.

Examples:

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

# Check integration status
kiro-cli integrations status kiro-command-router

# Uninstall silently
kiro-cli integrations uninstall --silent kiro-command-router

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

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
• In Kiro CLI 3.2.1 or later, kiro-cli login run at a terminal on a Linux host with no graphical session (neither DISPLAY nor WAYLAND_DISPLAY is set), such as a container, also uses the device flow. WSL keeps the browser flow

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

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.

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

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

Generate a system information report for troubleshooting.

Syntax:

kiro-cli diagnostic [OPTIONS]

Options:

The plain format outputs TOML.

Output Information:

The diagnostic report includes:

• Kiro CLI version, build hash, and build date
• System information (OS, chip, core count, memory)
• Environment (current directory, Kiro CLI path, install method, and the in-ssh, in-ci, in-wsl, and in-codespaces flags, each shown only when true)
• Cloud session settings
• Kiro CLI environment variables, plus shell and display variables such as PATH, SHELL, and TERM

The report replaces your username in paths with USER.

Examples:

# Generate a diagnostic report
kiro-cli diagnostic

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

Example Output (excerpt):

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

[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/.local/bin/kiro-cli"
install-method = "unknown"

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

Troubleshooting:

• Permission errors: Run with appropriate permissions or ignore errors

Use Cases:

• Troubleshooting installation issues
• Providing information to support
• Verifying environment configuration

Create a GitHub issue for feedback or bug reports.

Syntax:

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

Arguments:

Examples:

kiro-cli issue
kiro-cli issue "Chat session fails to resume after restart"

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

Manage Model Context Protocol (MCP) servers.

Syntax:

kiro-cli mcp [SUBCOMMAND] [OPTIONS]

Subcommands:

Add or replace a configured MCP server.

Arguments:

Example:

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

Remove an MCP server.

Arguments:

Example:

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

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

Import server configuration from a file.

Arguments:

Example:

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

Get the status of an MCP server.

Arguments:

Example:

kiro-cli mcp status --name my-server

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

# 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>

Use the /chat command to manage sessions:

# Start a fresh conversation (saves current session automatically)
/chat new

# Start a fresh conversation with an initial prompt
/chat new <PROMPT>

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

# Save current V3 session to a zip archive
/chat save <FILE_PATH>.zip

# Load a V3 session archive
/chat load <FILE_PATH>.zip

In V3, /chat save writes a zip session archive and /chat load reads that archive. CLI 2.x uses JSON session files and can infer an omitted .json extension.

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

Kiro CLI maintains log files for troubleshooting:

Locations:

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

Environment Variables:

Control logging, the Kiro home directory, and the runtime directory 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.

• Slash Commands Reference
• Settings Configuration
• Setup and troubleshooting