CLI commands

This page follows bb --help for bb 0.14.0. Run bb <command> --help for the full flag list of any command.

Global flags

Every command accepts these.

Flag	What it does
--json	Structured JSON output.
--quiet	Minimal output, no progress or colors.
--no-color	Disable colored output.
--api <url>	Override the API endpoint for this command.

Files

Command	What it does
bb ls [path]	List files. Names are decrypted locally.
bb mkdir <path>	Create a folder. Mirrors mkdir -p with -p.
bb mv <src> <dst>	Move or rename. Mirrors mv.
bb rm <path|id>...	Move files or folders to the trash. Folders need -r. Reversible.
bb restore <name|id>	Restore from the trash.
bb trash list	Browse the trash.
bb search <query>	Find files by name. --regex for a case-insensitive regular expression.
bb push <path>	Upload a file or folder. Encrypts on the fly.
bb pull <id|path>	Download and decrypt. --zip downloads a whole folder as a zip.
bb share <path|id>	Create an encrypted share link with expiry and an optional passphrase.
bb sync <dir> [remote]	Sync a local folder with a vault path. Continuous by default.
bb webdav	Serve your vault over local WebDAV. See Mount as a drive.
bb whoami	Session, device, region and quota.
bb speedtest	Benchmark network and crypto speed.
bb repair	Repair files encrypted with the old binary-UUID key derivation, so they open in the web app.

bb upload and bb download are accepted as aliases of bb push and bb pull.

Examples

bb ls /Photos -l
bb mkdir -p /Photos/2026
bb push ./holiday --folder Photos
bb search "invoice" --folder /Documents
bb pull Photos --zip
bb rm -r old-project
bb trash list
bb restore old-project

Uploads that collide

bb push takes --replace (replace the existing file, which creates a new version) or --keep-both (upload with a numeric suffix).

Downloads never overwrite silently

Without -f/--force, bb pull never replaces an existing file. It asks on an interactive terminal and exits non-zero otherwise. Use -o <path> to save elsewhere.

Permanent deletion

bb rm --permanent and bb trash empty are irreversible and require a step-up password confirmation.

Sharing and requests

Command	What it does
bb shares	List active share links.
bb unshare [share-id]	Revoke a share link. Omit the ID for an interactive picker.
bb request create	Create a file request and print its link. Anyone with the link can upload into your vault.
bb request list	List your file requests with received counts and links.
bb request rm	Close (default) or hard-delete a file request.
bb request send	Upload files to a request link. No account needed.

Sync

bb sync <dir> [remote] syncs and then keeps watching. Useful flags:

Flag	What it does
--once	Sync once and exit.
--dry-run	Show what would change without changing anything.
--daemon	Run as a background daemon with auto-start on login.
--status	Show all active sync sessions across devices.
--stop-session <name>	Stop one sync session.
--stop-all	Stop all sync sessions on this device.
--delete	Trash remote files that no longer exist locally. Use with care.
--force	Overwrite conflicts with the local copy.

bb watch <path> watches a folder and auto-syncs changes to your vault.

Account and session

Command	What it does
bb signup	Print the web signup URL and open it. The CLI signs in, it does not sign up.
bb login	Sign in. --headless prints only a URL and a code.
bb logout	End the current session.
bb status	Connection status, session health, storage usage.
bb quota	Storage used, total and file count.
bb config	Show current configuration with secrets masked.
bb account show	Profile, plan, security, sessions, passkeys.
bb account update	Change your email address. A verification goes to the new inbox.
bb account billing	Open the billing portal.
bb account addons	View or purchase billing add-ons.
bb billing show	Plan, storage usage, renewal date, pending changes.
bb billing usage	Storage usage with a per-region breakdown.
bb billing invoices	List invoices.
bb billing portal	Open the billing portal.
bb billing addons	View or purchase billing add-ons.
bb 2fa status	Show whether TOTP two-factor authentication is enabled.
bb 2fa setup	Begin setup. Returns a secret, a QR code and backup codes.
bb 2fa enable	Confirm a TOTP code to enable 2FA after setup.
bb 2fa disable	Disable 2FA. Requires a valid TOTP code.
bb sessions list	List active sessions. The current one is marked *.
bb sessions revoke	Revoke one session by ID or unique ID prefix.
bb sessions revoke-all-others	Revoke every session except this one.
bb passkey list	List registered passkeys.
bb passkey add	Register a passkey. Opens the web app, because WebAuthn only runs in a browser.
bb passkey remove	Remove a passkey by ID or unique ID prefix.
bb region list	List storage locations by country, with your choice marked.
bb region get	Show your current choice.
bb region set	Choose where new uploads are stored.

bb region with no subcommand lists the options. A location that is not live yet is shown as coming soon and cannot be chosen.

Shell completions

bb completions <shell> prints a completion script. Shells: bash, elvish, fish, powershell, zsh.