The BucketWorx command line (CLI)

Last updated: November 9, 2026

The BucketWorx CLI, bucketworx-cli, does everything the app does from a terminal or a script, with the same accounts and settings.

bucketworx-cli does the same jobs without a window, and uses the same accounts and settings as the app. Add --account NAME to pick an account, and --json for machine-readable output.

accounts list	Name, provider, region and endpoint of each account.
accounts add	Add an account. --provider is aws, cloudflare-r2, backblaze-b2, wasabi, do-spaces, minio, neon, supabase (from beta 4) or generic. Give --access-key-id or --profile.
accounts remove NAME	Remove an account and its stored secret.
accounts use NAME	Choose the account the free edition uses.
accounts export FILE	Save every account to a file, without secret keys (from beta 5). Use - for standard output.
accounts import FILE	Add the accounts from an exported file (from beta 5). At a terminal it asks about name clashes and lists what it will import; in a script give --on-conflict skip\|rename\|replace and --yes, plus --allow-profiles or --allow-certs for accounts that use an AWS profile or their own certificate.
accounts set-secret NAME	Save only an account's secret key, for example after an import (from beta 5). --secret-from-env reads it from BUCKETWORX_SECRET instead of the terminal.
ls [s3://bucket/path]	List an account's buckets, or a folder's contents. --deleted-only lists only what was deleted there and in every folder below (from beta 4). --multi-version lists the files with several versions, biggest older versions first, with --min N (from beta 5).
mb BUCKET	Create a bucket, checking the name first.
cp SRC DEST [-r]	Upload, download or copy. One side must be an s3:// path. -r copies a folder. From beta 5, an upload follows your upload rules; --cache-control, --content-type, --meta, --tag, --storage-class and the other header options set values for this upload, and --no-upload-rules ignores the rules.
mv SRC DEST [-r]	Move within S3. --to-account NAME moves to another account (Pro).
rename s3://bucket/old NEW	Rename an object, or a folder and everything in it.
rm s3://bucket/key [-r]	Delete an object, or a folder with -r.
tags add \| remove s3://bucket/key	Add tags (KEY=VALUE, replacing a key's value) or remove keys (KEY) on an object, or with -r on everything in a folder (from beta 5). A folder asks first; in a script add --yes.
lock show \| hold \| retain s3://bucket/key	See or change a version's Object Lock (from beta 5): hold PATH on\|off, or retain PATH --mode governance\|compliance --until DATE (or --remove). --bypass shortens governance retention, --version-id picks a version, -r does a folder. A folder, or setting compliance, asks first; in a script add --yes.
share s3://bucket/key	Print a download link. --expires takes 90s, 30m, 1h or 7d, up to 7 days; the default is 1 day. From beta 5 it takes several paths, even across buckets, and prints one link per line (--with-keys adds each key before its link); --version-id links to an older version of one file. --upload makes an upload link for one key instead, with --content-type, and --curl prints the upload command.
sync SRC DEST	Make one folder match another: local to bucket, bucket to local, or bucket to bucket. Uploads follow your upload rules unless you add --no-upload-rules (from beta 5).
upload-rules list	List your upload rules, in the order they apply (from beta 5). Edit them in Settings, Uploads.
scan [--account NAME]	The security scan: who can reach each of an account's buckets. From beta 5 it prints the command that fixes each finding, and --json lists them as fixes.
acl remove-public s3://bucket	Remove one public grant from a bucket's ACL (from beta 5): --grantee AllUsers or AuthenticatedUsers, plus --permission when that grantee has several. It asks first; in a script add --yes.
palette QUERY	Search commands and places.
transfers list \| resume \| clear	See, resume or cancel transfers an earlier run didn't finish.
licence show \| add \| remove	See, add or remove a Pro licence key.
cors show \| set \| remove s3://bucket	See, replace or remove a bucket's CORS rules (from beta 4). set reads the rules from a file or -; --expect FILE refuses if the rules changed from those, and --yes skips the question.
policy show \| set \| remove s3://bucket	See, replace or remove a bucket's policy (from beta 4), with the same --expect and --yes as cors. A policy that could lock everyone out of it is refused unless you add --allow-lockout.
lifecycle show \| set \| remove s3://bucket	See, replace or remove a bucket's lifecycle rules (from beta 4), with the same --expect and --yes as cors. Setting them says which rules delete files, old versions or delete markers first.
website show \| set \| remove s3://bucket	See, replace or remove a bucket's website settings (from beta 4), with the same --expect and --yes as cors.

bucketworx-cli ls s3://photos-demo/2026/
bucketworx-cli cp ./report.pdf s3://invoices-demo/2026/
bucketworx-cli share s3://photos-demo/2026/spring/IMG_1004.jpg --expires 1d
bucketworx-cli sync ./spring s3://photos-demo/2026/spring/ --dry-run

Keys. accounts add asks for the secret key on the terminal and never takes it as an argument. In scripts, add --secret-from-env and put the key in the BUCKETWORX_SECRET variable.
Sync safely. sync prints a plan first: each file it would upload, download or delete and why, then totals, or "Already in sync." --dry-run stops there, --verbose also lists unchanged files, and --delete removes what is only in the destination. Before deleting it asks "Delete 2 objects (1.1 MiB)? [y/N]". In a script you need --yes. A sync that would delete everything because the source is empty is refused. Running a sync needs Pro. --dry-run works in both editions.
Settings somewhere else. --config-dir DIR keeps settings in another folder.

More help

Topics

Step-by-step guides

All help, including installing BucketWorx.