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
:
{
"mistweaverco/kulala.nvim",
opts = {
-- cURL path
-- if you have curl installed in a non-standard path,
-- you can specify it here
curl_path = "curl",
-- split direction
-- possible values: "vertical", "horizontal"
split_direction = "vertical",
-- default_view, body or headers or headers_body
default_view = "body",
-- dev, test, prod, can be anything
-- see: https://learn.microsoft.com/en-us/aspnet/core/test/http-files?view=aspnetcore-8.0#environment-files
default_env = "dev",
-- enable/disable debug mode
debug = false,
-- default formatters/pathresolver for different content types
contenttypes = {
["application/json"] = {
ft = "json",
formatter = { "jq", "." },
pathresolver = require("kulala.parser.jsonpath").parse,
},
["application/xml"] = {
ft = "xml",
formatter = { "xmllint", "--format", "-" },
pathresolver = { "xmllint", "--xpath", "{{path}}", "-" },
},
["text/html"] = {
ft = "html",
formatter = { "xmllint", "--format", "--html", "-" },
pathresolver = {},
},
},
-- can be used to show loading, done and error icons in inlay hints
-- possible values: "on_request", "above_request", "below_request", or nil to disable
-- If "above_request" or "below_request" is used, the icons will be shown above or below the request line
-- Make sure to have a line above or below the request line to show the icons
show_icons = "on_request",
-- default icons
icons = {
inlay = {
loading = "⏳",
done = "✅",
error = "❌",
},
lualine = "🐼",
},
-- additional cURL options
-- see: https://curl.se/docs/manpage.html
additional_curl_options = {},
-- scratchpad default contents
scratchpad_default_contents = {
"@MY_TOKEN_NAME=my_token_value",
"",
"# @name scratchpad",
"POST https://httpbin.org/post HTTP/1.1",
"accept: application/json",
"content-type: application/json",
"",
"{",
' "foo": "bar"',
"}",
},
-- enable winbar
winbar = false,
-- Specify the panes to be displayed by default
-- Current avaliable pane contains { "body", "headers", "headers_body", "script_output" },
default_winbar_panes = { "body", "headers", "headers_body" },
-- enable reading vscode rest client environment variables
vscode_rest_client_environmentvars = false,
-- disable the vim.print output of the scripts
-- they will be still written to disk, but not printed immediately
disable_script_print_output = false,
-- set scope for environment and request variables
-- possible values: b = buffer, g = global
environment_scope = "b",
-- certificates
certificates = {},
},
}
curl_path
cURL path.
If you have curl
installed in a non-standard path, you can specify it here.
Default: curl
Example:
{
"mistweaverco/kulala.nvim",
opts = {
curl_path = "/home/bonobo/.local/bin/curl",
},
}
split_direction
Split direction.
Possible values:
vertical
horizontal
Default: vertical
Example:
{
"mistweaverco/kulala.nvim",
opts = {
split_direction = "vertical",
},
}
default_view
Default view.
Possible values:
body
headers
headers_body
script_output
Default: body
Example:
{
"mistweaverco/kulala.nvim",
opts = {
default_view = "body",
},
}
default_env
Default environment.
See: Environment files.
Possible values:
[any string]
Default: dev
Example:
{
"mistweaverco/kulala.nvim",
opts = {
default_env = "dev",
},
}
debug
Enable debug mode.
Possible values:
true
false
Default: false
Example:
{
"mistweaverco/kulala.nvim",
opts = {
debug = false,
},
}
contenttypes
Filetypes, formatters and path resolvers are defined for each content-type in an hash array.
Default:
contenttypes = {
["application/json"] = {
ft = "json",
formatter = { "jq", "." },
pathresolver = require("kulala.parser.jsonpath").parse,
},
["application/xml"] = {
ft = "xml",
formatter = { "xmllint", "--format", "-" },
pathresolver = { "xmllint", "--xpath", "{{path}}", "-" },
},
["text/html"] = {
ft = "html",
formatter = { "xmllint", "--format", "--html", "-" },
pathresolver = {},
},
}
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"] = {
formatter = { "jq", "." },
},
["application/xml"] = {
formatter = { "xmllint", "--format", "-" },
},
["text/html"] = {
formatter = { "xmllint", "--format", "--html", "-" },
},
}
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 defintion and will be replaced by the actual path (afterbody.
). - 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}}", "-" },
},
},
},
}
show_icons
Can be used to show loading, done and error icons in inlay hints.
Possible values:
"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.
Make sure to have a line above or below the request line to show the icons.
Default: "on_request"
.
icons
Default icons.
Possible values:
inlay = { loading = [string], done = [string], error = [string] }
lualine = [string]
Default:
icons = {
inlay = {
loading = "⏳",
done = "✅"
error = "❌",
},
lualine = "🐼",
}
Example:
{
"mistweaverco/kulala.nvim",
opts = {
icons = {
inlay = {
loading = "⏳",
done = "✅"
error = "❌",
},
lualine = "🐼",
},
},
}
additional_curl_options
Additional cURL options.
Possible values:
[table of strings]
Default: {}
Example:
{
"mistweaverco/kulala.nvim",
opts = {
additional_curl_options = { "--insecure", "-A", "Mozilla/5.0" },
},
}
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",
"",
"# @name scratchpad",
"POST https://httpbin.org/post HTTP/1.1",
"accept: application/json",
"content-type: application/json",
"",
"{",
' "foo": "bar"',
"}",
}
Example:
{
"mistweaverco/kulala.nvim",
opts = {
scratchpad_default_contents = {
"@AUTH_USERNAME=my_username",
"",
"# @name scratchpad_special_name",
"POST https://httpbin.org/post HTTP/1.1",
"accept: application/json",
"content-type: application/json",
"",
"{",
' "baz": "qux"',
"}",
},
},
}
winbar
Enable winbar for result buffer
Possible values:
true
false
Default: false
Example:
{
"mistweaverco/kulala.nvim",
opts = {
winbar = false,
},
}
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,
},
}
environment_scope
While using request variables the results will be stored for later use. As usual variables they're file relevant and should be stored in the buffer. If you want to share the variables between buffers you can use the global scope.
Possible values:
"b"
(buffer)"g"
(global)
Default: "b"
Example:
{
"mistweaverco/kulala.nvim",
opts = {
environment_scope = "b",
},
}
certificates
A hash array of certificates to be used for requests.
The key is the hostname and optional the port. If no port is given, the certificate will be used for all ports where no dedicated one is defined.
Each certificate definition needs
cert
the path to the certificate filekey
the path to the key files
Example:
{
"mistweaverco/kulala.nvim",
opts = {
certificates = {
["localhost"] = {
cert = vim.fn.stdpath("config") .. "/certs/localhost.crt",
key = vim.fn.stdpath("config") .. "/certs/localhost.key",
},
["www.somewhere.com:8443"] = {
cert = "/home/userx/certs/somewhere.crt",
key = "/home/userx/certs/somewhere.key",
},
},
},
}
Hostnames with prefix *.
will be used as wildcard certificates for the host itself and all subdomains.
*.company.com
will match
company.com
www.company.com
api.company.com
sub.api.company.com
- etc.