kulala-fmt

Install • Usage

An opinionated 🦄 .http and .rest 🐼 files linter 💄 and formatter ⚡.

Install

Just grab the latest release:

• Linux
• Mac
• Windows

Usage

Format all .http and .rest files in the current directory and its subdirectories:

kulala-fmt

Format specific .http and .rest files.

kulala-fmt file1.http file2.rest http/*.http

Format all .http and .rest files in the current directory and its subdirectories and prints the written output to the console:

kulala-fmt --verbose

Format specific .http and .rest files and prints the written output to the console:

kulala-fmt --verbose file1.http file2.rest http/*.http

Check if all .http and .rest files in the current directory and its subdirectories are formatted:

kulala-fmt --check

Check if specific .http and .rest files are formatted:

kulala-fmt --check file1.http file2.rest http/*.http

Check if all .http and .rest files in the current directory and its subdirectories are formatted and prints the desired output to the console:

kulala-fmt --check --verbose

Check if specific .http and .rest files are formatted and prints the desired output to the console:

kulala-fmt --check --verbose file1.http file2.rest http/*.http

What does it do?

• Checks if the file is formatted and valid
• Removes extraneous newlines
• Makes sure document variables are at the top of the file
• Lowercases all headers (when HTTP/2 or HTTP/3) else it will uppercase the first letter
• Puts all metadata right before the request line
• Ensures all comments are using # and not //
• Ensures all comments are at the top of the request

So a perfect request would look like this:

@variables1=value1

# This is a comment
# This is another comment
# @someother metatag
# @name REQUEST_NAME_ONE
GET http://localhost:8080/api/v1/health HTTP/1.1
Content-Type: application/json

{
  "key": "value"
}

or this:

@variables1=value1

# This is a comment
# This is another comment
# @someother metatag
# @name REQUEST_NAME_ONE
GET http://localhost:8080/api/v1/health HTTP/2
content-type: application/json

{
  "key": "value"
}

If run on all files it also warns when it finds both .env and http-client.env.json files in the same directory, because that might cause unexpected behavior.

Formatting options

You can tweak the formatter by using some flags.

separate-logical-blocks

Logical blocks can be separated by a newline using --separate-logical-blocks. For example:

@variables1=value1

# This is a comment
# This is another comment

# @someother metatag
# @name REQUEST_NAME_ONE

GET http://localhost:8080/api/v1/health HTTP/1.1
Content-Type: application/json

{
  "key": "value"
}

in-request-vars

When using request variables (like optaining a token from a previous request) you may assign thie to a document after the request and don't force to put it at the top of the file.

This can be done by using --in-request-vars

###

# @name login

POST {{loginURL}} HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded

client_secret={{clientSecret}}&client_id={{clientId}}&grant_type=client_credentials&scope={{scope}}

###

@token = {{login.response.body.$.access_token}}
@tokentype = {{login.response.body.$.token_type}}

###

Use it with conform.nvim

return {
  "stevearc/conform.nvim",
  config = function()
    require("conform").setup({
      formatters = {
        kulala = {
          command = "kulala-fmt",
          args = { "$FILENAME" },
          stdin = false,
        },
      },
      formatters_by_ft = {
        http = { "kulala" },
      },
      format_on_save = true,
    })
  end,
}