Documentation

Configuration

Complete config reference derived from packages/nikcli/src/config/config.ts.

Resolution Order

Configuration is merged in the following precedence order (lowest to highest):

Layer	Source
Remote	`/.well-known/nikcli` for OAuth providers (loaded via Auth)
Global	`~/.config/nikcli/nikcli.jsonc` (or `nikcli.json`, `config.json`)
Custom path	`NIKCLI_CONFIG` or `NIKCLI_CONFIG_CONTENT`
Project	`nikcli.jsonc` or `nikcli.json` discovered upward

Config tokens

Values like {env:VAR} and {file:path} are expanded while parsing.

Config Schema

json

{ "$schema": "https://nikcli.store/config.json", "theme": "dark", "model": "anthropic/claude-sonnet-4-20250514", "small_model": "anthropic/claude-haiku-4-20250514", "default_agent": "build", "username": "dev", "share": "manual", "autoupdate": true, "disabled_providers": [], "enabled_providers": [], "permission": {}, "agent": {}, "provider": {}, "mcp": {}, "lsp": {}, "rag": {}, "experimental": {} }

Top-Level Fields

Field	Description
`$schema`	Schema URL for validation.
`theme`	Theme name for UI.
`logLevel`	Log level (DEBUG/INFO/WARN/ERROR).
`tui`	TUI settings (scroll, layout, etc.).
`server`	Server defaults for serve/web commands.
`command`	Command templates and presets.
`watcher`	File watcher ignore list.
`plugin`	Plugin entrypoints to load.
`snapshot`	Enable snapshot tracking.
`share`	manual \| auto \| disabled.
`autoshare`	Deprecated, use share.
`autoupdate`	true \| false \| notify.
`disabled_providers`	Disable providers by ID.
`enabled_providers`	Enable only these providers.
`model`	Default model in provider/model format.
`small_model`	Small model for titles/summary.
`default_agent`	Primary agent name (defaults to build).
`username`	Custom username label.
`agent`	Agent configuration objects.
`provider`	Provider config overrides.
`mcp`	MCP server configs.
`formatter`	Formatter config or false.
`lsp`	LSP config or false.
`instructions`	Extra instruction files/patterns.
`permission`	Permission ruleset.
`tools`	Legacy tool allow/deny map.
`enterprise`	Enterprise settings.
`compaction`	Auto compaction settings.
`experimental`	Experimental flags and hooks.
`rag`	RAG embedding config.

Agents & Permissions

Agents use the AgentConfig schema and merge permissions from config + defaults.

Field	Description
`agent`	Primary/subagent definitions. Supports additional custom agents by name.
`permission`	Tool allow/deny/ask rules. Accepts per-tool rules and wildcard patterns.

Providers

Provider configuration is scoped per provider ID under provider.

json

{ "provider": { "anthropic": { "options": { "apiKey": "{env:ANTHROPIC_API_KEY}" } }, "openai": { "options": { "apiKey": "{env:OPENAI_API_KEY}" } }, "amazon-bedrock": { "options": { "region": "us-east-1" } } } }

MCP

MCP server entries live under mcp and support local or remote configurations.

json

{ "mcp": { "filesystem": { "type": "local", "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }, "remote-docs": { "type": "remote", "url": "https://example.com/mcp" } } }

LSP

Built-in LSP servers can be disabled or overridden. Custom servers require explicit extensions.

json

{ "lsp": { "pyright": { "disabled": true }, "custom-lua": { "command": ["lua-language-server"], "extensions": [".lua"] } } }

RAG

RAG embedding defaults are in packages/nikcli/src/rag/index.ts.

json

{ "rag": { "model": "nvidia/llama-embed-nemotron-8b", "provider": "nvidia" } }

Keybinds

Default keybinds are defined in KeybindsConfig and can be overridden under keybinds.

Key	Default	Description
`leader`	`ctrl+x`	Leader key for keybind combinations
`app_exit`	`ctrl+c,ctrl+d,<leader>q`	Exit the application
`editor_open`	`<leader>e`	Open external editor
`theme_list`	`<leader>t`	List available themes
`sidebar_toggle`	`<leader>b`	Toggle sidebar
`scrollbar_toggle`	`none`	Toggle session scrollbar
`username_toggle`	`none`	Toggle username visibility
`status_view`	`<leader>s`	View status
`session_export`	`<leader>x`	Export session to editor
`session_new`	`<leader>n`	Create a new session
`session_list`	`<leader>l`	List all sessions
`session_timeline`	`<leader>g`	Show session timeline
`session_fork`	`none`	Fork session from message
`session_rename`	`ctrl+r`	Rename session
`session_delete`	`ctrl+d`	Delete session
`stash_delete`	`ctrl+d`	Delete stash entry
`model_provider_list`	`ctrl+a`	Open provider list from model dialog
`model_favorite_toggle`	`ctrl+f`	Toggle model favorite status
`session_share`	`none`	Share current session
`session_unshare`	`none`	Unshare current session
`session_interrupt`	`escape`	Interrupt current session
`session_compact`	`<leader>c`	Compact the session
`messages_page_up`	`pageup,ctrl+alt+b`	Scroll messages up by one page
`messages_page_down`	`pagedown,ctrl+alt+f`	Scroll messages down by one page
`messages_line_up`	`ctrl+alt+y`	Scroll messages up by one line
`messages_line_down`	`ctrl+alt+e`	Scroll messages down by one line
`messages_half_page_up`	`ctrl+alt+u`	Scroll messages up by half page
`messages_half_page_down`	`ctrl+alt+d`	Scroll messages down by half page
`messages_first`	`ctrl+g,home`	Navigate to first message
`messages_last`	`ctrl+alt+g,end`	Navigate to last message
`messages_next`	`none`	Navigate to next message
`messages_previous`	`none`	Navigate to previous message
`messages_last_user`	`none`	Navigate to last user message
`messages_copy`	`<leader>y`	Copy message
`messages_undo`	`<leader>u`	Undo message
`messages_redo`	`<leader>r`	Redo message
`messages_toggle_conceal`	`<leader>h`	Toggle code block concealment in messages
`tool_details`	`none`	Toggle tool details visibility
`model_list`	`<leader>m`	List available models
`model_cycle_recent`	`f2`	Next recently used model
`model_cycle_recent_reverse`	`shift+f2`	Previous recently used model
`model_cycle_favorite`	`none`	Next favorite model
`model_cycle_favorite_reverse`	`none`	Previous favorite model
`command_list`	`ctrl+p`	List available commands
`agent_list`	`<leader>a`	List agents
`agent_cycle`	`tab`	Next agent
`agent_cycle_reverse`	`shift+tab`	Previous agent
`variant_cycle`	`ctrl+t`	Cycle model variants
`input_clear`	`ctrl+c`	Clear input field
`input_paste`	`ctrl+v`	Paste from clipboard
`input_submit`	`return`	Submit input
`input_newline`	`shift+return,ctrl+return,alt+return,ctrl+j`	Insert newline in input
`input_move_left`	`left,ctrl+b`	Move cursor left in input
`input_move_right`	`right,ctrl+f`	Move cursor right in input
`input_move_up`	`up`	Move cursor up in input
`input_move_down`	`down`	Move cursor down in input
`input_select_left`	`shift+left`	Select left in input
`input_select_right`	`shift+right`	Select right in input
`input_select_up`	`shift+up`	Select up in input
`input_select_down`	`shift+down`	Select down in input
`input_line_home`	`ctrl+a`	Move to start of line in input
`input_line_end`	`ctrl+e`	Move to end of line in input
`input_select_line_home`	`ctrl+shift+a`	Select to start of line in input
`input_select_line_end`	`ctrl+shift+e`	Select to end of line in input
`input_visual_line_home`	`alt+a`	Move to start of visual line in input
`input_visual_line_end`	`alt+e`	Move to end of visual line in input
`input_select_visual_line_home`	`alt+shift+a`	Select to start of visual line in input
`input_select_visual_line_end`	`alt+shift+e`	Select to end of visual line in input
`input_buffer_home`	`home`	Move to start of buffer in input
`input_buffer_end`	`end`	Move to end of buffer in input
`input_select_buffer_home`	`shift+home`	Select to start of buffer in input
`input_select_buffer_end`	`shift+end`	Select to end of buffer in input
`input_delete_line`	`ctrl+shift+d`	Delete line in input
`input_delete_to_line_end`	`ctrl+k`	Delete to end of line in input
`input_delete_to_line_start`	`ctrl+u`	Delete to start of line in input
`input_backspace`	`backspace,shift+backspace`	Backspace in input
`input_delete`	`ctrl+d,delete,shift+delete`	Delete character in input
`input_undo`	`ctrl+-,super+z`	Undo in input
`input_redo`	`ctrl+.,super+shift+z`	Redo in input
`input_word_forward`	`alt+f,alt+right,ctrl+right`	Move word forward in input
`input_word_backward`	`alt+b,alt+left,ctrl+left`	Move word backward in input
`input_select_word_forward`	`alt+shift+f,alt+shift+right`	Select word forward in input
`input_select_word_backward`	`alt+shift+b,alt+shift+left`	Select word backward in input
`input_delete_word_forward`	`alt+d,alt+delete,ctrl+delete`	Delete word forward in input
`input_delete_word_backward`	`ctrl+w,ctrl+backspace,alt+backspace`	Delete word backward in input
`history_previous`	`up`	Previous history item
`history_next`	`down`	Next history item
`session_child_cycle`	`<leader>right`	Next child session
`session_child_cycle_reverse`	`<leader>left`	Previous child session
`session_parent`	`<leader>up`	Go to parent session
`terminal_suspend`	`ctrl+z`	Suspend terminal
`terminal_title_toggle`	`none`	Toggle terminal title
`tips_toggle`	`<leader>h`	Toggle tips on home screen

Flags & Env

Runtime flags are parsed from environment variables in packages/nikcli/src/flag/flag.ts.

Variable	Description
`NIKCLI_AUTO_SHARE`	Enable automatic sharing for new sessions.
`NIKCLI_GIT_BASH_PATH`	Override Git Bash install path (Windows).
`NIKCLI_CONFIG`	Custom config file path.
`NIKCLI_CONFIG_DIR`	Additional config directory to scan.
`NIKCLI_CONFIG_CONTENT`	Inline JSON config content.
`NIKCLI_DISABLE_AUTOUPDATE`	Disable automatic upgrades.
`NIKCLI_DISABLE_PRUNE`	Disable pruning of old tool outputs.
`NIKCLI_DISABLE_TERMINAL_TITLE`	Disable terminal title updates.
`NIKCLI_PERMISSION`	Inline JSON permission overrides.
`NIKCLI_DISABLE_DEFAULT_PLUGINS`	Skip built-in plugins.
`NIKCLI_DISABLE_LSP_DOWNLOAD`	Disable automatic LSP downloads.
`NIKCLI_ENABLE_EXPERIMENTAL_MODELS`	Allow experimental models from catalog.
`NIKCLI_DISABLE_AUTOCOMPACT`	Disable auto compaction.
`NIKCLI_DISABLE_MODELS_FETCH`	Disable models.dev fetch.
`NIKCLI_DISABLE_CLAUDE_CODE`	Disable Claude Code integrations.
`NIKCLI_DISABLE_CLAUDE_CODE_PROMPT`	Disable Claude Code prompt injection.
`NIKCLI_DISABLE_CLAUDE_CODE_SKILLS`	Disable Claude Code skills discovery.
`NIKCLI_DISABLE_PROJECT_CONFIG`	Disable project-level config discovery.
`NIKCLI_FAKE_VCS`	Force fake VCS mode.
`NIKCLI_CLIENT`	Client type (cli/app/desktop).
`NIKCLI_SERVER_PASSWORD`	Enable basic auth for server mode.
`NIKCLI_SERVER_USERNAME`	Override basic auth username.
`NIKCLI_EXPERIMENTAL`	Enable experimental features.
`NIKCLI_EXPERIMENTAL_FILEWATCHER`	Enable experimental file watcher.
`NIKCLI_EXPERIMENTAL_DISABLE_FILEWATCHER`	Disable file watcher.
`NIKCLI_EXPERIMENTAL_ICON_DISCOVERY`	Enable icon discovery.
`NIKCLI_EXPERIMENTAL_DISABLE_COPY_ON_SELECT`	Disable copy-on-select.
`NIKCLI_ENABLE_EXA`	Enable Exa-backed search tools.
`NIKCLI_EXPERIMENTAL_EXA`	Enable Exa search in experimental mode.
`NIKCLI_EXPERIMENTAL_BASH_MAX_OUTPUT_LENGTH`	Max bash output length.
`NIKCLI_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS`	Default bash timeout in ms.
`NIKCLI_EXPERIMENTAL_OUTPUT_TOKEN_MAX`	Max output tokens before truncation.
`NIKCLI_EXPERIMENTAL_OXFMT`	Enable experimental formatter.
`NIKCLI_EXPERIMENTAL_LSP_TY`	Enable experimental LSP server ty.
`NIKCLI_EXPERIMENTAL_LSP_TOOL`	Enable LSP tool in registry.
`NIKCLI_DISABLE_FILETIME_CHECK`	Disable file mtime checks.
`NIKCLI_EXPERIMENTAL_PLAN_MODE`	Enable plan_enter/plan_exit tools.
`NIKCLI_EXPERIMENTAL_SECURITY_TOOL`	Enable experimental security tool.

Experimental

Experimental flags are defined under experimental and via env flags in packages/nikcli/src/flag/flag.ts.