dbxcli: Dropbox from the command line
dbxcli is a scriptable Dropbox CLI for files, shared links, teams, and
automation workflows. It is built for humans in the terminal, scripts, CI jobs,
and agent-style workflows.
Why use dbxcli?
- Work with Dropbox from the terminal
- Upload and download files, folders, and streams
- Create, inspect, update, revoke, and download shared links
- Use JSON output for scripts and automation
- Pipe generated content directly into Dropbox
- Manage team workflows with member-scoped access
Quickstart
dbxcli login
dbxcli ls /
dbxcli put local.txt /remote.txt
dbxcli get /remote.txt ./remote.txt
dbxcli share-link create /remote.txt
On team accounts where / is not writable, run dbxcli ls / and use a
writable personal or team folder instead.
For automation, use structured command output and JSON help discovery:
dbxcli ls --output=json /
dbxcli --help --output=json
dbxcli put --help --output=json
Stable JSON error codes and process exit codes are documented in Automation and JSON output.
JSON output
--output=json emits stable schema v1 success and error envelopes for
automation. Use JSON help for machine-readable command manifests:
dbxcli --help --output=json
dbxcli put --help --output=json
See the JSON schema v1 docs for schemas, stability policy, command contracts, and examples.
Common workflows
Upload a file:
dbxcli put report.pdf /Reports/report.pdf
Upload without overwriting:
dbxcli put --if-exists fail report.md /Reports/report.md
Upload from a pipe:
tar cz ./project | dbxcli put - /Backups/project.tgz
Download to stdout:
dbxcli get /Backups/project.tgz - | tar tz
Create a shared link:
dbxcli share-link create /Reports/report.pdf
In text mode, share-link create prints only the shared-link URL to stdout:
url="$(dbxcli share-link create /Reports/report.pdf)"
Troubleshooting
Why can uploading to /remote.txt fail on team accounts?
Some team accounts may not have a writable Dropbox root namespace. Run
dbxcli ls / first, then upload under a writable folder, such as your personal
folder or a team folder.
Features
- File operations:
ls,cp,mkdir,mv,rm,put, andget - Recursive upload and download with
put -randget -r - Pipe-friendly transfers with stdin upload and stdout download
- Conflict control with
put --if-exists overwrite|skip|failandcp/mv --if-exists fail|skip - Shared-link creation, listing, inspection, update, revoke, and download
- 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
- Direct token automation with
DBXCLI_ACCESS_TOKEN - Alternate saved-credential files with
DBXCLI_AUTH_FILE - Structured JSON success and error envelopes for migrated commands
- JSON help manifests for machine-readable command discovery
- Team administration commands and member-scoped access with
--as-member
Installation
Homebrew
brew install dbxcli
Homebrew formula: formulae.brew.sh/formula/dbxcli
Release archives
Download the archive for your platform from the
releases page, verify its
checksum, and install the dbxcli binary somewhere on your PATH.
Linux example:
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/
Release assets include:
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
Build from source
go install github.com/dropbox/dbxcli/v3@latest
Or build from a clone:
git clone https://github.com/dropbox/dbxcli.git
cd dbxcli
go build .
Support posture
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.
Command reference
The complete generated command reference is available here:
For command-specific help, run:
dbxcli --help
dbxcli put --help
dbxcli share-link --help
dbxcli share-link create --help
For machine-readable command discovery, use JSON help:
dbxcli --help --output=json
dbxcli put --help --output=json
Deeper documentation
Generated Cobra command docs live under docs/commands/, and CI verifies they
stay in sync with the CLI.
Contributing
- If you are 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.