A Bash command-line client for the BuzzHeavier API.
- Upload files anonymously or into your account, one or many at a time
- Download files from BuzzHeavier links, with resume
- Browse and manage your files: list, create, rename, move, annotate, delete
- Prints just the result (download link, saved path) on stdout, so it is easy to use in scripts
- Formatted tables when
jqis installed, raw JSON with--json - Interactive menu mode
$ ./buzzheavier.sh upload video.mp4
→ Uploading video.mp4 (148.2 MB)
######################################################################## 100.0%
✔ Uploaded video.mp4
https://buzzheavier.com/abc123def456- Installation
- Configuration
- Usage
- Commands
- Scripting
- Interactive mode
- Legacy command names
- Dependencies
- Development
- License
git clone https://github.com/Ognisty321/buzzheavier-cli.git
cd buzzheavier-cli
chmod +x buzzheavier.shOptionally put it on your PATH:
sudo install -m 755 buzzheavier.sh /usr/local/bin/buzzheavierOptionally install jq to get formatted tables (sudo apt-get install jq, brew install jq, winget install jqlang.jq).
Commands that work with your account use your Account ID as a Bearer token. Anonymous uploads and locations need no setup at all.
Save it once:
./buzzheavier.sh set-tokenThe command prompts for the ID without echoing it, so it stays out of your shell history. You can also pass it as an argument (set-token YOUR_ACCOUNT_ID) or pipe it in.
It is stored in ~/.config/buzzheavier-cli/config (or under $XDG_CONFIG_HOME) with permissions 600:
ACCOUNT_ID=YOUR_ACCOUNT_ID
Related commands:
./buzzheavier.sh config # show where the ID comes from (masked) and which endpoints are used
./buzzheavier.sh account # check that the ID works
./buzzheavier.sh unset-token # remove the saved ID| Variable | Purpose |
|---|---|
BUZZHEAVIER_ACCOUNT_ID |
Account ID; takes precedence over the config file |
BUZZHEAVIER_API_BASE |
default: https://buzzheavier.com/api |
BUZZHEAVIER_UPLOAD_BASE |
default: https://w.buzzheavier.com |
BUZZHEAVIER_DOWNLOAD_BASE |
default: https://buzzheavier.com |
BUZZHEAVIER_DOWNLOADER |
auto (default), cffi or curl |
BUZZHEAVIER_IMPERSONATE |
browser for curl_cffi, default: chrome |
NO_COLOR |
set to any value to disable colours |
./buzzheavier.sh [options] <command> [arguments]
./buzzheavier.sh helpQuick tour:
# Anonymous upload - prints the download link
./buzzheavier.sh upload video.mp4
# Several files into one of your directories
./buzzheavier.sh upload *.zip -d <dirId>
# Different name, a note and a specific storage location
./buzzheavier.sh upload report.pdf -n "Report 2025.pdf" --note "final version" -l <locationId>
# Download a file from its link (run it again to resume an interrupted download)
./buzzheavier.sh download https://buzzheavier.com/<id>
./buzzheavier.sh download <id> -o ~/Downloads/
# Browse and manage
./buzzheavier.sh ls
./buzzheavier.sh ls <dirId>
./buzzheavier.sh mkdir "Holiday photos"
./buzzheavier.sh rename <id> "new name.mp4"
./buzzheavier.sh mv <id> <newParentId>
./buzzheavier.sh rm <id>upload <file>... [-d <dirId>] [-n <name>] [-l <locationId>] [--note <text>]
| Option | Description |
|---|---|
-d, --dir <dirId> |
Upload into one of your directories (needs the account ID). Without it the upload is anonymous. |
-n, --name <name> |
Store the file under another name (single file only). Default: the file's own name. |
-l, --location <id> |
Storage location, see locations. |
-N, --note <text> |
Note shown under the download link (max 500 characters). |
File names are URL-encoded automatically, so spaces and non-ASCII characters work. BuzzHeavier itself refuses a few characters in names (for example #); in that case choose another name with -n. When several files are given, a failed one does not stop the others; the exit code is non-zero if any of them failed.
download <link|id>... [-o <file|dir>] [-f] [--alt]
Aliases: dl, get. Takes full links (https://buzzheavier.com/<id>), bare file IDs or direct file links, saves each file under its original name and prints the path it was saved to. No account ID is needed.
| Option | Description |
|---|---|
-o, --output <path> |
A file name, or a directory to save into (existing, or ending with /). - writes the file to stdout. Default: the current directory. |
-f, --force |
Overwrite an existing file. Without it an existing file is never touched. |
--alt |
Use the site's alternative download server ("mirror 2"). |
$ ./buzzheavier.sh download https://buzzheavier.com/abc123def456 -o ~/Downloads/
→ Downloading video.mp4 (148.2MB)
######################################################################## 100.0%
✔ Saved /home/me/Downloads/video.mp4 (148.2 MB)
/home/me/Downloads/video.mp4- Resume: data is written to
<name>.partfirst. If a download is interrupted, run the same command again and it continues where it stopped. - File names come from the server and are cleaned up before use: path separators and control characters are removed, so a file can only ever land in the directory you chose.
- Only single files: links to directories are not supported.
BuzzHeavier has no download API, so this command reads the public file page the same way a browser does. The site often answers plain
curlwith a browser check (HTTP 403) instead of the page - in testing, 7 of 10 requests. Withcurl_cffiinstalled (pip install curl_cffi), downloads are sent with a real browser's TLS fingerprint and got through 10 of 10 times; without it the CLI falls back tocurl. If a browser check still comes back, the CLI stops with an explanation. If the site changes its pages, this command may need an update.
When the browser check gets in the way, open the file page in your browser, click Copy download link and give that direct link to the CLI. It skips the file page entirely, and name detection, -o, --force and resume work the same:
./buzzheavier.sh download "https://<server>/d/<id>?v=<token>" -o ~/Downloads/Direct links expire after a while; copy a fresh one if it is refused.
All of these need the account ID.
| Command | Description |
|---|---|
ls [dirId] |
List the root directory or the given directory |
mkdir <name> [parentId] |
Create a directory and print its ID. Without parentId it is created in the root directory (this lookup needs jq). |
rename <id> <newName> |
Rename a file or directory |
mv <id> <newParentId> |
Move a file or directory |
note <fileId> <text> |
Set or replace the note of a file |
rm <id>... |
Delete files or directories; a directory is deleted with everything inside it |
rm asks for confirmation when run in a terminal. Pass -y to skip the question. When input is not a terminal (scripts, pipes) it does not ask.
With jq installed, ls prints a table:
$ ./buzzheavier.sh ls
Directory: root [id: r00t1d2x3y4z]
TYPE ID SIZE DL CREATED NAME
dir d1r2e3x4a5m6 - - 2026-11-10 Backups/
file f1l2e3x4a5m6 112.3 KB 4 2025-12-31 notes.txtThe official API reference lists
PUTfor moving items and setting notes, but the server only acceptsPATCHfor them (PUTanswers405 Method Not Allowed). This CLI usesPATCH.
| Command | Description |
|---|---|
account |
Show account information |
locations |
List storage locations (no account needed) |
set-token [account_id] |
Save the account ID (prompts when omitted) |
unset-token |
Remove the saved account ID |
config |
Show the configuration; the account ID is masked |
interactive |
Menu-driven mode |
help, version |
Help and version |
| Option | Description |
|---|---|
--json |
Print the raw API response instead of formatted output |
-q, --quiet |
No progress or status messages (errors are still shown) |
-y, --yes |
Do not ask for confirmation before deleting |
--no-color |
Disable colours |
-h, --help |
Show help |
-V, --version |
Show the version |
-- |
Treat everything after it as arguments, e.g. a file called -q |
Options can be placed before or after the command.
The CLI is built to be used from scripts:
- stdout carries only the result: download links, paths of downloaded files, tables, IDs or JSON.
- stderr carries progress, status and error messages.
- Exit code is
0on success,1on failure (network error or an error response from the API) and2for wrong usage.
# Capture the link of an upload
link=$(./buzzheavier.sh -q upload backup.tar.gz) || echo "upload failed" >&2
# Create a directory and upload into it
dir=$(./buzzheavier.sh mkdir "Backups $(date +%F)")
./buzzheavier.sh upload *.tar.gz -d "$dir"
# Download and unpack without keeping the archive
./buzzheavier.sh -q download <id> -o - | tar xz
# Work with the raw API response
./buzzheavier.sh ls --json | jq -r '.data.children[].name'The account ID is passed to curl on standard input rather than as a command-line argument, so it is not visible to other users in the process list.
./buzzheavier.sh interactiveBuzzheavier CLI v2.2.0 - account ID: ab…wxyz
Upload
1) Upload a file (anonymous)
2) Upload file(s) into a directory
Download
3) Download a file from a link
Browse
4) List root directory
5) List a directory
Manage
6) Create directory
7) Rename file or directory
8) Move file or directory
9) Set a file note
10) Delete file or directory
Account
11) Account info
12) Storage locations
13) Set account ID
14) Show config
q) Quit
Choose an option:
The command names of version 1 keep working, with the same arguments:
| Legacy command | Now |
|---|---|
upload-anon <filePath> [fileName] |
upload <file> [-n <name>] |
upload-auth <filePath> <parentId> [fileName] [account_id] |
upload <file> -d <dirId> |
upload-loc <filePath> <fileName> <locationId> |
upload <file> -l <id> |
upload-note <filePath> <fileName> <noteString> |
upload <file> --note <text> |
bulk-upload <parentId> <file1> [file2] ... |
upload <file>... -d <dirId> |
get-root [account_id], get-dir <directoryId> [account_id] |
ls [dirId] |
create-dir <name> <parentId> [account_id] |
mkdir <name> [parentId] |
rename-dir, rename-file <id> <newName> [account_id] |
rename <id> <newName> |
move, move-dir, move-file <id> <newParentId> [account_id] |
mv <id> <newParentId> |
add-note-file <fileId> <noteString> [account_id] |
note <fileId> <text> |
delete-dir <directoryId> [account_id] |
rm <id> |
bulk-delete <dirId1> [dirId2] ... |
rm <id>... |
Differences from version 1 that scripts may notice:
- Status messages (
Uploading ...) now go to stderr, and uploads print only the download link on stdout. Use--jsonto get the API response as before. - Failed requests now return a non-zero exit code.
- Moving items and setting notes (
move-*,add-note-file) now work; version 1 sentPUT, which the server rejects. delete-dirandbulk-deleteask for confirmation when run in a terminal (-yskips it).
- Bash and
curl jq(optional) - formatted tables andmkdirwithout a parent IDbase64oropenssl- only for upload notesgrep,sed,tr- only for downloads (present on any Unix-like system)- Python 3 with
curl_cffi(optional, recommended for downloads) -pip install curl_cffi. When it is installed, downloads are sent with a real browser's TLS fingerprint, which the site's browser check blocks far less often than plaincurl(plaincurlgot HTTP 403 wherecurl_cffigot the page). Without it, downloads fall back tocurl.BUZZHEAVIER_DOWNLOADER=auto|cffi|curlforces a transport,BUZZHEAVIER_IMPERSONATE(defaultchrome) picks the browser to imitate.
Tested with Bash 5 on Linux and on Windows (Git Bash and WSL). The script avoids Bash 4+ only features, so the Bash 3.2 that ships with macOS should work too.
The test suite runs every command against a small local mock of the API, so nothing is sent to buzzheavier.com:
bash tests/run.sh # needs python3MIT License – you are free to fork and modify.