Documentation

Configuration

Read and patch the merged nikcli config, reload it from disk, resolve the provider table, and manage MCP server entries and config profiles.

Playground

Send these requests to your own running server. Values stay in this browser.

Not connected

Base URL Directory optional Bearer token optional

How this works

Start a server with nikcli serve --hostname 127.0.0.1 --port 4096. Requests go straight from this page to that address — the browser allows it because loopback counts as a secure origin, and the server allows it because nikcli-ai.dev is in its CORS allowlist.

To try things without touching your real sessions or config, start the server with NIKCLI_TEST_HOME pointed at a throwaway directory — see the guided tour.

Operations

10 endpoints, generated from the server's own OpenAPI document. Every path also accepts the directory and workspace query parameters that select which instance handles the request.

get	/config	config.get
patch	/config	config.update
get	/config/providers	config.providers
post	/config/reload	config.reload
post	/config/mcp	postConfigMcp
patch	/config/mcp/{name}	patchConfigMcp:name
delete	/config/mcp/{name}	deleteConfigMcp:name
get	/config/profiles	getConfigProfiles
post	/config/profiles	postConfigProfiles
post	/config/profiles/activate/{name}	postConfigProfilesActivate:name

get /config # config.get

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Responses

200 Config application/json

{
  [key: string]: unknown
}

Example response from schema

{}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

config.get

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.config.get({
  ...
})

Try it

directory query workspace query

patch /config # config.update

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Request body · required · application/json

{
  [key: string]: unknown
}

Responses

200 Config application/json

{
  [key: string]: unknown
}

400 ConfigUpdateError application/json

{
  name: string
  data: { [key: string]: unknown }
}

Example response from schema

{}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

config.update

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.config.update({
  ...
})

Try it

directory query workspace query

Request body application/json

get /config/providers # config.providers

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Responses

200 ConfigProviders application/json

{
  providers: Provider[]
  default: {
    [key: string]: string
  }
}

Example response from schema

{
  "providers": [
    {
      "id": "",
      "name": "",
      "source": "env",
      "env": [],
      "key": "",
      "options": {},
      "models": {}
    }
  ],
  "default": {}
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

config.providers

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.config.providers({
  ...
})

Try it

directory query workspace query

post /config/reload # config.reload

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Responses

200 ConfigReloadResponse application/json

{
  reloaded: boolean
  directory: string
}

Example response from schema

{
  "reloaded": false,
  "directory": ""
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

config.reload

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.config.reload({
  ...
})

Try it

directory query workspace query

post /config/mcp # postConfigMcp

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Request body · required · application/json

{
  name: string
  config: unknown
}

Responses

200 SuccessFlag application/json

{
  success: boolean
}

Example response from schema

{
  "success": false
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

postConfigMcp

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.postConfigMcp({
  ...
})

Try it

directory query workspace query

Request body application/json

patch /config/mcp/{name} # patchConfigMcp:name

Parameters

Name	In	Type	Required
name	path	string	required
directory	query	string	optional
workspace	query	string	optional

Request body · required · application/json

{ [key: string]: unknown }

Responses

200 SuccessFlag application/json

{
  success: boolean
}

Example response from schema

{
  "success": false
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

patchConfigMcp:name

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.patchConfigMcp:name({
  ...
})

Try it

name path · required directory query workspace query

Request body application/json

delete /config/mcp/{name} # deleteConfigMcp:name

Parameters

Name	In	Type	Required
name	path	string	required
directory	query	string	optional
workspace	query	string	optional

Responses

200 SuccessFlag application/json

{
  success: boolean
}

Example response from schema

{
  "success": false
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

deleteConfigMcp:name

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.deleteConfigMcp:name({
  ...
})

Try it

name path · required directory query workspace query

This changes or removes server state, against whatever base URL is set above.

get /config/profiles # getConfigProfiles

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Responses

200 ConfigProfilesList application/json

{
  profiles: {
    [key: string]: ConfigProfileInfo
  }
  activeProfile: string
}

Example response from schema

{
  "profiles": {},
  "activeProfile": ""
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

getConfigProfiles

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.getConfigProfiles({
  ...
})

Try it

directory query workspace query

post /config/profiles # postConfigProfiles

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Request body · required · application/json

{
  name: string
}

Responses

200 SuccessFlag application/json

{
  success: boolean
}

Example response from schema

{
  "success": false
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

postConfigProfiles

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.postConfigProfiles({
  ...
})

Try it

directory query workspace query

Request body application/json

post /config/profiles/activate/{name} # postConfigProfilesActivate:name

Parameters

Name	In	Type	Required
name	path	string	required
directory	query	string	optional
workspace	query	string	optional

Responses

200 SuccessFlag application/json

{
  success: boolean
}

Example response from schema

{
  "success": false
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

postConfigProfilesActivate:name

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.postConfigProfilesActivate:name({
  ...
})

Try it

name path · required directory query workspace query

Schemas

The 44 schemas reachable from these endpoints. Each is shown one level deep; nested types link to their own entry below. Names ending in _2, _3 and so on are the OpenAPI emitter disambiguating same-named schemas declared by different HttpApi groups — they are distinct shapes, not duplicates.

AdsConfig

{
  enabled?: boolean | null
  ratio?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
  items?: AdsItemConfig[] | null
}

AdsItemConfig

{
  id: string
  text: string
  url?: string | null
  enabled?: boolean | null
}

AgentConfig

{
  [key: string]: unknown | null
}

AttachmentConfig

{
  image?: 
    | {
    auto_resize?: boolean | null
    max_width?: 
      | 
      | number
      | "Infinity" | "-Infinity" | "NaN"
      | null
    max_height?: 
      | 
      | number
      | "Infinity" | "-Infinity" | "NaN"
      | null
    max_base64_bytes?: 
      | 
      | number
      | "Infinity" | "-Infinity" | "NaN"
      | null
  }
    | null
}

AutoModeConfig

{
  environment?: string[] | null
  allow?: string[] | null
  soft_deny?: string[] | null
  hard_deny?: string[] | null
  classify_all_shell?: boolean | null
  model?: string | null
  disable?: boolean | null
}

ComputerConfig

{
  mode?: "sandbox" | "host" | null
  width?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
  height?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
}

Config

{
  [key: string]: unknown
}

ConfigMcpAddInput

{
  name: string
  config: unknown
}

ConfigProfileInfo

{
  mcpCount: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  plugins: string[]
  providerCount: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
}

ConfigProfilesList

{
  profiles: {
    [key: string]: ConfigProfileInfo
  }
  activeProfile: string
}

ConfigProviders

{
  providers: Provider[]
  default: {
    [key: string]: string
  }
}

ConfigReloadResponse

{
  reloaded: boolean
  directory: string
}

ConfigUpdateError

{
  name: string
  data: { [key: string]: unknown }
}

ConnectorDiscord

{
  type: "discord"
  botToken?: string | null
  enabled?: boolean | null
}

ConnectorFigma

{
  type: "figma"
  token?: string | null
  enabled?: boolean | null
}

ConnectorGChat

{
  type: "gchat"
  botToken?: string | null
  enabled?: boolean | null
}

ConnectorGithub

{
  type: "github"
  token?: string | null
  oauthClientId?: string | null
  clientId?: string | null
  enabled?: boolean | null
}

ConnectorLinear

{
  type: "linear"
  botToken?: string | null
  enabled?: boolean | null
}

ConnectorLovable

{
  type: "lovable"
  token?: string | null
  apiKey?: string | null
  enabled?: boolean | null
}

ConnectorSlack

{
  type: "slack"
  botToken?: string | null
  teamId?: string | null
  enabled?: boolean | null
}

ConnectorTeams

{
  type: "teams"
  botToken?: string | null
  enabled?: boolean | null
}

ImageConfig

{
  model?: string | null
  provider?: string | null
}

KeybindsConfig

{
  leader?: string | null
  app_exit?: string | null
  editor_open?: string | null
  theme_list?: string | null
  sidebar_toggle?: string | null
  scrollbar_toggle?: string | null
  username_toggle?: string | null
  status_view?: string | null
  sync_view?: string | null
  session_export?: string | null
  session_new?: string | null
  session_list?: string | null
  session_timeline?: string | null
  session_fork?: string | null
  session_rename?: string | null
  session_delete?: string | null
  session_pin_toggle?: string | null
  session_scope_toggle?: string | null
  session_tab_back?: string | null
  session_tab_forward?: string | null
  session_quick_switch_1?: string | null
  session_quick_switch_2?: string | null
  session_quick_switch_3?: string | null
  session_quick_switch_4?: string | null
  session_quick_switch_5?: string | null
  session_quick_switch_6?: string | null
  session_quick_switch_7?: string | null
  session_quick_switch_8?: string | null
  session_quick_switch_9?: string | null
  stash_delete?: string | null
  model_provider_list?: string | null
  model_favorite_toggle?: string | null
  session_share?: string | null
  session_unshare?: string | null
  session_interrupt?: string | null
  session_codebro_open?: string | null
  subtask_background?: string | null
  subtask_picker?: string | null
  session_compact?: string | null
  messages_page_up?: string | null
  messages_page_down?: string | null
  messages_line_up?: string | null
  messages_line_down?: string | null
  messages_half_page_up?: string | null
  messages_half_page_down?: string | null
  messages_first?: string | null
  messages_last?: string | null
  messages_next?: string | null
  messages_previous?: string | null
  messages_last_user?: string | null
  messages_copy?: string | null
  messages_undo?: string | null
  messages_redo?: string | null
  messages_toggle_conceal?: string | null
  tool_details?: string | null
  model_list?: string | null
  model_cycle_recent?: string | null
  model_cycle_recent_reverse?: string | null
  model_cycle_favorite?: string | null
  model_cycle_favorite_reverse?: string | null
  command_list?: string | null
  agent_list?: string | null
  agent_cycle?: string | null
  agent_cycle_reverse?: string | null
  permission_mode?: string | null
  variant_cycle?: string | null
  input_clear?: string | null
  input_paste?: string | null
  input_submit?: string | null
  input_newline?: string | null
  input_move_left?: string | null
  input_move_right?: string | null
  input_move_up?: string | null
  input_move_down?: string | null
  input_select_left?: string | null
  input_select_right?: string | null
  input_select_up?: string | null
  input_select_down?: string | null
  input_line_home?: string | null
  input_line_end?: string | null
  input_select_line_home?: string | null
  input_select_line_end?: string | null
  input_visual_line_home?: string | null
  input_visual_line_end?: string | null
  input_select_visual_line_home?: string | null
  input_select_visual_line_end?: string | null
  input_buffer_home?: string | null
  input_buffer_end?: string | null
  input_select_buffer_home?: string | null
  input_select_buffer_end?: string | null
  input_delete_line?: string | null
  input_delete_to_line_end?: string | null
  input_delete_to_line_start?: string | null
  input_backspace?: string | null
  input_delete?: string | null
  input_undo?: string | null
  input_redo?: string | null
  input_word_forward?: string | null
  input_word_backward?: string | null
  input_select_word_forward?: string | null
  input_select_word_backward?: string | null
  input_delete_word_forward?: string | null
  input_delete_word_backward?: string | null
  history_previous?: string | null
  history_next?: string | null
  session_child_cycle?: string | null
  session_child_cycle_reverse?: string | null
  session_parent?: string | null
  session_child_close?: string | null
  terminal_suspend?: string | null
  terminal_title_toggle?: string | null
  tips_toggle?: string | null
  voice_record?: string | null
  app_support?: string | null
}

LayoutConfig

"auto" | "stretch"

LogLevel

  | "DEBUG"
  | "INFO"
  | "WARN"
  | "ERROR"

McpLocalConfig

{
  type: "local"
  command: string[]
  environment?: 
    | {
    [key: string]: string
  }
    | null
  enabled?: boolean | null
  timeout?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
}

McpOAuthConfig

{
  clientId?: string | null
  clientSecret?: string | null
  scope?: string | null
}

McpRemoteConfig

{
  type: "remote"
  url: string
  enabled?: boolean | null
  headers?: 
    | {
    [key: string]: string
  }
    | null
  oauth?: McpOAuthConfig | false | null
  timeout?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
}

Model

{
  id: string
  providerID: string
  api: {
    id: string
    url?: string
    npm: string
  }
  name: string
  family?: string
  capabilities: {
    temperature: boolean
    reasoning: boolean
    attachment: boolean
    toolcall: boolean
    input: {
      text: boolean
      audio: boolean
      image: boolean
      video: boolean
      pdf: boolean
    }
    output: {
      text: boolean
      audio: boolean
      image: boolean
      video: boolean
      pdf: boolean
    }
    interleaved: 
      | boolean
      | {
      field: "reasoning_content" | "reasoning_details"
    }
  }
  cost: {
    input: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    output: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    cache: {
      read: 
        | number
        | "Infinity" | "-Infinity" | "NaN"
      write: 
        | number
        | "Infinity" | "-Infinity" | "NaN"
    }
    experimentalOver200K?: {
      input: 
        | number
        | "Infinity" | "-Infinity" | "NaN"
      output: 
        | number
        | "Infinity" | "-Infinity" | "NaN"
      cache: {
        read: 
          | number
          | "Infinity" | "-Infinity" | "NaN"
        write: 
          | number
          | "Infinity" | "-Infinity" | "NaN"
      }
    }
  }
  limit: {
    context: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    input?: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    output: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
  }
  status: 
    | "alpha"
    | "beta"
    | "deprecated"
    | "active"
  options: { [key: string]: unknown }
  headers: {
    [key: string]: string
  }
  release_date: string
  variants?: {
    [key: string]: { [key: string]: unknown }
  }
}

PermissionActionConfig

"ask" | "allow" | "deny"

PermissionConfig

{
  [key: string]: PermissionRuleConfig | null
}

PermissionModeConfig

"default" | "auto"

PermissionObjectConfig

{
  [key: string]: PermissionActionConfig
}

PermissionRuleConfig

PermissionActionConfig | PermissionObjectConfig

PolicyStatementConfig

{
  effect: "allow" | "deny"
  action: string
  resource: string
}

Provider

{
  id: string
  name: string
  source: 
    | "env"
    | "config"
    | "custom"
    | "api"
  env: string[]
  key?: string | null
  options: { [key: string]: unknown }
  models: {
    [key: string]: Model
  }
}

ProviderConfig

{
  api?: string | null
  name?: string | null
  env?: string[] | null
  id?: string | null
  npm?: string | null
  models?: 
    | {
    [key: string]: {
      id?: string | null
      name?: string | null
      family?: string | null
      release_date?: string | null
      attachment?: boolean | null
      reasoning?: boolean | null
      temperature?: boolean | null
      tool_call?: boolean | null
      interleaved?: 
        | 
        | true
        | {
        field: "reasoning_content" | "reasoning_details"
      }
        | null
      cost?: 
        | {
        input: 
          | number
          | "Infinity" | "-Infinity" | "NaN"
        output: 
          | number
          | "Infinity" | "-Infinity" | "NaN"
        cache_read?: 
          | 
          | number
          | "Infinity" | "-Infinity" | "NaN"
          | null
        cache_write?: 
          | 
          | number
          | "Infinity" | "-Infinity" | "NaN"
          | null
        context_over_200k?: 
          | {
          input: 
            | number
            | "Infinity" | "-Infinity" | "NaN"
          output: 
            | number
            | "Infinity" | "-Infinity" | "NaN"
          cache_read?: 
            | 
            | number
            | "Infinity" | "-Infinity" | "NaN"
            | null
          cache_write?: 
            | 
            | number
            | "Infinity" | "-Infinity" | "NaN"
            | null
        }
          | null
      }
        | null
      limit?: 
        | {
        context: 
          | number
          | "Infinity" | "-Infinity" | "NaN"
        input?: 
          | 
          | number
          | "Infinity" | "-Infinity" | "NaN"
          | null
        output: 
          | number
          | "Infinity" | "-Infinity" | "NaN"
      }
        | null
      modalities?: 
        | {
        input: (
          | "text"
          | "audio"
          | "image"
          | "video"
          | "pdf")[]
        output: (
          | "text"
          | "audio"
          | "image"
          | "video"
          | "pdf")[]
      }
        | null
      experimental?: boolean | null
      status?: "alpha" | "beta" | "deprecated" | null
      options?: { [key: string]: unknown } | null
      headers?: 
        | {
        [key: string]: string
      }
        | null
      provider?: 
        | {
        npm: string
        api: string
      }
        | null
      reasoning_options?: 
        | (
        | {
        type: "effort"
        values: (string | null)[]
      }
        | {
        type: "toggle"
      }
        | {
        type: "budget_tokens"
        min?: 
          | 
          | number
          | "Infinity" | "-Infinity" | "NaN"
          | null
        max?: 
          | 
          | number
          | "Infinity" | "-Infinity" | "NaN"
          | null
      })[]
        | null
      variants?: 
        | {
        [key: string]: {
          [key: string]: unknown | null
        }
      }
        | null
      disabled?: boolean | null
    }
  }
    | null
  auth_provider?: string | null
  whitelist?: string[] | null
  blacklist?: string[] | null
  options?: 
    | {
    [key: string]: unknown | null
  }
    | null
}

RagConfig

{
  model?: string | null
  provider?: string | null
}

ReferenceConfig

  | {
  type: "git"
  repository: string
  branch?: string | null
  description?: string | null
}
  | {
  type: "local"
  path: string
  description?: string | null
}

RemoteConfig

{
  enabled?: boolean | null
  enableTunnel?: boolean | null
  provider?: 
    | 
    | "localtunnel"
    | "cloudflared"
    | "ngrok"
    | "remotosh"
    | "none"
    | null
  askOnExistingSession?: boolean | null
}

ServerConfig

{
  port?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
  hostname?: string | null
  mdns?: boolean | null
  cors?: string[] | null
}

SpeakConfig

{
  provider?: string | null
  model?: string | null
  modelId?: string | null
  outputFormat?: string | null
}

SuccessFlag

{
  success: boolean
}

TeleportConfig

{
  url?: string | null
  token?: string | null
}