bun-file

Read and write the file formats supported natively by Bun, from a small CLI or a TypeScript import.

bun-file is intentionally Bun-only. The package publishes its TypeScript source directly—there is no dist directory or build step.

Requirements

• Bun 1.3.14 or newer

Installation

bun add @bunx/file

CLI

The executable is called bun-file.

For one-off commands, run it directly with bunx without installing the package:

# Read a file and print its parsed value
bunx @bunx/file config.toml

# Convert stdin to JSON
cat config.yaml | bunx @bunx/file --type yaml --format json

# Write the converted value to a file
bunx @bunx/file config.toml --format json --output config.json

# Read a file and print its parsed value
bun-file config.toml

# Convert stdin to JSON
cat config.yaml | bun-file --type yaml --format json

# Write the converted value to a file
bun-file config.toml --format json --output config.json

# Read a file from a URL
bun-file https://example.com/config.json

When reading a file, the input type is inferred from its extension. For stdin, provide --type. URLs without a file extension default to JSON; use --type to override this.

Supported formats

| Format | Read | Write | | --- | :---: | :---: | | TOML | ✓ | | | YAML | ✓ | ✓ | | JSON | ✓ | ✓ | | JSONC | ✓ | | | JSON5 | ✓ | | | JSONL | ✓ | ✓ | | JSC | ✓ | ✓ |

TOML can be read, but Bun does not provide a native TOML serializer, so TOML output is not supported.

Run bun-file --help for all options:

bun-file [options] <input> [output]

Standalone binaries

Each GitHub Release includes standalone executables for Linux, macOS, and Windows. Download the asset matching your operating system and architecture from the latest release.

Available assets:

• bun-file-linux-x64
• bun-file-linux-arm64
• bun-file-darwin-x64
• bun-file-darwin-arm64
• bun-file-windows-x64.exe

These executables include the Bun runtime and do not require Bun to be installed separately.

API

The package exports the CLI entry point for use in Bun applications:

import { cli } from "@bunx/file"

await cli(["config.toml", "--format", "json"])

The default CLI executable is also available in the package's bin directory for Bun to run directly.

Development

bun install
bun test
bun run check

Publishing

This package does not require a compilation step. bun publish publishes the TypeScript source listed in package.json's files field.

See the publishing guide for the complete npm, Trusted Publishing, and GitHub Actions setup.

With Mise installed, publish it with:

mise run publish

GitHub Actions

The repository uses Release Please to keep package versions, changelogs, and GitHub Releases synchronized:

1. Merge changes using Conventional Commits, such as fix: handle empty input or feat: add jsonl output.
2. Release Please opens or updates a release PR on main.
3. Merge the release PR to create the GitHub Release.
4. The publish workflow validates the release tag against package.json, runs the checks, and publishes to npm.

For secure, tokenless publishing, configure npm Trusted Publishing for the repository and publish.yml. The workflow requests the required GitHub OIDC permission and npm generates provenance automatically.

License

MIT