Configuration Options

Kulala can be configured with the following options.

Full example

Here is a full example of setting up the Kulala plugin with the available opts:

kulala.nvim/lua/config/defaults.lua
local M = {
  kulala_core = {
    path = nil,
    timeout = nil,
    data_dir = nil,
  },
  default_env = "default",
  vscode_rest_client_environmentvars = false,

  halt_on_error = true,

  contenttypes = {},

  ui = {},

  lsp = {
    enable = true,
    filetypes = { "http", "rest", "json", "yaml", "bruno" },
    keymaps = false,
    formatter = {},
    on_attach = nil,
  },

  debug = 3,
  generate_bug_report = false,
  global_keymaps = false,
  global_keymaps_prefix = "<leader>R",
  kulala_keymaps = true,
  kulala_keymaps_prefix = "",
}

return M

kulala_core.path

Optional path to the kulala-core executable (https://github.com/mistweaverco/kulala-core). When set, this path is used exclusively. When nil (default), auto-download and use kulala-core from GitHub releases based on the user's OS and architecture.

Example:

{
  "mistweaverco/kulala.nvim",
  opts = {
    kulala_core: {
      path = "/home/bonobo/.local/bin/kulala-core",
    },
  },
}

kulala_core.timeout

Optional subprocess timeout (ms) for kulala-core. Default is 60000 (1 minute). nil disables the vim.system timeout.

Example:

{
  "mistweaverco/kulala.nvim",
  opts = {
    kulala_core: {
      timeout = 60000, -- timeout in milliseconds
    },
  },
}

kulala_core.data_dir

Optional override for kulala-core persistence (cookies, OAuth, prompts).

Default matches kulala-core CLI:

Linux: ~/.local/share/kulala-core or $XDG_DATA_HOME/kulala-core
macOS: ~/Library/Application or Support/kulala-core
Windows: %APPDATA%\kulala-core

Example:

{
  "mistweaverco/kulala.nvim",
  opts = {
    kulala_core: {
      data_dir = vim.fn.stdpath("data") .. "/kulala-core",
    },
  },
}

default_env

Default environment.

See: [Environment files][see-env-files].

Possible values:

[any string]

Default: default

Example:

{
  "mistweaverco/kulala.nvim",
  opts = {
    default_env = "default",
  },
}

vscode_rest_client_environmentvars

If enabled, Kulala searches for .vscode/settings.json or *.code-workspace files in the current directory and its parents to read the rest-client.environmentVariables definitions.

If http-client.env.json is also present, it'll be merged (and overwrites variables from VSCode).

Possible values:

true
false

Default: false

Example:

{
  "mistweaverco/kulala.nvim",
  opts = {
    vscode_rest_client_environmentvars = true,
  },
}

contenttypes

Filetypes, formatters and path resolvers are defined for each content-type in an hash array.

Default:

contenttypes = {
  ["application/json"] = {
    ft = "json",
    formatter = vim.fn.executable("jq") == 1 and { "jq", "." },
    pathresolver = function(...)
      return require("kulala.parser.jsonpath").parse(...)
    end,
  },
  ["application/graphql"] = {
    ft = "graphql",
    formatter = vim.fn.executable("prettier") == 1 and { "prettier", "--stdin-filepath", "file.graphql" },
    pathresolver = nil,
  },
  ["application/javascript"] = {
    ft = "javascript",
    formatter = vim.fn.executable("prettier") == 1 and { "prettier", "--stdin-filepath", "file.js" },
    pathresolver = nil,
  },
  ["application/lua"] = {
    ft = "lua",
    formatter = vim.fn.executable("stylua") == 1 and { "stylua", "-" },
    pathresolver = nil,
  },
  ["application/graphql-response+json"] = "application/json",
  ["application/xml"] = {
    ft = "xml",
    formatter = vim.fn.executable("xmllint") == 1 and { "xmllint", "--format", "-" },
    pathresolver = vim.fn.executable("xmllint") == 1 and { "xmllint", "--xpath", "{{path}}", "-" },
  },
  ["text/html"] = {
    ft = "html",
    formatter = vim.fn.executable("prettier") == 1 and { "prettier", "--stdin-filepath", "file.html" },
    pathresolver = nil,
  },
},

contenttypes.ft

Default filetype for the given content type.

Possible values:

Any filetype (:help filetype) neovim supports.

Default:

contenttypes = {
  ["application/json"] = {
    ft = "json",
  },
  ["application/xml"] = {
    ft = "xml",
  },
  ["text/html"] = {
    ft = "html",
  },

Example:

{
  "mistweaverco/kulala.nvim",
  opts = {
    contenttypes = {
      ["text/xml"] = {
        ft = "xml",
      },
    },
  },
}

contenttypes.formatter

Formatters take the response body and produce a beautified / more human readable output.

Possible values:

You can define a commandline which processes the body. The body will be piped as stdin and the output will be used as the formatted body.
You can define a lua function formatted_body = function(body) which returns the formatted body.

Default:

  contenttypes = {
    ["application/json"] = {
      ft = "json",
      formatter = vim.fn.executable("jq") == 1 and { "jq", "." },
      pathresolver = function(...)
        return require("kulala.parser.jsonpath").parse(...)
      end,
    },
    ["application/graphql"] = {
      ft = "graphql",
      formatter = vim.fn.executable("prettier") == 1 and { "prettier", "--stdin-filepath", "file.graphql" },
      pathresolver = nil,
    },
    ["application/javascript"] = {
      ft = "javascript",
      formatter = vim.fn.executable("prettier") == 1 and { "prettier", "--stdin-filepath", "file.js" },
      pathresolver = nil,
    },
    ["application/lua"] = {
      ft = "lua",
      formatter = vim.fn.executable("stylua") == 1 and { "stylua", "-" },
      pathresolver = nil,
    },
    ["application/graphql-response+json"] = "application/json",
    ["application/xml"] = {
      ft = "xml",
      formatter = vim.fn.executable("xmllint") == 1 and { "xmllint", "--format", "-" },
      pathresolver = vim.fn.executable("xmllint") == 1 and { "xmllint", "--xpath", "{{path}}", "-" },
    },
    ["text/html"] = {
      ft = "html",
      formatter = vim.fn.executable("prettier") == 1 and { "prettier", "--stdin-filepath", "file.html" },
      pathresolver = nil,
    },
  },

Example:

{
  "mistweaverco/kulala.nvim",
  opts = {
    contenttypes = {
      ["text/plain"] = {
        formatter = function(body)
          return body:lower()
        end,
      },
    },
  },
}

contenttypes.pathresolver

You can use Request Variables to read values from requests / responses. To access a specific value inside a body Kulala gives you the possibility to define a path for it.

This is normally JSONPath for JSON or XPath for XML, but can be individually defined for any content type.

Possible values:

You can use an external program which receives the full body as stdin and has to return the selected value in stdout. The placeholder {{path}} can be used in any string of this definition and will be replaced by the actual path (after body.).
Alternative you can give a lua function of value = function(body, path).

Default:

Kulala has implemented a basic JSONPath parser which supports object traversal including array index access.

For full JSONPath support you need to use an external program like jsonpath-cli or jp.

contenttypes = {
  ["application/json"] = {
    pathresolver = require("kulala.parser.jsonpath").parse,
  },
  ["application/xml"] = {
    pathresolver = { "xmllint", "--xpath", "{{path}}", "-" },
  },
  ["text/html"] = {
    pathresolver = nil,
  },
}

Example:

{
  "mistweaverco/kulala.nvim",
  opts = {
    contenttypes = {
      ["text/xml"] = {
        pathresolver = { "xmllint", "--xpath", "{{path}}", "-" },
      },
    },
  },
}

debug

Enable debug mode.

Possible values:

true - enable debug mode
false - disable debug mode
1/2/3 - set log level
- 0 = silence all notifications
- 1 = only error
- 2 = error and warn
- 3 = error, warn and info
- 4 = debug

Default: false

Example:

{
  "mistweaverco/kulala.nvim",
  opts = {
    debug = false,
  },
}

generate_bug_report

Generate a bug report on error.

Default: false

UI Options

ui.display_mode

The display mode.

Can be either split or float.

Default: split

Example:

{
  "mistweaverco/kulala.nvim",
  opts = {
    ui = {
      display_mode = "float",
    }
  },
}

ui.split_direction

Split direction.

Only used when ui.display_mode is set to split.

Possible values:

vertical
horizontal

Default: vertical

Example:

{
  "mistweaverco/kulala.nvim",
  opts = {
    ui = {
      split_direction = "vertical",
    },
  },
}

ui.win_opts

Kualala UI buffer and window options.

Default: {}

Example:

{
  "mistweaverco/kulala.nvim",
  opts = {
    ui = {
      ---@type kulala.ui.win_config
      win_opts = {
        width = 80,
        height = 20,
        split = "vertical",
        bo = { number = true, wrap = true }, -- buffer options
        wo = { foldmethod = "indent" }, -- window options
      },
    },
  },
}

ui.default_view

Default view.

Possible values:

body
headers
headers_body
verbose
script_output
stats
function(response) ... end

Default: body

Example:

{
  "mistweaverco/kulala.nvim",
  opts = {
    ui = {
      default_view = "body",
    },
  },
}

Setting the default view to a function allows you to define a custom view handler, which will be called with the response object and will override default views. The response object has the following properties:

---@class Response
---@field id string
---@field url string
---@field method string
---@field status boolean
---@field code number -- request command code
---@field response_code number -- http response code
---@field duration number
---@field time number
---@field body string
---@field headers string
---@field errors string
---@field stats table|string
---@field script_pre_output string
---@field script_post_output string
---@field assert_output table
---@field assert_status boolean
---@field buf number
---@field buf_name string
---@field line number
  local response = {}

ui.winbar

Enable winbar for result buffer

Possible values:

true
false

Default: true

Example:

{
  "mistweaverco/kulala.nvim",
  opts = {
    ui = {
      winbar = true,
    },
  },
}

ui.default_winbar_panes

Default visible winbar panes

Possible values:

body
headers
headers_body
verbose
script_output
stats
report

Default: body

Example:

{
  "mistweaverco/kulala.nvim",
  opts = {
    ui = {
      default_winbar_panes = { "body", "headers", "headers_body", "verbose" },
    },
  },
}

ui.winbar_labels

Customize Winbar labels

winbar_labels = {
  body = "Body",
  headers = "Headers",
  headers_body = "All",
  verbose = "Verbose",
  script_output = "Script Output",
  stats = "Stats",
  report = "Report",
  help = "Help"
}

ui.winbar_labels_keymaps

Show/hide winbar keymaps in labels

winbar_labels_keymaps = true

ui.show_variable_info_text

Enable/disable variable info text.

Possible values:

false = disable variable info text
"float" = show the variable name and value as float

Default: always

Example:

{
  "mistweaverco/kulala.nvim",
  opts = {
    ui = {
      show_variable_info_text = false,
    },
  },
}

ui.show_icons

Can be used to show loading, done and error icons in inlay hints or signcolumn

Possible values:

"singcolumn"
"on_request"
"above_request"
"below_request"
nil (to disable inlay hints)

If "above_request" or "below_request" is used, the icons will be shown above or below the request line.

Default: "on_request".

ui.icons

Default icons.

Possible values:

inlay = { loading = [string], done = [string], error = [string] }
lualine = [string]

Default:

icons = {
  inlay = {
    loading = "⏳",
    done = "✔",
    error = "✘",
  },
  lualine = "🐼",
  textHighlight = "WarningMsg", -- highlight group for request elapsed time
  loadingHighlight = "Normal",
  doneHighlight = "String",
  errorHighlight = "ErrorMsg",
},

ui.syntax_hl

Highlight groups for http syntax highlighting

{
  opts = {
    ui = {
      ---@type table<string, string|vim.api.keyset.highlight>
      syntax_hl = {
        ["@punctuation.bracket.kulala_http"] = "Number",
        ["@character.special.kulala_http"] = "Special",
        ["@operator.kulala_http"] = "Special",
        ["@variable.kulala_http"] = "String",
        ["@redirect_path.kulala_http"] = "Number",
        ["@external_body_path.kulala_http"] = "String",
      },
    }
  },
}

ui.max_response_size

Do not show responses over maximum size, in bytes

Default: 32768 (32 KB)

ui.max_request_size

Used by Copy as Curl command to determine whether to inline request body or include as a file

Default: 2048 (2 KB)

ui.show_request_summary

Enable/disable request summary in the output window.

Possible values:

true
false

Default: true

Example:

{
  "mistweaverco/kulala.nvim",
  opts = {
    ui = {
      show_request_summary = false,
    },
  },
}

ui.report options

  {
    report = {
      -- possible values: true | false | "on_error"
      show_script_output = true,
      -- possible values: true | false | "on_error" | "failed_only"
      show_asserts_output = true,
      -- possible values: true | false
      show_summary = true,
    }
  }

ui.report.ui.report.show_script_output

Shows/hides the script output. on_error will show the output only when request status is failed.

ui.report.ui.report.show_asserts_output

Shows/hides the assert output. on_error will show the output only when request status is failed, failed_only will show only the failed asserts.

ui.report.ui.report.show_summary

Shows/hides the stats summary of the test results.

ui.scratchpad_default_contents

Scratchpad default contents.

The contents of the scratchpad when it's opened via :lua require('kulala').scratchpad() command.

Possible values:

[table of strings] (each string is a line)

Default:

scratchpad_default_contents = {
  "@MY_TOKEN_NAME=my_token_value",
  "",
  "POST https://httpbin.org/post HTTP/1.1",
  "accept: application/json",
  "content-type: application/json",
  "",
  "{",
  '  "foo": "bar"',
  "}",
}

Example:

{
  "mistweaverco/kulala.nvim",
  opts = {
    ui = {
      scratchpad_default_contents = {
        "@AUTH_USERNAME=my_username",
        "",
        "POST https://httpbin.org/post HTTP/1.1",
        "accept: application/json",
        "content-type: application/json",
        "",
        "{",
        '  "baz": "qux"',
        "}",
      },
    },
  },
}

ui.disable_news_popup

Disable the news popup.

ui.lua_syntax_hl

Enable/disable lua syntax highlighting.

ui.pickers

Settings for pickers used for Environment, Authentication and Requests Managers.

pickers = {
  snacks = {
    layout = function()
      local has_snacks, snacks_picker = pcall(require, "snacks.picker")
      return not has_snacks and {}
        or vim.tbl_deep_extend("force", snacks_picker.config.layout("telescope"), {
          reverse = true,
          layout = {
            { { win = "list" }, { height = 1, win = "input" }, box = "vertical" },
            { win = "preview", width = 0.6 },
            box = "horizontal",
            width = 0.8,
          },
        })
    end,
  },
},

LSP

lsp.enable

Enable/disable Kulala LSP server

lsp.filetypes

Filetypes to attach Kulala LSP to

lsp.keymaps

Enable/disable/customize Kulala LSP keymaps

lsp.formatter

Enable/disable/customize HTTP formatter

lsp.on_attach

Function called when Kulala LSP attaches to the buffer

{
  lsp = {
    enable = true,
    filetypes = { "http", "rest", "json", "yaml", "bruno" },
    keymaps = false, -- disabled by default, as Kulala relies on default Neovim LSP keymaps
    formatter = {
      split_params = 4, -- split query/form parameters onto multiple lines if number of params exceeds this value
      sort = { -- enable/disable alphabetical sorting
        metadata = true,
        variables = true,
        commands = false,
        json = true,
      },
      quote_json_variables = true, -- add quotes around {{variable}} in JSON bodies
      indent = 2, -- base indentation for scripts
    },
    on_attach = function(client, bufnr)
      -- custom on_attach function
    end,
  },
}

Keymaps

global_keymaps

Set to true to enable default keymaps.

Check the keymaps documentation for details.

Default: false

Example:

{
  "mistweaverco/kulala.nvim",
  global_keymaps = true,
}

global_keymaps_prefix

Prefix for global keymaps

{
  global_keymaps_prefix = "<leader>R",
}

kulala_keymaps

Set to true to enable default keymaps for the Kulala UI.

Check the keymaps documentation for details.

Default: true

Example:

{
  "mistweaverco/kulala.nvim",
  kulala_keymaps = false,
}

kulala_keymaps_prefix

Prefix for kulala keymaps

{
  kulala_keymaps_prefix = "",
}

Full example​

kulala_core.path​

kulala_core.timeout​

kulala_core.data_dir​

default_env​

vscode_rest_client_environmentvars​

contenttypes​

contenttypes.ft​

contenttypes.formatter​

contenttypes.pathresolver​

debug​

generate_bug_report​

UI Options​

ui.display_mode​

ui.split_direction​

ui.win_opts​

ui.default_view​

ui.winbar​

ui.default_winbar_panes​

ui.winbar_labels​

ui.winbar_labels_keymaps​

ui.show_variable_info_text​

ui.show_icons​

ui.icons​

ui.syntax_hl​

ui.max_response_size​

ui.max_request_size​

ui.show_request_summary​

ui.report options​

ui.report.ui.report.show_script_output​

ui.report.ui.report.show_asserts_output​

ui.report.ui.report.show_summary​

ui.scratchpad_default_contents​

ui.disable_news_popup​

ui.lua_syntax_hl​

ui.pickers​

LSP​

lsp.enable​

lsp.filetypes​

lsp.keymaps​

lsp.formatter​

lsp.on_attach​

Keymaps​

global_keymaps​

global_keymaps_prefix​

kulala_keymaps​

kulala_keymaps_prefix​

Full example

kulala_core.path

kulala_core.timeout

kulala_core.data_dir

default_env

vscode_rest_client_environmentvars

contenttypes

contenttypes.ft

contenttypes.formatter

contenttypes.pathresolver

debug

generate_bug_report

UI Options

ui.display_mode

ui.split_direction

ui.win_opts

ui.default_view

ui.winbar

ui.default_winbar_panes

ui.winbar_labels

ui.winbar_labels_keymaps

ui.show_variable_info_text

ui.show_icons

ui.icons

ui.syntax_hl

ui.max_response_size

ui.max_request_size

ui.show_request_summary

ui.report options

ui.report.ui.report.show_script_output

ui.report.ui.report.show_asserts_output

ui.report.ui.report.show_summary

ui.scratchpad_default_contents

ui.disable_news_popup

ui.lua_syntax_hl

ui.pickers

LSP

lsp.enable

lsp.filetypes

lsp.keymaps

lsp.formatter

lsp.on_attach

Keymaps

global_keymaps

global_keymaps_prefix

kulala_keymaps

kulala_keymaps_prefix