### Install kulala-core Backend

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/07-downloader.md

Downloads and installs the kulala-core binary for the current platform. Displays a spinner during download and makes the binary executable. Writes the installed version to a version file.

```typescript
export async function installBackend(): Promise<void>
```

```typescript
import { installBackend } from '@mistweaverco/kulala-fmt';

try {
  await installBackend();
  console.log('Installation complete');
} catch (error) {
  console.error('Installation failed:', error);
}
```

--------------------------------

### installBackend()

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/07-downloader.md

Downloads and installs the kulala-core binary for the current platform. It detects the platform and architecture, displays a spinner during download, makes the binary executable, and writes the installed version to a file.

```APIDOC
## installBackend()

### Description
Downloads and installs the kulala-core binary for the current platform. Detects the current platform (darwin, linux, windows) and architecture (x86_64, aarch64, arm64). Displays a spinner during download (if stderr is a TTY). Makes the downloaded binary executable. Writes the installed version to a version.txt file for future version checks. Throws on download failure.

### Method Signature
```typescript
export async function installBackend(): Promise<void>
```

### Returns
- Promise<void> — Resolves when install completes.

### Throws
- Error on network failure, invalid download, file system errors, or missing output directory.

### Example
```typescript
import { installBackend } from '@mistweaverco/kulala-fmt';

try {
  await installBackend();
  console.log('Installation complete');
} catch (error) {
  console.error('Installation failed:', error);
}
```
```

--------------------------------

### Install Dependencies and Build Project

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/README.md

These commands are used for development. `pnpm install` installs all necessary dependencies, and `pnpm run build` compiles the project.

```sh
pnpm install
pnpm run build
```

--------------------------------

### tryInstallBackend()

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/07-downloader.md

Attempts to install the kulala-core binary in a best-effort manner for lifecycle scripts. It logs warnings on failure instead of throwing errors, allowing npm install to complete successfully. It checks for KULALA_CORE_PATH, skips download if the binary exists and matches the version, and removes stale binaries before downloading new ones.

```APIDOC
## tryInstallBackend()

### Description
Best-effort installation for lifecycle scripts (postinstall/prepare).

### Method Signature
```typescript
export async function tryInstallBackend(): Promise<void>
```

### Returns
Promise<void> — Always resolves (never rejects).

### Details
Attempts to install the binary but logs warnings instead of throwing on failure. Checks for KULALA_CORE_PATH environment variable first (if set, returns immediately). Skips download if binary exists and version matches. Removes stale binaries before downloading new ones. On download failure, logs a warning message and returns (does not throw). This allows npm install to complete successfully even if the binary download fails; the binary will be downloaded on first use.

### Code Example
```typescript
import { tryInstallBackend } from '@mistweaverco/kulala-fmt';

// Called during postinstall
await tryInstallBackend();
// Never throws
```
```

--------------------------------

### Install Kulala-core Binary

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/07-downloader.md

Best-effort installation for lifecycle scripts. Attempts to install the binary but logs warnings instead of throwing on failure. Skips download if binary exists and version matches. Removes stale binaries before downloading new ones.

```typescript
export async function tryInstallBackend(): Promise<void>
```

```typescript
import { tryInstallBackend } from '@mistweaverco/kulala-fmt';

// Called during postinstall
await tryInstallBackend();
// Never throws
```

--------------------------------

### Example Defaults Configuration

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/03-configuration.md

Illustrates how to set custom default HTTP methods and versions in the `kulala-fmt.yaml` file.

```yaml
defaults:
  http_method: POST
  http_version: HTTP/2
```

--------------------------------

### Bruno Request File (.bru) Example

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/11-bruno-details.md

A comprehensive example of a .bru file, demonstrating various sections like meta, http, headers, params, body, scripts, and variables.

```bru
meta {
  name: Get Users
  type: http
  seq: 1
}

http {
  method: GET
  url: https://api.example.com/users?limit=10
}

headers {
  Accept: application/json
  Authorization: Bearer {{token}}
}

params:query {
  limit: 10
  offset: 0
}

body:json {
{
  "filter": "active"
}
}

script:pre-request {
  const now = new Date();
  bru.setVar("timestamp", now.toISOString());
}

script:post-response {
  if (res.getStatus() === 200) {
    bru.setVar("users", res.getBody());
  }
}

vars:pre-request {
  timestamp: timestamp-value
}

vars:post-response {
  user_id: 123
}
```

--------------------------------

### Install Kulala-fmt Globally

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/README.md

Install kulala-fmt globally using npm, bun, yarn, or pnpm. This makes the command available system-wide.

```sh
npm install -g @mistweaverco/kulala-fmt
bun add -g @mistweaverco/kulala-fmt
yarn global add @mistweaverco/kulala-fmt
pnpm add -g @mistweaverco/kulala-fmt
```

--------------------------------

### Example Kulala-FMT Configuration Output

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/08-cli.md

This is an example of the default configuration file generated by `kulala-fmt init`. It includes a schema directive for IDE support and pre-populated default values for formatting and HTTP requests.

```yaml
# yaml-language-server: $schema=https://kulala.app/kulala-fmt.schema.json
---
defaults:
  http_method: GET
  http_version: HTTP/1.1
body:
  format:
    indent: 2
    line_width: 80
    expand_tabs: true

```

--------------------------------

### Example Kulala-fmt Configuration

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/README.md

This is an example of a `kulala-fmt.yaml` configuration file. It specifies default HTTP methods and versions, and configures body formatting options like indentation and line width.

```yaml
# yaml-language-server: $schema=https://kulala.app/kulala-fmt.schema.json
defaults:
  http_method: GET
  http_version: HTTP/1.1
body:
  format:
    indent: 2
    line_width: 80
    expand_tabs: true

```

--------------------------------

### Formatted HTTP Request Example (HTTP/1.1)

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/README.md

This example shows a perfectly formatted request using HTTP/1.1. It includes metadata, comments, and a JSON body with a variable substitution.

```http
@SOME_DOCUMENT_VARIABLE1 = some value

### REQUEST_NAME_ONE

# This is a comment
# @kulala-curl--insecure
# This is another comment

POST https://echo.kulala.app/post HTTP/1.1
Content-Type: application/json

{
  "key": "{{ SOME_DOCUMENT_VARIABLE1 }}"
}

```

--------------------------------

### Usage Example of PostmanDocumentParser

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/06-conversion-parsers.md

Demonstrates how to instantiate PostmanDocumentParser and use its parse method with a sample Postman collection object. This example shows the basic setup and the expected output structure.

```typescript
import { PostmanDocumentParser } from '@mistweaverco/kulala-fmt';

const collection = {
  info: { name: 'My API' },
  item: [
    {
      name: 'Get User',
      request: {
        method: 'GET',
        url: { raw: 'https://api.example.com/users/{{userId}}' },
      },
    },
  ],
};

const parser = new PostmanDocumentParser();
const { document, collectionName, environments } = parser.parse(collection);
```

--------------------------------

### Swagger 2.0 Example

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/09-openapi-details.md

This is an example of a Swagger 2.0 specification, including host, basePath, schemes, and paths.

```json
{
  "swagger": "2.0",
  "host": "api.example.com",
  "basePath": "/v1",
  "schemes": ["https"],
  "paths": {
    "/users": {
      "get": {
        "parameters": [{
          "name": "limit",
          "in": "query",
          "type": "integer"
        }]
      }
    }
  }
}
```

--------------------------------

### Ensure kulala-core Binary is Installed

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/07-downloader.md

Checks for an existing kulala-core binary, respecting KULALA_CORE_PATH. Downloads and installs if necessary, making it executable. Caches the path for future use.

```typescript
export async function ensureInstalled(): Promise<string>
```

```typescript
import { ensureInstalled } from '@mistweaverco/kulala-fmt';

const binPath = await ensureInstalled();
console.log(binPath);
// Output: /path/to/node_modules/@mistweaverco/kulala-fmt/dist/bin/kulala-core
```

--------------------------------

### Example Body Format Configuration

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/03-configuration.md

Shows how to customize body formatting options such as indent width, line width, and tab expansion in `kulala-fmt.yaml`.

```yaml
body:
  format:
    indent: 4
    line_width: 100
    expand_tabs: false
```

--------------------------------

### Downloader Module Functions

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/README.md

Lists functions for managing the installation and retrieval of backend binaries.

```APIDOC
### Downloader Module (`src/lib/downloader/index.ts`)

**Exported Functions:**
- `ensureInstalled()` — Get/download binary path
- `installBackend()` — Install binary
- `tryInstallBackend()` — Best-effort install
- `getBinPath()` — Get binary location
```

--------------------------------

### Formatted HTTP Request Example (HTTP/2)

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/README.md

This example demonstrates a formatted request using HTTP/2. Note that header casing might differ from HTTP/1.1, and the HTTP version is explicitly set to HTTP/2.

```http
@SOME_DOCUMENT_VARIABLE1 = some value

### REQUEST_NAME_ONE

# This is a comment
# @kulala-curl--insecure
# This is another comment

POST https://echo.kulala.app/post HTTP/2
content-type: application/json

{
  "key": "{{ SOME_DOCUMENT_VARIABLE1 }}"
}

```

--------------------------------

### CLI Tool Usage

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/README.md

Provides examples of how to use the Kulala-fmt CLI tool for various operations like formatting, validation, and format conversion.

```APIDOC
## CLI Tool Usage

### Entry point: `src/cli.ts` → `dist/cli.cjs`

```bash
# Format .http files
kulala-fmt fix ./api

# Validate files
kulala-fmt check ./api

# Convert OpenAPI to HTTP
kulala-fmt convert --from openapi openapi.yaml

# Convert HTTP to Postman
kulala-fmt convert --from http --to postman requests.http
```
```

--------------------------------

### ensureInstalled()

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/07-downloader.md

Ensures the kulala-core binary is installed and returns its path. It checks environment variables, bundled binaries, and downloads from GitHub if needed. Caches the path for subsequent calls.

```APIDOC
## ensureInstalled()

### Description
Ensures the kulala-core binary is installed and returns its path. Checks for the KULALA_CORE_PATH environment variable first (allowing manual overrides). If set and the path exists, returns it immediately. Otherwise, checks if the bundled binary exists and matches the required version. If mismatched, removes the stale binary. If no binary is installed, downloads the appropriate platform-specific release from GitHub (v## tag based on KULALA_CORE_VERSION). Makes the binary executable on non-Windows platforms. Caches the path in memory for subsequent calls.

### Method Signature
```typescript
export async function ensureInstalled(): Promise<string>
```

### Returns
- Promise<string> — Absolute path to the kulala-core executable.

### Environment Variables
- `KULALA_CORE_PATH` — Override binary location (absolute path to executable).

### Throws
- Error if KULALA_CORE_PATH is set but path does not exist, or if download fails.

### Example
```typescript
import { ensureInstalled } from '@mistweaverco/kulala-fmt';

const binPath = await ensureInstalled();
console.log(binPath);
// Output: /path/to/node_modules/@mistweaverco/kulala-fmt/dist/bin/kulala-core
```
```

--------------------------------

### Display Kulala-FMT Version

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/08-cli.md

Use this command to display the installed version of the kulala-fmt tool.

```bash
kulala-fmt --version
```

--------------------------------

### HTTP Request Formatting Example

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/README.md

Demonstrates the transformation of an unformatted HTTP request to a standardized format, including the addition of the HTTP version for HTTP/1.1.

```http
# Before formatting
GET   https://api.example.com/users
Content-Type:    application/json

{  "filter"  :  "active"  }

# After formatting (HTTP/1.1)
GET https://api.example.com/users HTTP/1.1
Content-Type: application/json

{
  "filter": "active"
}
```

--------------------------------

### HTTP File Generation Example

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/09-openapi-details.md

This JSON snippet demonstrates a specification with multiple server URLs, which will result in separate HTTP files being generated for each server.

```json
{
  "servers": [
    {"url": "https://api.example.com"},
    {"url": "https://staging-api.example.com"}
  ]
}
```

--------------------------------

### Utility Modules

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/MANIFEST.txt

Reference for utility functions related to file operations and backend installations.

```APIDOC
## Utility Modules

### Description
Provides utility functions for file manipulation and managing backend installations.

### File Operations
- **fileWalker()**: Recursively walks through files in a directory.
- **DocumentBuilder.build()**: Builds a document from parsed data.
- **documentToHttp()**: Converts a document to HTTP format.
- **Diff()**: Computes differences between two documents.
- **DiffOptions**: Options for the Diff function.

### Downloader
- **ensureInstalled()**: Ensures a backend is installed.
- **installBackend()**: Installs a backend.
- **tryInstallBackend()**: Attempts to install a backend.
```

--------------------------------

### OpenAPI 3.x Converted Example

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/09-openapi-details.md

This is the OpenAPI 3.x equivalent of the provided Swagger 2.0 specification, showing the converted servers, paths, and parameters.

```json
{
  "openapi": "3.0.0",
  "servers": [{"url": "https://api.example.com/v1"}],
  "paths": {
    "/users": {
      "get": {
        "parameters": [{
          "name": "limit",
          "in": "query",
          "schema": {"type": "integer"}
        }]
      }
    }
  }
}
```

--------------------------------

### Environment File Structure

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/11-bruno-details.md

Example of a Bruno environment.json file. Each key represents a variable name, and its value object contains the variable's 'value' and a 'secret' flag.

```json
{
  "client_id": {
    "value": "abc123",
    "secret": false
  },
  "client_secret": {
    "value": "secret456",
    "secret": true
  },
  "api_url": {
    "value": "https://api.example.com",
    "secret": false
  }
}
```

--------------------------------

### Run Kulala-fmt Directly

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/README.md

Execute kulala-fmt directly without global installation using npx, bunx, yarn dlx, or pnpx. This is useful for one-off commands or testing.

```sh
npx @mistweaverco/kulala-fmt fix file.http
bunx @mistweaverco/kulala-fmt fix file.http
yarn dlx @mistweaverco/kulala-fmt fix file.http
pnpx @mistweaverco/kulala-fmt fix file.http
```

--------------------------------

### Get Kulala-core Binary Path

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/07-downloader.md

Returns the platform-specific binary path within the package's bin directory. On Windows, appends .exe extension. On Unix-like systems, returns bare executable name. Does not check if the file exists.

```typescript
export function getBinPath(): string
```

```typescript
import { getBinPath } from '@mistweaverco/kulala-fmt';

const path = getBinPath();
// Output (Unix): /path/to/.../bin/kulala-core
// Output (Windows): /path/to/.../bin/kulala-core.exe
```

--------------------------------

### Pre-Request Script Example in HTTP File

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/11-bruno-details.md

JavaScript code for pre-request scripts can be embedded as comments within HTTP files. These scripts are executed before the request is sent, allowing for dynamic variable setting.

```http
# Pre-Request:
# const now = new Date();
# bru.setVar("timestamp", now.toISOString());

POST https://api.example.com/requests
```

--------------------------------

### Initialize Configuration File

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/03-configuration.md

Creates a new `kulala-fmt.yaml` file with default settings. If a configuration file already exists, it will prompt for confirmation before overwriting.

```APIDOC
## init()

### Description
Initializes a new `kulala-fmt.yaml` file in the current working directory.

### Method Signature
```typescript
export function init(): void
```

### Usage Example
```typescript
import { configparser } from '@mistweaverco/kulala-fmt';

configparser.init();
// Output: 🦄 Config file written: /current/working/directory/kulala-fmt.yaml
```
```

--------------------------------

### Initialize Kulala-fmt Configuration

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/README.md

Run this command to create a default `kulala-fmt.yaml` file in your current directory. All fields in the configuration are optional.

```sh
kulala-fmt init
```

--------------------------------

### Initialize Configuration File

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/03-configuration.md

Use the `init` function from the `configparser` module to create a new `kulala-fmt.yaml` file with default settings. If a file exists, it will prompt for overwrite confirmation.

```typescript
import { configparser } from '@mistweaverco/kulala-fmt';

configparser.init();
// Output: 🦄 Config file written: /current/working/directory/kulala-fmt.yaml
```

--------------------------------

### Run CLI Tool for Help

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/00-index.md

Execute the built CLI tool to view its help information. Assumes the build process outputs to the `dist/` directory.

```bash
node dist/cli.cjs --help
```

--------------------------------

### Lint Project and View CLI Help

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/README.md

Useful commands for development. `pnpm run lint` checks for code style issues, and `node dist/cli.cjs --help` displays the command-line interface options.

```sh
pnpm run lint
node dist/cli.cjs --help
```

--------------------------------

### Configure conform.nvim with Kulala-fmt

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/README.md

Set up Kulala-fmt as a formatter for HTTP files within conform.nvim. Ensure format_on_save is enabled for automatic formatting.

```lua
return {
  "stevearc/conform.nvim",
  config = function()
    require("conform").setup({
      formatters_by_ft = {
        http = { "kulala-fmt" },
      },
      format_on_save = true,
    })
  end,
}
```

--------------------------------

### Format HTTP files with kulala-fmt

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/01-parser.md

Demonstrates how to use the format function to format files in the current directory, a specific directory, or from stdin.

```typescript
import { format } from '@mistweaverco/kulala-fmt';

// Format all files in current directory
await format(null, { body: true, stdin: false });

// Format specific directory without body formatting
await format('./api', { body: false, stdin: false });

// Format stdin and output to stdout
await format(null, { body: true, stdin: true });
```

--------------------------------

### PostmanItem Interface

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/10-postman-details.md

Represents a single request within a Postman collection. It includes the request name, the request details, and any associated response examples.

```typescript
interface PostmanItem {
  name: string;
  request: PostmanRequest;
  response: unknown[];
}
```

--------------------------------

### OpenAPI Request Body Interface

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/09-openapi-details.md

Defines the structure for an OpenAPI request body, including its description, requirement, and content types with schemas and examples.

```typescript
interface OpenAPIRequestBody {
  description?: string;
  required?: boolean;
  content: Record<string, {
    schema?: OpenAPISchema;
    example?: OpenAPISchemaExample;
  }>;
}
```

--------------------------------

### Run Linting

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/00-index.md

Execute the linting process for the project to check code quality and style.

```bash
pnpm run lint
```

--------------------------------

### OpenAPIPathItem Interface

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/09-openapi-details.md

Defines a single API path and its associated HTTP operations (GET, POST, PUT, DELETE, PATCH) and path-level parameters.

```typescript
interface OpenAPIPathItem {
  get?: OpenAPIOperation;
  post?: OpenAPIOperation;
  put?: OpenAPIOperation;
  delete?: OpenAPIOperation;
  patch?: OpenAPIOperation;
  parameters?: OpenAPIParameter[];
}
```

--------------------------------

### Basic CLI Usage

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/08-cli.md

Shows the general syntax for the 'check' command.

```bash
kulala-fmt check [files] [options]
```

--------------------------------

### Configuration Module Functions

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/README.md

Describes the functions for initializing and parsing configuration files within the Configuration module.

```APIDOC
### Configuration Module (`src/lib/configparser/index.ts`)

**Exported Functions:**
- `configparser.init()` — Create new config file
- `configparser.parse()` — Read and parse config

**Exported Types:**
- `Config` — Configuration object structure
```

--------------------------------

### Configuration API

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/MANIFEST.txt

Documentation for configuration schema, defaults, and parsing functions.

```APIDOC
## Configuration API

### Description
APIs for managing configuration, including schema definition and parsing.

### Functions
- **configparser.init()**: Initializes the configuration parser.
- **configparser.parse()**: Parses the configuration.
```

--------------------------------

### Format All API Files with Kulala-fmt

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/README.md

Use the 'fix' command to automatically format all API files in a directory.

```bash
kulala-fmt fix ./api
```

--------------------------------

### Parse Configuration File

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/03-configuration.md

Reads and parses the `kulala-fmt.yaml` file from the current working directory. If the file is not found, it returns the default configuration.

```APIDOC
## parse()

### Description
Reads and parses the `kulala-fmt.yaml` configuration file. If the file does not exist, returns the default configuration.

### Method Signature
```typescript
export function parse(): Config
```

### Returns
`Config` - Parsed configuration object with all defaults applied.

### Usage Example
```typescript
import { configparser } from '@mistweaverco/kulala-fmt';

const config = configparser.parse();

console.log(config.defaults.http_method);
console.log(config.body.format.indent);
```
```

--------------------------------

### CLI Commands

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/MANIFEST.txt

Documentation for the command-line interface commands provided by kulala-fmt.

```APIDOC
## CLI Commands

### Description
Reference for the command-line interface tools.

### Commands
- **fix/format**: Alias for the format command.
- **check**: Checks file validity.
- **convert**: Converts file formats.
- **init**: Initializes a new project or configuration.
```

--------------------------------

### Format All .http and .rest Files

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/README.md

Formats all .http and .rest files recursively from the current directory. Use this for a project-wide formatting pass.

```sh
kulala-fmt fix
```

--------------------------------

### Environment File Formats

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/08-cli.md

Supports .env or http-client.env.json for variable injection during http to Postman conversion.

```plaintext
BASE_URL=https://api.example.com
API_KEY=secret123
```

```json
{
  "dev": {
    "BASE_URL": "https://dev.api.example.com",
    "API_KEY": "dev-key"
  }
}
```

--------------------------------

### Library Usage: Validation, Formatting, and Conversion

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/README.md

Demonstrates how to use the main functions of the Kulala-fmt library to check, format, and convert files programmatically.

```APIDOC
## Library Usage

### Main module: `src/lib/parser/index.ts`

```typescript
import { check, format, convert } from '@mistweaverco/kulala-fmt';

// Validate files
await check(dirPath, { quiet: false, body: true, stdin: false });

// Format files
await format(dirPath, { body: true, stdin: false });

// Convert formats
await convert({ from: 'openapi', to: 'http' }, ['spec.yaml']);
```
```

--------------------------------

### buildPostmanCollection()

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/06-conversion-parsers.md

Builds a Postman Collection v2.1 from parsed HTTP files and KulalaParsedDocuments.

```APIDOC
## buildPostmanCollection()

### Description
Converts parsed HTTP content into a Postman Collection v2.1 format, handling multiple documents and extra variables.

### Method
`buildPostmanCollection(documents: Array<{ doc: KulalaParsedDocument; relativePath?: string }>, collectionName: string, extraVariables: Record<string, string> = {}): PostmanCollection`

### Parameters
#### Path Parameters
- **documents** (Array<{ doc, relativePath? }>) - Required - Array of parsed documents with optional relative paths.
- **collectionName** (string) - Required - Name for the generated collection.
- **extraVariables** (Record<string, string>) - Optional - Additional variables to inject (e.g., from .env files).

### Returns
- **PostmanCollection** (PostmanCollection) - Postman Collection v2.1 object.

### Description
Converts multiple HTTP documents into a single Postman collection. Merges variables from all documents and injected variables into collection-level variables. Extracts folder structure from "Folder: " comments in block preambles and comments. Creates nested folder structure in Postman format. Each request block becomes a Postman item. Detects body content type from Content-Type header or body content analysis. Handles query parameters by parsing URLs. Preserves request descriptions from comments.

### Request Example
```typescript
import { buildPostmanCollection } from '@mistweaverco/kulala-fmt';

const parsed = await parseHttp('GET https://api.example.com/users');

const collection = buildPostmanCollection(
  [{ doc: parsed, relativePath: 'users.http' }],
  'My API',
  { BASE_URL: 'https://api.example.com' }
);

// Output is a PostmanCollection object ready to JSON.stringify
```
```

--------------------------------

### Format HTTP Content with formatHttp()

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/02-kulala-core.md

Formats HTTP file content using the kulala-core binary. Options can control body formatting and provide filepath context for errors.

```typescript
export async function formatHttp(
  content: string,
  options: FormatOptions = {}
): Promise<string>
```

```typescript
import { formatHttp } from '@mistweaverco/kulala-fmt';

const httpContent = `
GET https://api.example.com/users
Content-Type: application/json

{"filter":"active"}
`;

const formatted = await formatHttp(httpContent, {
  formatBody: true,
  filepath: 'requests.http'
});

console.log(formatted);
```

--------------------------------

### Convert OpenAPI to HTTP with Kulala-fmt

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/README.md

Use the 'convert' command to transform OpenAPI specification files into the HTTP format.

```bash
kulala-fmt convert --from openapi openapi.yaml
```

--------------------------------

### YAML Schema Reference for IDE

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/03-configuration.md

Includes a YAML language server directive in `kulala-fmt.yaml` to enable IDE autocompletion and validation against the official JSON Schema.

```yaml
# yaml-language-server: $schema=https://kulala.app/kulala-fmt.schema.json
---
# Your configuration here
```

--------------------------------

### Default Configuration Schema

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/03-configuration.md

Defines the structure for the `kulala-fmt.yaml` configuration file, including options for default HTTP methods and versions, as well as body formatting.

```yaml
defaults:
  http_method: GET
  http_version: HTTP/1.1

body:
  format:
    indent: 2
    line_width: 80
    expand_tabs: true
```

--------------------------------

### Environment Handling Functions

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/README.md

Details functions for building and writing environment files for Bruno and Postman, including parsing Postman environments.

```APIDOC
### Environment Handling

**BrunoEnvFiles** (`src/lib/parser/BrunoEnvFiles.ts`)
- `buildHttpClientEnvJson(environments)` — Build env file
- `buildHttpClientPrivateEnvJson(environments)` — Build secrets file
- `writeHttpClientEnvFiles(environments, outputDir)` — Write files
- `BrunoEnvironment`, `KulalaOAuth2PublicConfig` types

**PostmanEnvironmentParser** (`src/lib/parser/PostmanEnvironmentParser.ts`)
- `parsePostmanEnvironment(json)` — Parse env file
- `isPostmanEnvironment(json)` — Type guard
- `isPostmanCollection(json)` — Type guard
- `PostmanEnvironment`, `PostmanEnvironmentValue` types
```

--------------------------------

### Use Kulala-FMT as a CLI Tool (Bash)

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/README.md

Execute Kulala-FMT commands from the terminal to format, validate, or convert API definition files. Use subcommands like `fix`, `check`, and `convert` with appropriate arguments for file paths and conversion types.

```bash
# Format .http files
kulala-fmt fix ./api

# Validate files
kulala-fmt check ./api

# Convert OpenAPI to HTTP
kulala-fmt convert --from openapi openapi.yaml

# Convert HTTP to Postman
kulala-fmt convert --from http --to postman requests.http
```

--------------------------------

### Format-Specific Documentation

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/MANIFEST.txt

In-depth documentation for supported formats including OpenAPI, Postman, and Bruno.

```APIDOC
## Format-Specific Documentation

### OpenAPI
- Support for OpenAPI 3.x and Swagger 2.0.
- Details on `OpenAPISpec` structure.
- Parameter handling specifics.
- Swagger 2.0 conversion details.

### Postman
- Documentation for Postman Collection v2.1 format.
- Details on `PostmanItem` and `PostmanItemGroup`.
- Handling of authentication types.
- HTTP to Postman conversion specifics.

### Bruno
- Documentation for Bruno collection directory format.
- Parsing of `.bru` file DSL.
- Environment variable handling.
- Folder structure preservation.
```

--------------------------------

### Skip body formatting with 'fix' command

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/08-cli.md

To format .http and .rest files while leaving request bodies unchanged, use the --no-body option with the 'fix' command.

```bash
kulala-fmt fix --no-body requests.http
```

--------------------------------

### Convert Bruno to HTTP

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/08-cli.md

Converts a Bruno collection directory into .http files. Use 'bruno' for the --from format.

```bash
kulala-fmt convert --from bruno ./bruno-collection
```

--------------------------------

### DocumentBuilder.build()

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/05-file-operations.md

Constructs an HTTP file from a Document object and applies formatting. It converts a Document to raw HTTP text and then formats it using kulalaCore.formatHttp().

```APIDOC
## build()

### Description
Constructs an HTTP file from a Document object and applies formatting.

### Method Signature
```typescript
const build = async (
  document: Document,
  formatBody: boolean = true,
  filepath?: string
): Promise<string>
```

### Parameters
#### Path Parameters
* **document** (Document) - Required - Document structure to build from.
* **formatBody** (boolean) - Optional - Default: `true`. When true, formats request bodies using prettier rules.
* **filepath** (string) - Optional - Optional file path for error context.

### Returns
Promise<string> — Formatted HTTP file content.

### Throws
Error if kulalaCore.formatHttp() fails.

### Code Example
```typescript
import { DocumentBuilder } from '@mistweaverco/kulala-fmt';

const document = {
  variables: [{ key: 'BASE_URL', value: 'https://api.example.com' }],
  blocks: [
    {
      requestSeparator: { text: 'Get Users' },
      metadata: [],
      comments: ['# Fetch all users'],
      request: {
        method: 'GET',
        url: 'https://api.example.com/users',
        httpVersion: 'HTTP/1.1',
        headers: [{ key: 'Accept', value: 'application/json' }],
        body: null,
      },
      preRequestScripts: [],
      postRequestScripts: [],
      responseRedirect: null,
    },
  ],
};

const httpContent = await DocumentBuilder.build(document);
console.log(httpContent);
```
```

--------------------------------

### Format .http and .rest files in place

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/08-cli.md

Use the 'fix' command to format .http and .rest files. It can target specific files, directories, or all files recursively in the current directory if no files are specified. Glob patterns are supported for file selection.

```bash
kulala-fmt fix
```

```bash
kulala-fmt fix ./api/requests
```

```bash
kulala-fmt fix file1.http file2.rest
```

```bash
kulala-fmt fix src/**/*.http
```

--------------------------------

### Parse Configuration File

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/03-configuration.md

Reads and parses the `kulala-fmt.yaml` file using the `parse` function from the `configparser` module. If the file is not found, it returns the default configuration.

```typescript
import { configparser } from '@mistweaverco/kulala-fmt';

const config = configparser.parse();

console.log(config.defaults.http_method);           // "GET" or user value
console.log(config.body.format.indent);             // 2 or user value
```

--------------------------------

### getBinPath()

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/07-downloader.md

Returns the absolute path where the kulala-core binary is or should be stored within the package's bin directory.

```APIDOC
## getBinPath()

### Description
Returns the path where the kulala-core binary is/should be stored.

### Method Signature
```typescript
export function getBinPath(): string
```

### Returns
string — Absolute path to the expected binary location.

### Details
Returns the platform-specific binary path within the package's bin directory. On Windows, appends .exe extension. On Unix-like systems, returns bare executable name. Does not check if the file exists.

### Code Example
```typescript
import { getBinPath } from '@mistweaverco/kulala-fmt';

const path = getBinPath();
// Output (Unix): /path/to/.../bin/kulala-core
// Output (Windows): /path/to/.../bin/kulala-core.exe
```
```

--------------------------------

### HTTP to Postman Folder Structure

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/10-postman-details.md

Demonstrates how folder structures in Postman Collections are derived from 'Folder: ' preamble comments in HTTP files.

```http
### Get Users
# Folder: /API/Users

GET https://api.example.com/users

```

```json
{
  "item": [
    {
      "name": "API",
      "item": [
        {
          "name": "Users",
          "item": [
            {
              "name": "Get Users",
              "request": { ... }
            }
          ]
        }
      ]
    }
  ]
}

```

--------------------------------

### Default kulala-fmt.yaml Configuration

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/README.md

Shows the default configuration settings for kulala-fmt, including default HTTP method and version, and body formatting options like indent, line width, and tab expansion.

```yaml
defaults:
  http_method: GET          # Default method (GET, POST, etc.)
  http_version: HTTP/1.1    # Default version (HTTP/1.0, HTTP/1.1, HTTP/2) or false

body:
  format:
    indent: 2               # Indent width in spaces
    line_width: 80          # Max line width before wrapping
    expand_tabs: true       # Use spaces vs tabs
```

--------------------------------

### Convert .http to Postman with Environment

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/README.md

Converts .http files to a Postman collection, injecting variables from a specified environment file. Supports both .env and http-client.env.json formats.

```sh
kulala-fmt convert --from http --to postman requests.http --env .env
```

```sh
kulala-fmt convert --from http --to postman requests.http --env http-client.env.json
```

--------------------------------

### Display Help Message for a Command

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/08-cli.md

Use this command to display the help message for a specific kulala-fmt command, such as `fix`.

```bash
kulala-fmt fix --help
```

--------------------------------

### formatHttp()

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/02-kulala-core.md

Formats HTTP file content according to specified configuration rules, including body formatting and header normalization. It invokes the kulala-core binary to perform the parsing and formatting.

```APIDOC
## formatHttp()

### Description
Formats HTTP file content according to configuration rules.

### Method
`async function formatHttp(content: string, options: FormatOptions = {}): Promise<string>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Function Parameters
- **content** (string) - Required - Raw HTTP file content as text.
- **options** (FormatOptions) - Optional - Formatting configuration object.
  - **options.formatBody** (boolean) - Optional - When true, formats JSON and GraphQL request bodies using prettier rules. When false, leaves body content unchanged. Defaults to true.
  - **options.filepath** (string) - Optional - Optional file path used for error reporting context.

### Returns
Promise<string> — Formatted HTTP content.

### Description
Invokes the kulala-core binary to parse and format HTTP content. Applies configuration from kulala-fmt.yaml if present (defaults, HTTP version, body formatting). Normalizes headers (lowercase for HTTP/2-3, capitalized for HTTP/1.x), removes extraneous whitespace, and organizes request metadata. Body formatting uses prettier with configured indent width and line width.

### Request Example
```typescript
import { formatHttp } from '@mistweaverco/kulala-fmt';

const httpContent = `
GET https://api.example.com/users
Content-Type: application/json

{"filter":"active"}
`;

const formatted = await formatHttp(httpContent, {
  formatBody: true,
  filepath: 'requests.http'
});

console.log(formatted);
```

### Response
#### Success Response (200)
Formatted HTTP content as a string.

#### Response Example
(See Request Example for output structure)

### Throws
Error if kulala-core binary is not found, not properly initialized, or returns non-zero exit code. Error messages from kulala-core are propagated.
```

--------------------------------

### Use Kulala-FMT as a Library (TypeScript)

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/README.md

Import and use the `check`, `format`, and `convert` functions from the Kulala-FMT library to validate, format, or convert API definition files programmatically. Ensure necessary imports are included.

```typescript
import { check, format, convert } from '@mistweaverco/kulala-fmt';

// Validate files
await check(dirPath, { quiet: false, body: true, stdin: false });

// Format files
await format(dirPath, { body: true, stdin: false });

// Convert formats
await convert({ from: 'openapi', to: 'http' }, ['spec.yaml']);
```

--------------------------------

### Set Custom Kulala-core Path

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/README.md

To use your own kulala-core binary, set the KULALA_CORE_PATH environment variable to the absolute path of your binary. This overrides the automatically downloaded binary.

```sh
export KULALA_CORE_PATH=/path/to/kulala-core
```

--------------------------------

### Check Specific Files

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/README.md

Checks the formatting of a list of specific .http and .rest files, including wildcard patterns. Allows for targeted formatting verification.

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

--------------------------------

### writeHttpClientEnvFiles

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/06-conversion-parsers.md

Writes environment variables to http-client.env.json and http-client.private.env.json files, creating a nested structure with environment names as keys. It only writes files if they contain content and includes schema references for IDE support.

```APIDOC
## writeHttpClientEnvFiles()

### Description
Writes environment variables to http-client.env.json files.

### Signature
```typescript
export function writeHttpClientEnvFiles(
  environments: BrunoEnvironment[],
  outputDir: string = process.cwd()
): { wrotePublic: boolean; wrotePrivate: boolean }
```

### Parameters
#### Parameters
- **environments** (BrunoEnvironment[]) - Required - Array of environment configurations.
- **outputDir** (string) - Optional - Default: `cwd` - Directory to write files to.

### Returns
Object with fields:
- `wrotePublic: boolean` — True if http-client.env.json was written.
- `wrotePrivate: boolean` — True if http-client.private.env.json was written.

### Description
Writes public variables to http-client.env.json and secret variables to http-client.private.env.json. Creates nested structure with environment names as keys. Only writes files if they have content. Includes schema references for IDE support.
```

--------------------------------

### Core API Reference

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/MANIFEST.txt

Provides documentation for the core functions of the kulala-fmt library, including parsing, formatting, and conversion utilities.

```APIDOC
## Core API Functions

### Description
Core functions for file validation, formatting, and conversion.

### Functions
- **check()**: Validates a file against Kulala-FMT standards.
- **format()**: Formats a file according to Kulala-FMT specifications.
- **convert()**: Converts a file from one supported format to another.
```

--------------------------------

### Kulala-FMT Module Organization

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/00-index.md

Illustrates the directory and file structure of the kulala-fmt project, highlighting the purpose of key modules and files.

```tree
src/
├── cli.ts                           # CLI command definitions
├── lib/
│   ├── configparser/                # Configuration parsing
│   ├── downloader/                  # Binary download/management
│   ├── filewalker/                  # Directory traversal
│   ├── kulala-core/                 # Formatting engine wrapper
│   └── parser/                      # Parsing & conversion
│       ├── DocumentBuilder.ts       # Build HTTP from documents
│       ├── DocumentParser.ts        # Document structure defs
│       ├── DocumentSerializer.ts    # Serialize to HTTP
│       ├── Diff.ts                  # Diff display
│       ├── OpenAPIDocumentParser.ts # OpenAPI parsing
│       ├── PostmanDocumentParser.ts # Postman parsing
│       ├── PostmanDocumentBuilder.ts # Build Postman collections
│       ├── BrunoDocumentParser.ts   # Bruno parsing
│       ├── BrunoYamlToJson.ts       # Bruno YAML format
│       ├── BrunoToJson.ts           # Bruno DSL format
│       ├── BrunoEnvFiles.ts         # Environment files
│       ├── PostmanEnvironmentParser.ts # Postman env parsing
│       ├── postmanAuth.ts           # Authentication handling
│       └── index.ts                 # Public API
├── versions/                        # Version management
└── postinstall.ts                   # Lifecycle script
```

--------------------------------

### Check Single File with Diff

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/README.md

Check a single HTTP file and display the differences if formatting changes are needed.

```bash
kulala-fmt check requests.http
# Shows formatted vs actual if changes needed
```

--------------------------------

### convert()

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/01-parser.md

Converts between HTTP and other API formats (OpenAPI, Postman, Bruno). Supports bidirectional conversion and variable injection for http→postman.

```APIDOC
## convert() 

### Description
Converts between HTTP and other API formats (OpenAPI, Postman, Bruno).

### Method Signature
```typescript
export const convert = async (
  options: { from: string; to: string; env?: string; output?: string },
  files: string[],
): Promise<void>
```

### Parameters
#### options (object) - Required
Conversion configuration.

- **options.from** ('openapi' | 'postman' | 'bruno' | 'http') - Required - Source format identifier.
- **options.to** ('http' | 'postman') - Required - Destination format identifier.
- **options.env** (string) - Optional - Path to environment file for variable injection (.env or http-client.env.json). Only used with http→postman conversion.
- **options.output** (string) - Optional - Output file path. If not provided, generates filename automatically.

#### files (string[]) - Required
Array of file paths or directory paths to convert.

### Returns
Promise that resolves when conversion completes or rejects on errors.

### Supported Conversions
- **openapi→http:** Converts OpenAPI 3.x or Swagger 2.0 specifications to HTTP files. One HTTP file is generated per server URL in the spec.
- **postman→http:** Converts Postman Collection v2.1 files to HTTP files, preserving folder structure and extracting environment variables to separate files.
- **bruno→http:** Converts Bruno collection directories to HTTP files, preserving request variables and environment configurations.
- **http→postman:** Converts .http/.rest files to Postman Collection v2.1 format. Automatically determines output filename unless specified. Optionally injects variables from environment file.

### Throws
Process exits with code 1 if source format is invalid, destination format is invalid, or files cannot be found.

### Code Example
```typescript
import { convert } from '@mistweaverco/kulala-fmt';

// OpenAPI to HTTP
await convert({ from: 'openapi', to: 'http' }, ['openapi.yaml']);

// Postman to HTTP
await convert({ from: 'postman', to: 'http' }, ['collection.json']);

// Bruno to HTTP
await convert({ from: 'bruno', to: 'http' }, ['/path/to/bruno/collection']);

// HTTP to Postman with environment variables
await convert(
  { from: 'http', to: 'postman', env: '.env', output: 'my-collection.json' },
  ['./api']
);
```
```

--------------------------------

### Conversion Parsers

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/MANIFEST.txt

Details on parsers and builders for various document formats like OpenAPI, Postman, and Bruno.

```APIDOC
## Conversion Parsers

### Description
Parsers and builders for different document formats.

### Parsers
- **OpenAPIDocumentParser**: Parses OpenAPI documents.
- **PostmanDocumentParser**: Parses Postman Collection documents.
- **BrunoDocumentParser**: Parses Bruno collection documents.

### Builders
- **PostmanDocumentBuilder**: Builds Postman Collection documents.

### File Handling
- **Environment file handling**: Utilities for managing environment files.
```

--------------------------------

### Convert OpenAPI to HTTP

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/08-cli.md

Converts OpenAPI 3.x/Swagger 2.0 specifications to .http files. Generates one file per server URL. Use 'openapi' or 'swagger' for the --from format.

```bash
kulala-fmt convert --from openapi api-spec.yaml
```

```bash
kulala-fmt convert swagger.json
```

--------------------------------

### Write HTTP Client Environment Files

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/06-conversion-parsers.md

Writes environment variables to http-client.env.json and http-client.private.env.json files. Creates nested structures based on environment names and includes schema references. Files are only written if they contain content.

```typescript
export function writeHttpClientEnvFiles(
  environments: BrunoEnvironment[],
  outputDir: string = process.cwd()
): { wrotePublic: boolean; wrotePrivate: boolean }
```

--------------------------------

### Check Formatting of All Files

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/README.md

Checks if all .http and .rest files in the current directory and subdirectories are formatted. It displays a diff for unformatted files.

```sh
kulala-fmt check
```

--------------------------------

### Convert HTTP to Postman with Environment Variables

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/08-cli.md

Converts .http/.rest files to Postman Collection JSON, injecting variables from a specified environment file (.env or http-client.env.json).

```bash
kulala-fmt convert --from http --to postman requests.http --env .env
```

--------------------------------

### Document Builder and Serializer

Source: https://github.com/mistweaverco/kulala-fmt/blob/main/_autodocs/README.md

Explains the `DocumentBuilder` for building formatted HTTP documents and `DocumentSerializer` for serializing documents to HTTP text.

```APIDOC
### Document Operations

**DocumentBuilder** (`src/lib/parser/DocumentBuilder.ts`)
- `DocumentBuilder.build(document, formatBody, filepath)` — Build formatted HTTP

**DocumentSerializer** (`src/lib/parser/DocumentSerializer.ts`)
- `documentToHttp(document)` — Serialize to HTTP text

**Diff** (`src/lib/parser/Diff.ts`)
- `Diff(build, content, options)` — Display colored diff
- `DiffOptions` type
```