DOCSEARCHbyAlgolia
Submit Docs

kulala.nvim

repository·main·Indexed 24 days ago

https://github.com/mistweaverco/kulala.nvim

A Neovim plugin providing a powerful interface for making HTTP, GraphQL, gRPC, and WebSocket requests, designed to support the JetBrains .http specification. It features JavaScript/TypeScript scripting, environment variable support, a built-in LSP for autocompletion, and the ability to export requests to Postman collections.

Tokens
7K
Snippets
4
Records
43
Agent score
84%

What's inside kulala.nvim

  1. Overview of kulala.nvim

    main
    kulala.nvim is a fully-featured HTTP, GraphQL, gRPC, and WebSocket client interface for Neovim. It is designed to support the JetBrains .http specification, including full scripting capabilities. It allows developers to execute requests directly from within Neovim and supports advanced features like environment variables, JavaScript/TypeScript scripting, and various authentication methods.

  2. Key features of kulala.nvim

    main

    kulala.nvim provides a comprehensive suite of tools for API interaction:

    • Protocols: HTTP, gRPC, GraphQL, WebSocket, and Streaming.
    • Variables: Supports Environment, Document, Request, Dynamic, Prompt, and http-client.env files.
    • File Management: Import and run requests from external *.http files; import and save request/response data to/from external files.
    • Scripting: JavaScript (JetBrains compatible) and TypeScript support for Pre-request, Post-request, Conditional, Inline, and External scripts.
    • Authentication: Basic, Bearer, Digest, NTLM, OAuth2, Negotiate, AWS, and SSL.
    • Response Handling: Response formatting, live filtering, assertions, automated testing, and reporting.
    • Developer Experience: Built-in LSP completion and a Scratchpad for quick request creation.

  3. Explore related tools: rest.nvim and curl.nvim

    main

    If you are looking for alternatives or complementary tools for HTTP requests in Neovim:

    • rest.nvim: A project that served as early motivation for the development of kulala.nvim.
    • curl.nvim: A lightweight, uncomplicated scratchpad designed for making quick HTTP requests from within Neovim.

  4. Use Kulala in non-.http files

    main

    You can execute requests in any file type by wrapping them in an HTTP code block:

    POST http://localhost:3000
Content-Type: application/json

{"name": "John Doe"}

    If you cannot use a code block, you must position the cursor exactly on the request line or use visual mode to select the request and its accompanying data.

    // You javascript code here
console.log('Hello world!');

/* My test request

```http
POST http://localhost:3000
Content-Type: application/json
{"name": "John Doe"}

    */

  5. Install kulala.nvim via lazy.nvim

    main

    To install kulala.nvim, use the following configuration with lazy.nvim.

    Prerequisites:

    • Neovim 0.12+
    • cURL
    • git
    • tree-sitter-cli

    Architecture Support:

    • MacOS/Linux: x86_64 and arm64
    • Windows: x86_64 only

    Note: cURL is required to download the kulala-core backend, git is required for the kulala-http tree-sitter parser, and tree-sitter-cli is required to generate the parser from the included grammar.

    require("lazy").setup({
  {
    "mistweaverco/kulala.nvim",
    -- Load before session save/restore so VimLeavePre and SessionLoadPost hooks are registered.
    event = { "SessionLoadPost", "VimLeavePre" },
    keys = {
      { "<leader>Rs", desc = "Send request" },
      { "<leader>Ra", desc = "Send all requests" },
      { "<leader>Rb", desc = "Open scratchpad" },
    },
    -- See opts.lsp.enforce_external_script_naming_convention
    -- to restrict LSP capabilities to *.http, *.http.js, *.http.ts and *.http.lua files.
    ft = {"http", "rest", "javascript", "lua"},
    opts = {},
  },
})

  6. Navigate the Kulala UI

    main

    The Kulala UI opens automatically when a request is run, or you can open it manually with <leader>Ro.

    UI Controls:

    • Switch Views: (H) Headers, B (Body), (A) All, (V) Verbose, (S) Stats, (O) Script output, (R) Report.
    • History: Use [ and ] to scroll through previous responses.
    • Clear History: Press X to clear the response history.
    • Jump to Request: Press <CR> to jump to the request in the request buffer.
    • Help: Press ? to open the help window.
    • Scratch Buffer: Press <leader>Rb to open the Kulala scratch buffer.
    • Environments: Press <leader>Re to select a variable environment.
    • Authentication: Press <leader>Ru to manage authentication configurations.

  7. Use Kulala LSP features

    main

    Kulala provides an in-process LSP server for enhanced development. It does not set its own keymaps but relies on your Neovim LSP configuration (e.g., vim.lsp.buf.hover()).

    Features:

    • Autocompletion: HTTP syntax, metadata, commands, variables, requests, GraphQL schema, and Kulala API.
    • Symbols: Search and outline via <leader>cs and <leader>cS.
    • Hover: Inspect requests using your LSP hover command (e.g., K).
    • Code Actions: Access available Kulala commands via gra/<leader>ca.
    • Formatting: Format buffer/range via gq/<leader>cf/<leader>lf.
    • Conversions: In json, yaml, or bruno files, code actions allow converting collections into HTTP format.

    Tip: If using plugins like lspsaga or nvim-lightbulb, you may want to ignore the kulala client to avoid excessive lightbulb icons.

    -- Example: Ignoring kulala in lspsaga
require('lspsaga').setup({
  lightbulb = { ignore = { clients = { 'kulala' } } }
})

-- Example: Ignoring kulala in nvim-lightbulb
require("nvim-lightbulb").setup({
     ignore = { clients = { "kulala" } }
})

  8. Execute REST requests in Kulala

    main

    Kulala allows you to execute HTTP requests directly from your buffer using several methods:

    • Single Request: Position your cursor on the request line or within a request block (delimited by ###) and press <CR> or <leader>Rs.
    • Multiple Requests: Select several requests in visual mode and press <CR> or <leader>Ra.
    • All Requests: Press <leader>Ra to run every request in the current buffer.
    • Search: Press <leader>Rf to search for a specific request in the buffer.
    • Cancel: Press <C-c> to stop an ongoing request.

    Note on Comments: You can use # or // to comment out a request or its data; commented sections will be ignored by the executor.

  9. Manage OAuth2 authentication flows in kulala.nvim

    main

    The kulala.cmd.oauth module provides a comprehensive suite of tools to handle various OAuth2 grant types within Neovim. It manages the lifecycle of authentication, including acquiring tokens, refreshing them, and handling different flows like Authorization Code, Client Credentials, Device Authorization, and Password grants.

    Authentication data is persisted in http-client.private.env.json under the Security.Auth key for the current environment.

  10. How request batching and state preservation works

    main

    To maintain execution-flow state (such as client.global.headers or other session-based data), kulala.nvim can group multiple requests into a single kulala-core execution run.

    When run_parser detects multiple requests, it creates an 'anchor' request and attaches the remaining requests as _kulala_batch_targets. It then calculates a batch_limit and passes these to the core. This ensures that subsequent requests in a batch benefit from the state established by previous requests in that same session.

  11. Configure Treesitter parser handling

    main

    The treesitter configuration block controls how kulala.nvim manages the kulala-http parser.

    • enable: (boolean) If true, kulala.nvim handles downloading, building, and installing the parser and queries. Set to false to manage them manually.
    • cli_path: (string) Path to the tree-sitter CLI. Required for building the parser if enable is true.

  12. Manage WebSocket connections in kulala.nvim

    main

    The kulala.cmd.websocket module provides the logic for handling live WebSocket streams. It manages the connection lifecycle, including connecting to a URL, sending messages, and closing the connection.

    When a WebSocket connection is active, the module handles incoming (<--) and outgoing (-->) messages. If the messages are JSON, you can use jq filters to transform the stream of messages into a structured view.

    Key behaviors:

    • Message Direction: Incoming messages are prefixed with <-- and outgoing with --> in the display.
    • JSON Processing: If messages are valid JSON, the module attempts to build a JSON array of all messages to allow for jq filtering.
    • Persistence: The live WebSocket body is persisted to the file system so the UI can stay in sync.