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, and get
• Recursive upload and download with put -r and get -r
• Pipe-friendly transfers with stdin upload and stdout download
• Conflict control with put --if-exists overwrite|skip|fail and cp/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/

For security-sensitive direct downloads, verify the signed checksum file and provenance before installing:

curl -LO https://github.com/dropbox/dbxcli/releases/download/vX.Y.Z/SHA256SUMS.sigstore.json
cosign verify-blob SHA256SUMS \
  --bundle SHA256SUMS.sigstore.json \
  --certificate-identity "https://github.com/dropbox/dbxcli/.github/workflows/release.yml@refs/tags/vX.Y.Z" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

curl -LO https://github.com/dropbox/dbxcli/releases/download/vX.Y.Z/dbxcli_X.Y.Z_slsa.intoto.jsonl
slsa-verifier verify-artifact dbxcli_X.Y.Z_linux_amd64.tar.gz \
  --provenance-path dbxcli_X.Y.Z_slsa.intoto.jsonl \
  --source-uri github.com/dropbox/dbxcli \
  --source-tag vX.Y.Z

Release assets include:

• dbxcli_X.Y.Z_darwin_amd64.tar.gz
• dbxcli_X.Y.Z_darwin_arm64.tar.gz
• dbxcli_X.Y.Z_linux_amd64.tar.gz
• dbxcli_X.Y.Z_linux_arm64.tar.gz
• dbxcli_X.Y.Z_linux_arm.tar.gz
• dbxcli_X.Y.Z_openbsd_amd64.tar.gz
• dbxcli_X.Y.Z_windows_amd64.zip
• SHA256SUMS
• SHA256SUMS.sigstore.json
• dbxcli_X.Y.Z_sbom.spdx.json
• dbxcli_X.Y.Z_slsa.intoto.jsonl

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:

• dbxcli command reference

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

• Automation and JSON output
• Sharing workflows
• JSON schema v1
• Release history

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.

Useful resources

• Go SDK documentation
• Dropbox API documentation