Settings

Kiro CLI provides extensive customization through settings. You can configure everything from telemetry to chat behavior, key bindings, and feature toggles.

Manage settings directly from the command line. Settings saved through interactive /settings menus are available through kiro-cli settings as well; both surfaces use the CLI settings stored in ~/.kiro/settings/cli.json.

# List all configured settings
kiro-cli settings list

# List all available settings with descriptions
kiro-cli settings list --all

# View 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 in editor
kiro-cli settings open

Without a scope flag, kiro-cli settings writes or deletes global settings in ~/.kiro/settings/cli.json. Pass --workspace to store a value for the current project instead:

# Set a global default
kiro-cli settings --global chat.defaultAgent default

# Override it in the current workspace
kiro-cli settings --workspace chat.defaultAgent my-project-agent

When both scopes define a workspace-overridable setting, the workspace value takes precedence in that project's terminal UI sessions. Delete the workspace value to reveal the global value again. Some settings are global-only — including chat.agentEngine, chat.uiMode, and chat.terminalTitle — and cannot be overridden per workspace.

In Kiro CLI 3.1.0 or later on macOS and Linux, a root-owned file named by the KIRO_DEFAULT_SETTINGS environment variable supplies defaults below both scopes. Any value in your global or workspace cli.json overrides it. See Environment variables.

# Plain text (default)
kiro-cli settings list

# JSON
kiro-cli settings list --format json

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

These settings control how the terminal UI renders output. You can toggle animation, ASCII art, icons, screen reader support, and thinking display from within a session with /settings display.

The terminal UI shows a busy indicator while Kiro works. Set chat.enableCustomSpinnerVerbs to true to use the verb pool in chat.spinnerVerbs.

Run kiro-cli settings open, then merge these properties into the top-level object in ~/.kiro/settings/cli.json. Do not replace existing settings:

{
  "chat.enableCustomSpinnerVerbs": true,
  "chat.spinnerVerbs": {
    "mode": "append",
    "verbs": [
      "Checking...",
      "Reading documentation <https://docs.example.com>"
    ]
  }
}

Use append to add your verbs to Kiro's built-in pool. Use replace to use only your verbs. An empty replace list falls back to the built-in busy indicator. A verb can end with a space and an http or https URL in angle brackets. Kiro shows the verb text and makes it a terminal hyperlink when the terminal supports hyperlinks.

These key bindings apply to the classic interface only and have no effect in the terminal UI.

Override the terminal UI shortcuts for cancelling a response, closing overlay menus, and quitting the session. Values use ctrl+, shift+, and alt+/meta+ modifiers with a single key (for example ctrl+shift+q, esc). Invalid values fall back to the built-in default.

V3 loads MCP tools on demand by default. It reads saved toolSearch.* values in interactive runs. Kiro CLI 2.31.1 and later also applies them to non-interactive V3 runs. V2 remains opt-in. See Tool Search for details.

Transient request failures — throttling, 5xx errors, and connection drops (including mid-stream resets) — are retried automatically with backoff; no setting is required.

# Enable telemetry
kiro-cli settings telemetry.enabled true

# Set default chat model
kiro-cli settings chat.defaultModel "claude-sonnet-4.6"

# Disable greeting message
kiro-cli settings chat.greeting.enabled false

# Enable knowledge base
kiro-cli settings chat.enableKnowledge true

# Set file patterns to include
kiro-cli settings knowledge.defaultIncludePatterns '["*.py", "*.js", "*.md", "*.txt"]'

# Set file patterns to exclude
kiro-cli settings knowledge.defaultExcludePatterns '["*.log", "node_modules", ".git", "*.pyc"]'

# Set maximum files to index
kiro-cli settings knowledge.maxFiles 2000

# Enable thinking tool
kiro-cli settings chat.enableThinking true

# Enable tangent mode
kiro-cli settings chat.enableTangentMode true

# Enable todo lists
kiro-cli settings chat.enableTodoList true

# Enable checkpoints
kiro-cli settings chat.enableCheckpoint true

# Configure key bindings
kiro-cli settings chat.tangentModeKey "t"
kiro-cli settings chat.delegateModeKey "d"

# Cap streaming responses at 10 minutes instead of the 60-minute default
kiro-cli settings api.timeout 600

# Give slow connections more room before a stall warning
kiro-cli settings api.streamIdleSoftTimeout 120

# Adjust knowledge base chunk size
kiro-cli settings knowledge.chunkSize 1024

# Disable auto-compaction for long conversations
kiro-cli settings chat.disableAutoCompaction true

Boolean values: Use true or false (lowercase)

kiro-cli settings telemetry.enabled true  # ✓ Correct
kiro-cli settings telemetry.enabled True  # ✗ Wrong

Array values: Use JSON format with single quotes

kiro-cli settings knowledge.defaultIncludePatterns '["*.py", "*.js"]'  # ✓ Correct

String values: Use quotes for strings with spaces

kiro-cli settings chat.defaultModel "claude-sonnet-4.6"  # ✓ Correct

Delete individual settings:

kiro-cli settings --delete setting.name

Open settings file for manual editing:

kiro-cli settings open

View current settings to identify issues:

kiro-cli settings list --all

If the settings file becomes corrupted:

1. Back up current settings:

   bash

   kiro-cli settings list --format json > backup.json
   

2. Open the settings file:

   bash

   kiro-cli settings open
   

3. Verify JSON syntax or restore from backup

Settings are stored in ~/.kiro/settings/cli.json.

You can edit this file directly, but using kiro-cli settings commands is recommended for validation.

• Configure custom agents
• Workflows
• Set up MCP servers
• Configure custom diff tools
• Enable experimental features
• CLI Commands Reference