dbxcli is maintained in the Dropbox GitHub organization by Dropbox engineers, but it is not a formally supported Dropbox product. Use GitHub issues and pull requests for bugs and contributions; Dropbox Support does not provide support for this CLI. The CLI implements a practical subset of Dropbox API features, not the full API surface.
- File operations:
ls,cp,mkdir,mv,rm,put, andget - Recursive upload and download with
put -randget -r - Pipe-friendly transfers: upload from stdin with
put -and download to stdout withget ... - - Upload conflict control with
put --if-exists overwrite|skip|fail - Shared-link management with
share-link create,list,info,update,revoke, anddownload - Structured JSON output with stable success and error envelopes for migrated commands
- Search, file revisions, restore, flexible sorting, and time formatting
- Chunked uploads for large files and paginated listing for large directories
- OAuth login with refreshable saved credentials,
DBXCLI_ACCESS_TOKEN, andDBXCLI_AUTH_FILE - Team administration commands and member-scoped access with
--as-member
dbxcli login
dbxcli ls /
dbxcli put local.txt /remote.txt
dbxcli get /remote.txt ./remote.txt
dbxcli share-link create /remote.txtSee the GitHub Releases page for version-by-version changes.
brew install dbxcliDownload the archive for your architecture, verify its checksum, and install. Replace X.Y.Z with the latest version from the Releases page (without the leading v).
curl -LO https://github.com/dropbox/dbxcli/releases/download/vX.Y.Z/dbxcli_X.Y.Z_linux_amd64.tar.gz
curl -LO https://github.com/dropbox/dbxcli/releases/download/vX.Y.Z/SHA256SUMS
grep 'dbxcli_X.Y.Z_linux_amd64.tar.gz' SHA256SUMS | sha256sum -c -
tar -xzf dbxcli_X.Y.Z_linux_amd64.tar.gz
sudo mv dbxcli_X.Y.Z_linux_amd64/dbxcli /usr/local/bin/For ARM systems, use linux_arm64 or linux_arm instead of linux_amd64.
If you prefer not to use Homebrew:
curl -LO https://github.com/dropbox/dbxcli/releases/download/vX.Y.Z/dbxcli_X.Y.Z_darwin_arm64.tar.gz
curl -LO https://github.com/dropbox/dbxcli/releases/download/vX.Y.Z/SHA256SUMS
grep 'dbxcli_X.Y.Z_darwin_arm64.tar.gz' SHA256SUMS | shasum -a 256 -c -
tar -xzf dbxcli_X.Y.Z_darwin_arm64.tar.gz
sudo mv dbxcli_X.Y.Z_darwin_arm64/dbxcli /usr/local/bin/Use darwin_amd64 for Intel Macs.
Download dbxcli_X.Y.Z_windows_amd64.zip from the Releases page, extract it, and add the directory to your PATH.
All release archives are available at the releases page:
dbxcli_X.Y.Z_darwin_amd64.tar.gzdbxcli_X.Y.Z_darwin_arm64.tar.gzdbxcli_X.Y.Z_linux_amd64.tar.gzdbxcli_X.Y.Z_linux_arm64.tar.gzdbxcli_X.Y.Z_linux_arm.tar.gzdbxcli_X.Y.Z_openbsd_amd64.tar.gzdbxcli_X.Y.Z_windows_amd64.zipSHA256SUMS
- Make sure
gitandgoare installed. - Install the latest released version:
$ go install github.com/dropbox/dbxcli@latest
- Or build from source:
$ git clone https://github.com/dropbox/dbxcli.git $ cd dbxcli $ go build .
To use your own Dropbox app while developing, provide its app key when logging in:
$ dbxcli login --app-key=your-app-keydbxcli is largely self-documenting. Run dbxcli -h for a list of supported commands:
$ dbxcli --help
Use dbxcli to quickly interact with your Dropbox, upload/download files,
manage your team and more. It is easy, scriptable and works on all platforms!
Usage:
dbxcli [command]
Available Commands:
account Display account information
completion Generate the autocompletion script for the specified shell
cp Copy a file or folder to a different location in the user's Dropbox. If the source path is a folder all its contents will be copied.
du Display usage information
get Download a file or folder
help Help about any command
login Log in and save Dropbox credentials
logout Log out of the current session
ls List files and folders
mkdir Create a new directory
mv Move files
put Upload files or directories
restore Restore a file revision
revs List file revisions
rm Remove files or folders
search Search
share Sharing commands
share-link Shared link commands
team Team management commands
version Print version information
Flags:
--as-member string Member ID to perform action as
-h, --help help for dbxcli
--output string Output format: text, json (default "text")
-v, --verbose Enable verbose logging
Use "dbxcli [command] --help" for more information about a command.The complete generated command reference is available in docs/commands/dbxcli.md.
Text output is the default. JSON output is available through the global --output flag for migrated commands:
$ dbxcli ls --output=json /Command results are written to stdout. Status, progress, human-facing warnings, diagnostics, and verbose logs are written to stderr.
Successful JSON responses return ok: true, schema_version: "1", command, an input object, a results array, and a warnings array. Each result includes status, kind, input, and result. Machine-actionable JSON warnings use the warnings array.
{
"ok": true,
"schema_version": "1",
"command": "ls",
"input": {
"path": "/Reports",
"recursive": false,
"include_deleted": false,
"only_deleted": false,
"long": false,
"reverse": false,
"time": "server"
},
"results": [
{
"status": "listed",
"kind": "file",
"input": {},
"result": {
"type": "file",
"path_display": "/Reports/q1.pdf",
"path_lower": "/reports/q1.pdf",
"id": "id:...",
"rev": "...",
"size": 123
}
}
],
"warnings": []
}In JSON mode, error responses are written to stdout and the process exits with a non-zero status. JSON errors return ok: false, a stable error.code, a human-readable error.message, optional error.details, and warnings:
{
"ok": false,
"schema_version": "1",
"command": "rm",
"error": {
"message": "path exists and is not a folder: /old-file.txt",
"code": "path_conflict"
},
"warnings": []
}The full JSON command catalog, stable error codes, and schemas live in docs/json-schema/v1. Commands that intentionally do not support JSON output yet include login, logout, and completion. Help output and shell-completion protocol commands are text-only.
By default, dbxcli stores OAuth credentials in ~/.config/dbxcli/auth.json.
Run dbxcli login to authorize dbxcli and save credentials:
$ dbxcli loginCommands require saved credentials. If no saved credentials are available, run
dbxcli login first or provide a token with DBXCLI_ACCESS_TOKEN.
Personal and team logins use bundled Dropbox app keys by default. You can pass a custom app key as an option:
$ dbxcli login --app-key=your-app-keyYou can also set custom app keys with environment variables:
$ DROPBOX_PERSONAL_APP_KEY=your-app-key dbxcli login
$ DROPBOX_TEAM_APP_KEY=your-app-key dbxcli login team-access
$ DROPBOX_MANAGE_APP_KEY=your-app-key dbxcli login team-manageSaved login credentials include a Dropbox refresh token and are refreshed
automatically when the access token expires. If saved credentials are revoked or
need to be replaced, run dbxcli login again.
Set DBXCLI_AUTH_FILE to use a different credentials file:
$ DBXCLI_AUTH_FILE=/path/to/auth.json dbxcli loginFor automation with short-lived Dropbox access tokens, set DBXCLI_ACCESS_TOKEN.
This token is used directly and is not saved or refreshed. If it expires, the
command fails and you must provide a fresh token:
$ DBXCLI_ACCESS_TOKEN=sl.xxxxxx dbxcli ls /$ dbxcli ls -l /Photos
Revision Size Last modified Path
abc123 1.2 MiB 3 weeks ago /Photos/vacation.jpg
def456 4.5 MiB 1 month ago /Photos/family.pngBy default, ls -l, search -l, and revs -l show relative timestamps ("3 weeks ago"). Use --time-format for absolute dates:
$ dbxcli ls -l --time-format=short /Photos
Revision Size Last modified Path
abc123 1.2 MiB 2026-05-15 10:30 /Photos/vacation.jpg
$ dbxcli ls -l --time-format=rfc3339 /Photos
Revision Size Last modified Path
abc123 1.2 MiB 2026-05-15T10:30:00Z /Photos/vacation.jpgUse --time=client to display client-modified time instead of server-modified (default):
$ dbxcli ls -l --time=client --time-format=short /PhotosSort results with --sort and optionally --reverse:
$ dbxcli ls -l --sort=size /Documents # smallest first
$ dbxcli ls -l --sort=size --reverse /Documents # largest first
$ dbxcli ls -l --sort=name /Documents # alphabetical
$ dbxcli ls -l --sort=time /Documents # oldest first
$ dbxcli ls -l --sort=type /Documents # folders, files, deleted$ dbxcli search -l --time-format=short --sort=size "report"All --sort, --reverse, --time, and --time-format flags work with both ls and search. The --time and --time-format flags also work with revs -l.
Create shared links:
$ dbxcli share-link create /file.txt # create or return an existing shared link
$ dbxcli share-link create /file.txt --access viewer # create a link with requested access
$ dbxcli share-link create /file.txt --audience team # create a link with requested audience
$ dbxcli share-link create /file.txt --allow-download # create a downloadable shared link
$ dbxcli share-link create /file.txt --disallow-download # create a shared link with downloads disabled
$ dbxcli share-link create /file.txt --expires 2026-07-01T00:00:00Z # create an expiring shared link
$ dbxcli share-link create /file.txt --password-prompt # create a password-protected shared link
$ dbxcli share-link create /file.txt --remove-expiration # remove expiration when returning an existing linkInspect and list shared links:
$ dbxcli share-link info <url> # display shared link information
$ dbxcli share-link info <url> --path /nested/file.txt # display information for a path inside the shared link
$ dbxcli share-link list # list existing shared links
$ dbxcli share-link list /file.txt # list direct shared links for a pathDownload shared links:
$ dbxcli share-link download <url> [target] # download a shared-link file
$ dbxcli share-link download <url> --path /nested/file.txt # download a file inside a folder shared link
$ dbxcli share-link download <url> ./local.txt --path /nested/file.txt # download nested file to a local target
$ dbxcli share-link download <url> [target] --recursive # download a folder shared linkUpdate shared links:
$ dbxcli share-link update <url> --allow-download # update shared link settings
$ dbxcli share-link update <url> --disallow-download # disable downloads from a shared link
$ dbxcli share-link update <url> --audience public # update shared link audience
$ dbxcli share-link update <url> --expires 2026-07-01T00:00:00Z # update shared link expiration
$ dbxcli share-link update <url> --remove-expiration # remove shared link expiration
$ dbxcli share-link update <url> --password-prompt # set or change a shared link password
$ dbxcli share-link update <url> --remove-password # remove a shared link passwordRevoke shared links:
$ dbxcli share-link revoke <url> # revoke a shared link
$ dbxcli share-link revoke --path /file.txt # revoke direct shared links for a pathCompatibility and shared folders:
$ dbxcli share list link # deprecated compatibility command
$ dbxcli share list folder # list shared foldersshare-link create --access supports viewer, editor, and max. Dropbox does not support changing access for an existing shared link, so --access fails clearly if the link already exists.
share-link create --audience and share-link update --audience support public, team, members, and no-one. Dropbox team and folder policies can still resolve the effective audience differently.
Dropbox account, team, and folder policies can reject shared-link settings such as passwords, expiration, audience, or disabled downloads. In that case, dbxcli returns the Dropbox API error, for example settings_error/not_authorized/.
share-link create, share-link update, share-link info, and share-link download support --password <value>, --password-prompt, and --password-file <path> for password-protected links. Use --password-prompt for interactive use so the password is not echoed.
share-link download writes to the metadata filename when target is omitted. Use --path to download a single file inside a folder shared link. Use - as the target to write file bytes to stdout. Folder shared links require --recursive and cannot be written to stdout.
$ dbxcli team --help
Team management commands
Usage:
dbxcli team [command]
Available Commands:
add-member Add a new member to a team
info Get team information
list-groups List groups
list-members List team members
remove-member Remove member from a team
Global Flags:
--as-member string Member ID to perform action as
--output string Output format: text, json (default "text")
-v, --verbose Enable verbose logging
Use "dbxcli team [command] --help" for more information about a command.The --verbose option will turn on verbose logging and is useful for debugging.
$ dbxcli put file.txt /destination/file.txt # upload a single file
$ dbxcli put -r ./project /backup/project # recursively upload a directory
$ dbxcli put -w 1 -c 134217728 large.zip /backup/large.zip
$ dbxcli put --if-exists skip file.txt /dest.txt # skip if the file already existsBy default, put overwrites existing destination files. Use --if-exists overwrite|skip|fail to choose whether existing files are overwritten, skipped, or treated as an error.
For files larger than 32MiB, put uses Dropbox upload sessions. By default, it
uses 4 workers and 16MiB chunks. Each chunk is one upload-session request; chunk
size must be a multiple of 4MiB and no more than 128MiB. On unstable networks,
fewer workers and larger chunks may be more reliable:
$ dbxcli put -w 1 -c 134217728 large.zip /backup/large.zip$ dbxcli get /remote/file.txt ./local-file.txt # download a single file
$ dbxcli get -r /remote/folder ./local-folder # recursively download a folderUse - as the local operand to stream through pipes:
$ printf 'hello' | dbxcli put - /hello.txt # upload from stdin
$ tar cz ./src | dbxcli put - /backups/src.tgz # pipe archive to Dropbox
$ dbxcli get /backups/src.tgz - | tar tz # download to stdout and list
$ dbxcli get /file.txt - > local-copy.txt # download to stdout, redirect to fileStdin uploads are spooled to a temp file before uploading, so disk space up to the full input size is required. Stdout downloads are byte-clean: all progress and diagnostic output goes to stderr.
A bare - means stdin/stdout only when it appears as the local operand. Dropbox paths named - are valid, for example dbxcli put - /- and dbxcli get /- -. To upload a local file literally named -, use ./-.
$ dbxcli rm /remote/file.txt # move a file to Dropbox trash
$ dbxcli rm -r /remote/folder # remove a non-empty folder
$ dbxcli rm --permanent /remote/file.txt # permanently delete when Dropbox permits it$ dbxcli mkdir /projects/2026/reports # creates all intermediate directories
$ dbxcli mkdir -p /projects/2026/reports # no error if directory already exists- If you're submitting a non-trivial change, please fill out the Dropbox Contributor License Agreement first.
- Open a pull request with a clear description of the change.
- Include tests or manual validation details when relevant.