---
title: "Update configuration"
method: PATCH
path: "/config"
---

# Update configuration

`PATCH /config`

Update Arctic configuration settings and preferences.

## Query parameters

- `directory` string

## Request body

- Config
  - `$schema` string — JSON schema reference for configuration validation
  - `theme` string — Theme name to use for the interface
  - `keybinds` KeybindsConfig — Custom keybind configurations
    - `leader` string — Leader key for keybind combinations
    - `app_exit` string — Exit the application
    - `editor_open` string — Open external editor
    - `theme_list` string — List available themes
    - `sidebar_toggle` string — Toggle sidebar
    - `scrollbar_toggle` string — Toggle session scrollbar
    - `username_toggle` string — Toggle username visibility
    - `status_view` string — View status
    - `session_export` string — Export session to editor
    - `session_new` string — Create a new session
    - `session_list` string — List all sessions
    - `session_timeline` string — Show session timeline
    - `session_share` string — Share current session
    - `session_unshare` string — Unshare current session
    - `session_interrupt` string — Interrupt current session
    - `session_compact` string — Compact the session
    - `messages_page_up` string — Scroll messages up by one page
    - `messages_page_down` string — Scroll messages down by one page
    - `messages_half_page_up` string — Scroll messages up by half page
    - `messages_half_page_down` string — Scroll messages down by half page
    - `messages_first` string — Navigate to first message
    - `messages_last` string — Navigate to last message
    - `messages_last_user` string — Navigate to last user message
    - `messages_copy` string — Copy message
    - `messages_undo` string — Undo message
    - `messages_redo` string — Redo message
    - `messages_toggle_conceal` string — Toggle code block concealment in messages
    - `tool_details` string — Toggle tool details visibility
    - `model_list` string — List available models
    - `model_cycle_recent` string — Next recently used model
    - `model_cycle_recent_reverse` string — Previous recently used model
    - `command_list` string — List available commands
    - `agent_list` string — List agents
    - `agent_cycle` string — Next agent
    - `agent_cycle_reverse` string — Previous agent
    - `input_clear` string — Clear input field
    - `input_paste` string — Paste from clipboard
    - `input_submit` string — Submit input
    - `input_newline` string — Insert newline in input
    - `input_move_left` string — Move cursor left in input
    - `input_move_right` string — Move cursor right in input
    - `input_move_up` string — Move cursor up in input
    - `input_move_down` string — Move cursor down in input
    - `input_select_left` string — Select left in input
    - `input_select_right` string — Select right in input
    - `input_select_up` string — Select up in input
    - `input_select_down` string — Select down in input
    - `input_line_home` string — Move to start of line in input
    - `input_line_end` string — Move to end of line in input
    - `input_select_line_home` string — Select to start of line in input
    - `input_select_line_end` string — Select to end of line in input
    - `input_visual_line_home` string — Move to start of visual line in input
    - `input_visual_line_end` string — Move to end of visual line in input
    - `input_select_visual_line_home` string — Select to start of visual line in input
    - `input_select_visual_line_end` string — Select to end of visual line in input
    - `input_buffer_home` string — Move to start of buffer in input
    - `input_buffer_end` string — Move to end of buffer in input
    - `input_select_buffer_home` string — Select to start of buffer in input
    - `input_select_buffer_end` string — Select to end of buffer in input
    - `input_delete_line` string — Delete line in input
    - `input_delete_to_line_end` string — Delete to end of line in input
    - `input_delete_to_line_start` string — Delete to start of line in input
    - `input_backspace` string — Backspace in input
    - `input_delete` string — Delete character in input
    - `input_undo` string — Undo in input
    - `input_redo` string — Redo in input
    - `input_word_forward` string — Move word forward in input
    - `input_word_backward` string — Move word backward in input
    - `input_select_word_forward` string — Select word forward in input
    - `input_select_word_backward` string — Select word backward in input
    - `input_delete_word_forward` string — Delete word forward in input
    - `input_delete_word_backward` string — Delete word backward in input
    - `history_previous` string — Previous history item
    - `history_next` string — Next history item
    - `session_child_cycle` string — Next child session
    - `session_child_cycle_reverse` string — Previous child session
    - `terminal_suspend` string — Suspend terminal
  - `tui` object — TUI specific settings
    - `scroll_speed` number — TUI scroll speed
    - `scroll_acceleration` object — Scroll acceleration settings
      - `enabled` boolean, required — Enable scroll acceleration
    - `diff_style` 'auto' | 'stacked' — Control diff rendering style: 'auto' adapts to terminal width, 'stacked' always shows single column
  - `command` object — Command configuration, see https://usearctic.sh/docs/commands
  - `watcher` object
    - `ignore` string[]
  - `plugin` string[]
  - `snapshot` boolean
  - `share` 'manual' | 'auto' | 'disabled' — Control sharing behavior:'manual' allows manual sharing via commands, 'auto' enables automatic sharing, 'disabled' disables all sharing
  - `autoshare` boolean — @deprecated Use 'share' field instead. Share newly created sessions automatically
  - `autoupdate` union — Automatically update to the latest version. Set to true to auto-update, false to disable, or 'notify' to show update notifications
    - boolean
    - 'notify'
  - `disabled_providers` string[] — Disable providers that are loaded automatically
  - `enabled_providers` string[] — When set, ONLY these providers will be enabled. All other providers will be ignored
  - `model` string — Model to use in the format of provider/model, eg anthropic/claude-2
  - `small_model` string — Small model to use for tasks like title generation in the format of provider/model
  - `username` string — Custom username to display in conversations instead of system username
  - `mode` object — @deprecated Use `agent` field instead.
    - `build` AgentConfig
      - `model` string
      - `temperature` number
      - `top_p` number
      - `prompt` string
      - `tools` object
      - `disable` boolean
      - `description` string — Description of when to use the agent
      - `mode` 'subagent' | 'primary' | 'all'
      - `color` string — Hex color code for the agent (e.g., #FF5733)
      - `maxSteps` integer — Maximum number of agentic iterations before forcing text-only response
      - `permission` object
        - `edit` 'ask' | 'allow' | 'deny'
        - `bash` union
          - 'ask' | 'allow' | 'deny'
          - object
        - `webfetch` 'ask' | 'allow' | 'deny'
        - `doom_loop` 'ask' | 'allow' | 'deny'
        - `external_directory` 'ask' | 'allow' | 'deny'
    - `plan` AgentConfig
      - `model` string
      - `temperature` number
      - `top_p` number
      - `prompt` string
      - `tools` object
      - `disable` boolean
      - `description` string — Description of when to use the agent
      - `mode` 'subagent' | 'primary' | 'all'
      - `color` string — Hex color code for the agent (e.g., #FF5733)
      - `maxSteps` integer — Maximum number of agentic iterations before forcing text-only response
      - `permission` object
        - `edit` 'ask' | 'allow' | 'deny'
        - `bash` union
          - 'ask' | 'allow' | 'deny'
          - object
        - `webfetch` 'ask' | 'allow' | 'deny'
        - `doom_loop` 'ask' | 'allow' | 'deny'
        - `external_directory` 'ask' | 'allow' | 'deny'
  - `agent` object — Agent configuration, see https://usearctic.sh/docs/agent
    - `plan` AgentConfig
      - `model` string
      - `temperature` number
      - `top_p` number
      - `prompt` string
      - `tools` object
      - `disable` boolean
      - `description` string — Description of when to use the agent
      - `mode` 'subagent' | 'primary' | 'all'
      - `color` string — Hex color code for the agent (e.g., #FF5733)
      - `maxSteps` integer — Maximum number of agentic iterations before forcing text-only response
      - `permission` object
        - `edit` 'ask' | 'allow' | 'deny'
        - `bash` union
          - 'ask' | 'allow' | 'deny'
          - object
        - `webfetch` 'ask' | 'allow' | 'deny'
        - `doom_loop` 'ask' | 'allow' | 'deny'
        - `external_directory` 'ask' | 'allow' | 'deny'
    - `build` AgentConfig
      - `model` string
      - `temperature` number
      - `top_p` number
      - `prompt` string
      - `tools` object
      - `disable` boolean
      - `description` string — Description of when to use the agent
      - `mode` 'subagent' | 'primary' | 'all'
      - `color` string — Hex color code for the agent (e.g., #FF5733)
      - `maxSteps` integer — Maximum number of agentic iterations before forcing text-only response
      - `permission` object
        - `edit` 'ask' | 'allow' | 'deny'
        - `bash` union
          - 'ask' | 'allow' | 'deny'
          - object
        - `webfetch` 'ask' | 'allow' | 'deny'
        - `doom_loop` 'ask' | 'allow' | 'deny'
        - `external_directory` 'ask' | 'allow' | 'deny'
    - `general` AgentConfig
      - `model` string
      - `temperature` number
      - `top_p` number
      - `prompt` string
      - `tools` object
      - `disable` boolean
      - `description` string — Description of when to use the agent
      - `mode` 'subagent' | 'primary' | 'all'
      - `color` string — Hex color code for the agent (e.g., #FF5733)
      - `maxSteps` integer — Maximum number of agentic iterations before forcing text-only response
      - `permission` object
        - `edit` 'ask' | 'allow' | 'deny'
        - `bash` union
          - 'ask' | 'allow' | 'deny'
          - object
        - `webfetch` 'ask' | 'allow' | 'deny'
        - `doom_loop` 'ask' | 'allow' | 'deny'
        - `external_directory` 'ask' | 'allow' | 'deny'
    - `explore` AgentConfig
      - `model` string
      - `temperature` number
      - `top_p` number
      - `prompt` string
      - `tools` object
      - `disable` boolean
      - `description` string — Description of when to use the agent
      - `mode` 'subagent' | 'primary' | 'all'
      - `color` string — Hex color code for the agent (e.g., #FF5733)
      - `maxSteps` integer — Maximum number of agentic iterations before forcing text-only response
      - `permission` object
        - `edit` 'ask' | 'allow' | 'deny'
        - `bash` union
          - 'ask' | 'allow' | 'deny'
          - object
        - `webfetch` 'ask' | 'allow' | 'deny'
        - `doom_loop` 'ask' | 'allow' | 'deny'
        - `external_directory` 'ask' | 'allow' | 'deny'
  - `provider` object — Custom provider configurations and model overrides
  - `mcp` object — MCP (Model Context Protocol) server configurations
  - `formatter` union
    - false
    - object
  - `lsp` union
    - false
    - object
  - `instructions` string[] — Additional instruction files or patterns to include
  - `layout` 'auto' | 'stretch' — @deprecated Always uses stretch layout.
  - `permission` object
    - `edit` 'ask' | 'allow' | 'deny'
    - `bash` union
      - 'ask' | 'allow' | 'deny'
      - object
    - `webfetch` 'ask' | 'allow' | 'deny'
    - `doom_loop` 'ask' | 'allow' | 'deny'
    - `external_directory` 'ask' | 'allow' | 'deny'
  - `tools` object
  - `enterprise` object
    - `url` string — Enterprise URL
  - `experimental` object
    - `hook` object
      - `file_edited` object
      - `session_completed` object[]
        - `command` string[], required
        - `environment` object
    - `chatMaxRetries` number — Number of retries for chat completions on failure
    - `disable_paste_summary` boolean
    - `batch_tool` boolean — Enable the batch tool
    - `openTelemetry` boolean — Enable OpenTelemetry spans for AI SDK calls (using the 'experimental_telemetry' flag)
    - `primary_tools` string[] — Tools that should only be available to primary agents.

## Response `200`

Successfully updated config

- Config
  - `$schema` string — JSON schema reference for configuration validation
  - `theme` string — Theme name to use for the interface
  - `keybinds` KeybindsConfig — Custom keybind configurations
    - `leader` string — Leader key for keybind combinations
    - `app_exit` string — Exit the application
    - `editor_open` string — Open external editor
    - `theme_list` string — List available themes
    - `sidebar_toggle` string — Toggle sidebar
    - `scrollbar_toggle` string — Toggle session scrollbar
    - `username_toggle` string — Toggle username visibility
    - `status_view` string — View status
    - `session_export` string — Export session to editor
    - `session_new` string — Create a new session
    - `session_list` string — List all sessions
    - `session_timeline` string — Show session timeline
    - `session_share` string — Share current session
    - `session_unshare` string — Unshare current session
    - `session_interrupt` string — Interrupt current session
    - `session_compact` string — Compact the session
    - `messages_page_up` string — Scroll messages up by one page
    - `messages_page_down` string — Scroll messages down by one page
    - `messages_half_page_up` string — Scroll messages up by half page
    - `messages_half_page_down` string — Scroll messages down by half page
    - `messages_first` string — Navigate to first message
    - `messages_last` string — Navigate to last message
    - `messages_last_user` string — Navigate to last user message
    - `messages_copy` string — Copy message
    - `messages_undo` string — Undo message
    - `messages_redo` string — Redo message
    - `messages_toggle_conceal` string — Toggle code block concealment in messages
    - `tool_details` string — Toggle tool details visibility
    - `model_list` string — List available models
    - `model_cycle_recent` string — Next recently used model
    - `model_cycle_recent_reverse` string — Previous recently used model
    - `command_list` string — List available commands
    - `agent_list` string — List agents
    - `agent_cycle` string — Next agent
    - `agent_cycle_reverse` string — Previous agent
    - `input_clear` string — Clear input field
    - `input_paste` string — Paste from clipboard
    - `input_submit` string — Submit input
    - `input_newline` string — Insert newline in input
    - `input_move_left` string — Move cursor left in input
    - `input_move_right` string — Move cursor right in input
    - `input_move_up` string — Move cursor up in input
    - `input_move_down` string — Move cursor down in input
    - `input_select_left` string — Select left in input
    - `input_select_right` string — Select right in input
    - `input_select_up` string — Select up in input
    - `input_select_down` string — Select down in input
    - `input_line_home` string — Move to start of line in input
    - `input_line_end` string — Move to end of line in input
    - `input_select_line_home` string — Select to start of line in input
    - `input_select_line_end` string — Select to end of line in input
    - `input_visual_line_home` string — Move to start of visual line in input
    - `input_visual_line_end` string — Move to end of visual line in input
    - `input_select_visual_line_home` string — Select to start of visual line in input
    - `input_select_visual_line_end` string — Select to end of visual line in input
    - `input_buffer_home` string — Move to start of buffer in input
    - `input_buffer_end` string — Move to end of buffer in input
    - `input_select_buffer_home` string — Select to start of buffer in input
    - `input_select_buffer_end` string — Select to end of buffer in input
    - `input_delete_line` string — Delete line in input
    - `input_delete_to_line_end` string — Delete to end of line in input
    - `input_delete_to_line_start` string — Delete to start of line in input
    - `input_backspace` string — Backspace in input
    - `input_delete` string — Delete character in input
    - `input_undo` string — Undo in input
    - `input_redo` string — Redo in input
    - `input_word_forward` string — Move word forward in input
    - `input_word_backward` string — Move word backward in input
    - `input_select_word_forward` string — Select word forward in input
    - `input_select_word_backward` string — Select word backward in input
    - `input_delete_word_forward` string — Delete word forward in input
    - `input_delete_word_backward` string — Delete word backward in input
    - `history_previous` string — Previous history item
    - `history_next` string — Next history item
    - `session_child_cycle` string — Next child session
    - `session_child_cycle_reverse` string — Previous child session
    - `terminal_suspend` string — Suspend terminal
  - `tui` object — TUI specific settings
    - `scroll_speed` number — TUI scroll speed
    - `scroll_acceleration` object — Scroll acceleration settings
      - `enabled` boolean, required — Enable scroll acceleration
    - `diff_style` 'auto' | 'stacked' — Control diff rendering style: 'auto' adapts to terminal width, 'stacked' always shows single column
  - `command` object — Command configuration, see https://usearctic.sh/docs/commands
  - `watcher` object
    - `ignore` string[]
  - `plugin` string[]
  - `snapshot` boolean
  - `share` 'manual' | 'auto' | 'disabled' — Control sharing behavior:'manual' allows manual sharing via commands, 'auto' enables automatic sharing, 'disabled' disables all sharing
  - `autoshare` boolean — @deprecated Use 'share' field instead. Share newly created sessions automatically
  - `autoupdate` union — Automatically update to the latest version. Set to true to auto-update, false to disable, or 'notify' to show update notifications
    - boolean
    - 'notify'
  - `disabled_providers` string[] — Disable providers that are loaded automatically
  - `enabled_providers` string[] — When set, ONLY these providers will be enabled. All other providers will be ignored
  - `model` string — Model to use in the format of provider/model, eg anthropic/claude-2
  - `small_model` string — Small model to use for tasks like title generation in the format of provider/model
  - `username` string — Custom username to display in conversations instead of system username
  - `mode` object — @deprecated Use `agent` field instead.
    - `build` AgentConfig
      - `model` string
      - `temperature` number
      - `top_p` number
      - `prompt` string
      - `tools` object
      - `disable` boolean
      - `description` string — Description of when to use the agent
      - `mode` 'subagent' | 'primary' | 'all'
      - `color` string — Hex color code for the agent (e.g., #FF5733)
      - `maxSteps` integer — Maximum number of agentic iterations before forcing text-only response
      - `permission` object
        - `edit` 'ask' | 'allow' | 'deny'
        - `bash` union
          - 'ask' | 'allow' | 'deny'
          - object
        - `webfetch` 'ask' | 'allow' | 'deny'
        - `doom_loop` 'ask' | 'allow' | 'deny'
        - `external_directory` 'ask' | 'allow' | 'deny'
    - `plan` AgentConfig
      - `model` string
      - `temperature` number
      - `top_p` number
      - `prompt` string
      - `tools` object
      - `disable` boolean
      - `description` string — Description of when to use the agent
      - `mode` 'subagent' | 'primary' | 'all'
      - `color` string — Hex color code for the agent (e.g., #FF5733)
      - `maxSteps` integer — Maximum number of agentic iterations before forcing text-only response
      - `permission` object
        - `edit` 'ask' | 'allow' | 'deny'
        - `bash` union
          - 'ask' | 'allow' | 'deny'
          - object
        - `webfetch` 'ask' | 'allow' | 'deny'
        - `doom_loop` 'ask' | 'allow' | 'deny'
        - `external_directory` 'ask' | 'allow' | 'deny'
  - `agent` object — Agent configuration, see https://usearctic.sh/docs/agent
    - `plan` AgentConfig
      - `model` string
      - `temperature` number
      - `top_p` number
      - `prompt` string
      - `tools` object
      - `disable` boolean
      - `description` string — Description of when to use the agent
      - `mode` 'subagent' | 'primary' | 'all'
      - `color` string — Hex color code for the agent (e.g., #FF5733)
      - `maxSteps` integer — Maximum number of agentic iterations before forcing text-only response
      - `permission` object
        - `edit` 'ask' | 'allow' | 'deny'
        - `bash` union
          - 'ask' | 'allow' | 'deny'
          - object
        - `webfetch` 'ask' | 'allow' | 'deny'
        - `doom_loop` 'ask' | 'allow' | 'deny'
        - `external_directory` 'ask' | 'allow' | 'deny'
    - `build` AgentConfig
      - `model` string
      - `temperature` number
      - `top_p` number
      - `prompt` string
      - `tools` object
      - `disable` boolean
      - `description` string — Description of when to use the agent
      - `mode` 'subagent' | 'primary' | 'all'
      - `color` string — Hex color code for the agent (e.g., #FF5733)
      - `maxSteps` integer — Maximum number of agentic iterations before forcing text-only response
      - `permission` object
        - `edit` 'ask' | 'allow' | 'deny'
        - `bash` union
          - 'ask' | 'allow' | 'deny'
          - object
        - `webfetch` 'ask' | 'allow' | 'deny'
        - `doom_loop` 'ask' | 'allow' | 'deny'
        - `external_directory` 'ask' | 'allow' | 'deny'
    - `general` AgentConfig
      - `model` string
      - `temperature` number
      - `top_p` number
      - `prompt` string
      - `tools` object
      - `disable` boolean
      - `description` string — Description of when to use the agent
      - `mode` 'subagent' | 'primary' | 'all'
      - `color` string — Hex color code for the agent (e.g., #FF5733)
      - `maxSteps` integer — Maximum number of agentic iterations before forcing text-only response
      - `permission` object
        - `edit` 'ask' | 'allow' | 'deny'
        - `bash` union
          - 'ask' | 'allow' | 'deny'
          - object
        - `webfetch` 'ask' | 'allow' | 'deny'
        - `doom_loop` 'ask' | 'allow' | 'deny'
        - `external_directory` 'ask' | 'allow' | 'deny'
    - `explore` AgentConfig
      - `model` string
      - `temperature` number
      - `top_p` number
      - `prompt` string
      - `tools` object
      - `disable` boolean
      - `description` string — Description of when to use the agent
      - `mode` 'subagent' | 'primary' | 'all'
      - `color` string — Hex color code for the agent (e.g., #FF5733)
      - `maxSteps` integer — Maximum number of agentic iterations before forcing text-only response
      - `permission` object
        - `edit` 'ask' | 'allow' | 'deny'
        - `bash` union
          - 'ask' | 'allow' | 'deny'
          - object
        - `webfetch` 'ask' | 'allow' | 'deny'
        - `doom_loop` 'ask' | 'allow' | 'deny'
        - `external_directory` 'ask' | 'allow' | 'deny'
  - `provider` object — Custom provider configurations and model overrides
  - `mcp` object — MCP (Model Context Protocol) server configurations
  - `formatter` union
    - false
    - object
  - `lsp` union
    - false
    - object
  - `instructions` string[] — Additional instruction files or patterns to include
  - `layout` 'auto' | 'stretch' — @deprecated Always uses stretch layout.
  - `permission` object
    - `edit` 'ask' | 'allow' | 'deny'
    - `bash` union
      - 'ask' | 'allow' | 'deny'
      - object
    - `webfetch` 'ask' | 'allow' | 'deny'
    - `doom_loop` 'ask' | 'allow' | 'deny'
    - `external_directory` 'ask' | 'allow' | 'deny'
  - `tools` object
  - `enterprise` object
    - `url` string — Enterprise URL
  - `experimental` object
    - `hook` object
      - `file_edited` object
      - `session_completed` object[]
        - `command` string[], required
        - `environment` object
    - `chatMaxRetries` number — Number of retries for chat completions on failure
    - `disable_paste_summary` boolean
    - `batch_tool` boolean — Enable the batch tool
    - `openTelemetry` boolean — Enable OpenTelemetry spans for AI SDK calls (using the 'experimental_telemetry' flag)
    - `primary_tools` string[] — Tools that should only be available to primary agents.

## Other responses

- `400` — Bad request

---

[API](https://skmtc.net/arctic-cli/apis/arctic.md) · [All operations](https://skmtc.net/arctic-cli/apis/arctic/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arctic-cli/arctic/versions/d64a58bed245/schema)