kulala-cli

Install • Usage

A fully-featured 🤏 HTTP/GraphQL/gRPC/Websocket-client 🐼 interface 🖥️ for your command-line ❤️, that supports the Jetbrains .http spec (with full scripting support).

Install

You can install kulala-cli globally using npm, bun, yarn or pnpm:

npm install -g @mistweaverco/kulala-cli
bun add -g @mistweaverco/kulala-cli
yarn global add @mistweaverco/kulala-cli
pnpm add -g @mistweaverco/kulala-cli

You can also run it directly without installation using

npx, bunx, yarn dlx or pnpx:

npx @mistweaverco/kulala-cli run --tests file.http
bunx @mistweaverco/kulala-cli run --tests file.http
yarn dlx @mistweaverco/kulala-cli run --tests file.http
pnpx @mistweaverco/kulala-cli run --tests file.http

On install, kulala-cli downloads a matching kulala-core binary automatically.

If install scripts are disabled (for example npm install --ignore-scripts), the binary is downloaded on first use instead.

To use your own kulala-core binary, set KULALA_CORE_PATH:

export KULALA_CORE_PATH=/path/to/kulala-core

Usage

Run a .http file and print human-readable output:

kulala run file.http

Run a .http file and print the raw kulala-core JSON output:

kulala run --json file.http

Run a .http file and only print test output (full output on failures):

kulala run --tests file.http

Run curl with human-readable output (supports normal curl flags):

kulala curl -I https://echo.kulala.app/get
kulala curl -H "Accept: application/json" https://echo.kulala.app/get

Run all files in a directory and only print test output:

kulala run --tests ./requests

Run all files in a directory (in random order) and only print test output:

kulala run --tests --shuffle ./requests

Only print output when a request fails:

kulala run --quiet ./requests

Stop after the first failing request or file:

kulala run --halt ./requests

Select an environment for variable resolution:

kulala run --tests --env=production file.http

Run a single request by block name (### name):

kulala run file.http --name MyRequest

Run the request at a cursor location (1-based line and column, same as kulala.nvim):

kulala run file.http --line 17
kulala run file.http --line 19 --column 1

When using --name, --line, or --column, <path> must be a single .http or .rest file.

Exit behaviour

kulala-cli exits with code 1 when any request fails. By default, all requests in a file and all files in a directory are run even when failures occur. Pass --halt to stop after the first failing request within a file and skip remaining files in a directory.

Success is determined by kulala-core's success flag, so operators such as // @kulala-expect-status-code are respected (for example, an expected 404 is treated as a pass).

Development

pnpm install
pnpm run build
pnpm run lint
node dist/cli.cjs --help

To use a locally built kulala-core binary during development:

export KULALA_CORE_PATH=/path/to/kulala-core/dist/kulala-core
node dist/cli.cjs run file.http

Docker

Run docker interactively and pseudo-TTY:

Run interactively with a mounted .http file:

docker run -it \
  -v ${PWD}/test.http:/app/test.http \
  ghcr.io/mistweaverco/kulala-cli:latest \
  run test.http \
 --name

Run docker non-interactively, but with a pseudo-TTY:

Run one request by block name (### name) with a mounted .http file and pseudo-TTY:

docker run -t \
  -v ${PWD}/test.http:/app/test.http \
  ghcr.io/mistweaverco/kulala-cli:latest \
  run test.http \
 --name "My Request Name"

Run docker non-interactively and without a pseudo-TTY; all requests in a directory:

Run all requests in a directory without a pseudo-TTY (for example, in CI):

docker run \
  -v ${PWD}/http-files-dir:/app/http-files-dir \
  ghcr.io/mistweaverco/kulala-cli:latest \
  run ./http-files-dir

Build docker and push to GitHub Container Registry:

Build and push to GitHub Container Registry:

docker buildx build --push \
  -t ghcr.io/mistweaverco/kulala-cli:latest \
  -f Dockerfile .

Build and push to Docker Hub:

docker buildx build --push \
  -t mistweaverco/kulala-cli:latest \
  -f Dockerfile .