btk compress and btk decompressCopy Anchor Link

Compress files with gzip, zstd, brotli or deflate, pack folders into archives, and reverse both. Bun provides every codec, so this works the same on machines that have no zstd or brotli installed.

CommandsCopy Anchor Link

compressCopy Anchor Link

btk compress [files...] writes a compressed copy next to each input and keeps the original. It uses gzip unless you pass a format.

btk compress bundle.js                          # bundle.js.gz
btk compress styles.css --brotli --level 9      # styles.css.br at level 9
btk compress ./site --zstd                      # site.tar.zst, one archive for the folder
btk compress ./dist --each --gzip --brotli      # a .gz and a .br next to every file in dist/
btk compress dump.sql --zstd --out-dir backups  # backups/dump.sql.zst
btk compress ./dist --each --dry-run            # sizes only, nothing written
cat dump.sql | btk compress --zstd > dump.sql.zst

formatsCopy Anchor Link

btk compress formats prints the table in Formats and levels.

btk compress formats

decompressCopy Anchor Link

btk decompress [files...] restores each file next to the compressed one. Archives such as .tar.zst extract into a folder.

btk decompress bundle.js.gz                     # bundle.js
btk decompress site.tar.zst                     # site/
btk decompress site.tar.zst -o ./restore        # into restore/
btk decompress app.log.gz --stdout | grep ERROR # print instead of writing a file
btk decompress data.bin --format brotli         # brotli has no signature, so name the format
cat dump.sql.zst | btk decompress > dump.sql

When to use itCopy Anchor Link

Precompress a website's static files. Web servers like nginx and Caddy, and CDNs, can serve app.js.br or app.js.gz directly instead of compressing on every request. Create both for every file in your build output:

btk compress ./dist --each --gzip --brotli

btk skips files that wouldn't get smaller, such as images and fonts, instead of writing a useless .gz.

Send or back up a folder as one file. Pack a folder into a single archive, then unpack it on the other side:

btk compress ./project --zstd
btk decompress project.tar.zst

zstd gives the smallest files quickly. Use --gzip when the other side may only have standard tools, because every system can open .tar.gz.

Shrink a large file before uploading it. Database dumps, logs and CSV exports often shrink by 80% or more:

btk compress dump.sql --zstd

Read a compressed log without unpacking it. Print the decompressed data and pipe it into another command:

btk decompress app.log.gz --stdout | grep ERROR

Open a file you downloaded. A .zst, .br or .tar.gz file decompresses the same way, including on machines without the matching command installed:

btk decompress data.json.zst

Compress in a pipeline. Standard input goes to standard output, so btk fits between other commands:

pg_dump mydb | btk compress --zstd > mydb.sql.zst
btk decompress < mydb.sql.zst | psql mydb

What gets written whereCopy Anchor Link

Both commands keep the input, never replace an existing file or folder without --overwrite, and write through a temp file. --out-dir puts results in another folder, -o names a single output, and --dry-run reports sizes without writing. Folders and globs with -r include subfolders. btk compress leaves out files that are already compressed, so rerunning it on a folder doesn't compress its own outputs. Batches show a progress bar on stderr. Ctrl+C lets the files in flight finish, skips the rest and exits 130.

btk refuses to print compressed data to a terminal or into --json output, and suggests a redirect or -o instead.

Formats and levelsCopy Anchor Link

The defaults favor small files over speed, because you usually compress something once and download or store it many times. Lower the level for speed on large files, such as --zstd --level 3.

gzip and deflate use libdeflate, which compresses better than zlib at the same level, and levels above 9 go further than zlib can. The shortcut flags --gzip, --zstd, --brotli and --deflate can be combined to write one file per format. Without them, btk uses --format or the configured format.

btk decompress picks the format from the file extension. It also recognizes gzip and zstd by their first bytes when the extension is missing or wrong, and then names the output name.out. brotli and raw deflate have no such signature, so those need --format.

LimitsCopy Anchor Link

• btk reads each file, and each folder's contents, into memory before compressing it. That's fine for files up to a few gigabytes.
• Archives don't keep file permissions. Extracted files are readable and writable by you, and executable bits are lost. Use tar when that matters.
• Extraction refuses entries that would land outside the target folder, such as ../evil.

OptionsCopy Anchor Link

compress:

decompress:

Config keys for btk compress can also be set with BTK_COMPRESS_<KEY>, such as BTK_COMPRESS_FORMAT=zstd. btk decompress has no config.

Exit codesCopy Anchor Link

Dashboard (btk compress --ui)Copy Anchor Link

1. Choose to compress or decompress.
2. Compress. Pick files, then set the format, level and output folder in a form prefilled from your config. The results show each file's size before and after.
3. Decompress. The browser lists only compressed files. Pick them and btk restores them next to the originals.

btk decompress --ui opens the decompress browser directly.