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:
# 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
# Plain text (default) kiro-cli settings list # JSON kiro-cli settings list --format json # Formatted JSON kiro-cli settings list --format json-pretty
| Setting | Type | Description | Example |
|---|---|---|---|
telemetry.enabled | boolean | Enable/disable telemetry collection | kiro-cli settings telemetry.enabled true |
telemetryClientId | string | Client identifier for telemetry | kiro-cli settings telemetryClientId "client-123" |
| Setting | Type | Description | Example |
|---|---|---|---|
chat.defaultModel | string | Default AI model for conversations | kiro-cli settings chat.defaultModel "claude-3-sonnet" |
chat.defaultAgent | string | Default agent configuration | kiro-cli settings chat.defaultAgent "my-agent" |
chat.diffTool | string | External diff tool for viewing code changes (classic only) | kiro-cli settings chat.diffTool "delta" |
chat.greeting.enabled | boolean | Show greeting message on chat start | kiro-cli settings chat.greeting.enabled false |
chat.editMode | boolean | Enable Vi edit mode (classic only) | kiro-cli settings chat.editMode true |
chat.enableNotifications | boolean | Enable desktop notifications | kiro-cli settings chat.enableNotifications true |
chat.notificationMethod | string | Notification method: auto, bel, or osc9 | kiro-cli settings chat.notificationMethod "osc9" |
chat.disableMarkdownRendering | boolean | Disable markdown formatting (classic only) | kiro-cli settings chat.disableMarkdownRendering false |
chat.disableWrap | boolean | Emit chat output without hard line breaks for clean copy-paste; terminal soft-wrap still applies. | kiro-cli settings chat.disableWrap true |
chat.disableAutoCompaction | boolean | Disable automatic conversation summarization | kiro-cli settings chat.disableAutoCompaction true |
compaction.excludeMessages | number | Minimum message pairs to retain during compaction | kiro-cli settings compaction.excludeMessages 2 |
compaction.excludeContextWindowPercent | number | Minimum % of context window to retain during compaction | kiro-cli settings compaction.excludeContextWindowPercent 2 |
chat.enablePromptHints | boolean | Show startup hints with tips and shortcuts (v1.26.0+, default: true) | kiro-cli settings chat.enablePromptHints false |
chat.enableHistoryHints | boolean | Show conversation history hints (classic only) | kiro-cli settings chat.enableHistoryHints true |
chat.uiMode | string | UI variant to use | kiro-cli settings chat.uiMode "compact" |
chat.ui | string | UI engine: tui (default) or classic | kiro-cli settings chat.ui "classic" |
chat.disableGranularTrust | boolean | Disable tiered trust options for tool approvals (terminal UI only) | kiro-cli settings chat.disableGranularTrust true |
chat.autoExpandToolOutput | boolean | Auto-expand tool output instead of collapsing (terminal UI only) | kiro-cli settings chat.autoExpandToolOutput true |
chat.enableContextUsageIndicator | boolean | Show context usage percentage in prompt (classic only) | kiro-cli settings chat.enableContextUsageIndicator true |
| Setting | Type | Description | Example |
|---|---|---|---|
chat.enableKnowledge | boolean | Enable knowledge base functionality | kiro-cli settings chat.enableKnowledge true |
knowledge.defaultIncludePatterns | array | Default file patterns to include | kiro-cli settings knowledge.defaultIncludePatterns '["*.py", "*.js"]' |
knowledge.defaultExcludePatterns | array | Default file patterns to exclude | kiro-cli settings knowledge.defaultExcludePatterns '["*.log", "node_modules"]' |
knowledge.maxFiles | number | Maximum files for indexing | kiro-cli settings knowledge.maxFiles 1000 |
knowledge.chunkSize | number | Text chunk size for processing | kiro-cli settings knowledge.chunkSize 512 |
knowledge.chunkOverlap | number | Overlap between text chunks | kiro-cli settings knowledge.chunkOverlap 50 |
knowledge.indexType | string | Type of knowledge index | kiro-cli settings knowledge.indexType "fast" |
These key bindings apply to the classic interface only and have no effect in the terminal UI.
| Setting | Type | Description | Example |
|---|---|---|---|
chat.skimCommandKey | char | Key for fuzzy search command | kiro-cli settings chat.skimCommandKey "f" |
chat.autocompletionKey | char | Key for autocompletion hint acceptance | kiro-cli settings chat.autocompletionKey "Tab" |
chat.tangentModeKey | char | Key for tangent mode toggle | kiro-cli settings chat.tangentModeKey "t" |
chat.delegateModeKey | char | Key for delegate command | kiro-cli settings chat.delegateModeKey "d" |
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.
| Setting | Type | Default | Description | Example |
|---|---|---|---|---|
chat.keybindings.cancelStream | string | esc | Cancel the current agent response while it streams | kiro-cli settings chat.keybindings.cancelStream "ctrl+x" |
chat.keybindings.closeMenu | string | esc | Close overlay panels and pickers | kiro-cli settings chat.keybindings.closeMenu "ctrl+[" |
chat.keybindings.quit | string | ctrl+c | Exit the chat session | kiro-cli settings chat.keybindings.quit "ctrl+shift+q" |
Configure on-demand MCP tool discovery. See Tool Search for details.
| Setting | Type | Description | Example |
|---|---|---|---|
toolSearch.enabled | boolean | Enable Tool Search for on-demand MCP tool discovery (default: false) | kiro-cli settings toolSearch.enabled true |
toolSearch.minPct | number | Activate when MCP tool specs exceed this % of context window (default: 5) | kiro-cli settings toolSearch.minPct 0 |
toolSearch.minTokens | number | Activate when MCP tool specs exceed this token count (default: 50000) | kiro-cli settings toolSearch.minTokens 0 |
| Setting | Type | Description | Example |
|---|---|---|---|
chat.enableThinking | boolean | Enable thinking tool for complex reasoning | kiro-cli settings chat.enableThinking true |
chat.enableTangentMode | boolean | Enable tangent mode feature (classic only) | kiro-cli settings chat.enableTangentMode true |
introspect.tangentMode | boolean | Auto-enter tangent mode for introspect (classic only) | kiro-cli settings introspect.tangentMode true |
chat.enableTodoList | boolean | Enable todo list feature (classic only) | kiro-cli settings chat.enableTodoList true |
chat.enableCheckpoint | boolean | Enable checkpoint feature (classic only) | kiro-cli settings chat.enableCheckpoint true |
chat.enableDelegate | boolean | Enable delegate tool (classic only) | kiro-cli settings chat.enableDelegate true |
app.disableAutoupdates | boolean | Disable background auto-updates | kiro-cli settings app.disableAutoupdates true |
| Setting | Type | Description | Example |
|---|---|---|---|
api.timeout | number | API request timeout in seconds | kiro-cli settings api.timeout 30 |
| Setting | Type | Description | Example |
|---|---|---|---|
mcp.initTimeout | number | MCP server initialization timeout | kiro-cli settings mcp.initTimeout 10 |
mcp.noInteractiveTimeout | number | Non-interactive MCP timeout | kiro-cli settings mcp.noInteractiveTimeout 5 |
mcp.loadedBefore | boolean | Track previously loaded MCP servers | kiro-cli settings mcp.loadedBefore true |
# Enable telemetry kiro-cli settings telemetry.enabled true # Set default chat model kiro-cli settings chat.defaultModel "claude-3-sonnet" # 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"
# Increase API timeout for slow connections kiro-cli settings api.timeout 60 # 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-3-sonnet" # ✓ 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:
Back up current settings:
kiro-cli settings list --format json > backup.json
Open the settings file:
kiro-cli settings open
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.
| Variable | Description |
|---|---|
KIRO_HOME | Overrides the ~/.kiro directory used for global agents, prompts, skills, steering, settings, and sessions. Useful for keeping multiple independent Kiro profiles on the same machine. |
KIRO_LOG_NO_COLOR | Set to 1 to disable colored log output |
NO_COLOR | Set to any value to disable all color output in the terminal UI |
KIRO_CLI_TOOL_SEARCH_MATCHING_THRESHOLD | Minimum relevance score for Tool Search keyword results (default: 1.5) |
Settings