dbxcli

A command line client for Dropbox built using the Go SDK

View on GitHub

dbxcli: Dropbox from the command line

CI Scorecard CodeQL

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?

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 envelopes, error codes, and process exit codes are documented in Automation and JSON output.

JSON output

For commands that support structured execution output, --output=json runs the command and emits stable schema v1 success and error envelopes for automation.

JSON help is the machine-readable command-discovery surface. Use it to discover command paths, arguments, flags, aliases, input schemas, auth behavior, stdin/stdout behavior, schema references, and whether structured command execution output is supported:

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.

Proxy configuration

dbxcli uses Go’s standard HTTP proxy behavior, so HTTPS_PROXY, HTTP_PROXY, and NO_PROXY apply to Dropbox API requests and OAuth token exchange/refresh requests made by the CLI.

For Dropbox API and OAuth requests, set HTTPS_PROXY:

HTTPS_PROXY=http://127.0.0.1:8080 dbxcli ls /

For a shell session:

export HTTPS_PROXY=http://proxy.company.example:8080
export NO_PROXY=localhost,127.0.0.1,.company.example
dbxcli login

On Windows PowerShell:

$env:HTTPS_PROXY = "http://127.0.0.1:8080"
dbxcli login

On Windows cmd:

set HTTPS_PROXY=http://127.0.0.1:8080
dbxcli login

HTTP_PROXY is also honored for plain HTTP requests. Use NO_PROXY to bypass the proxy for local or internal hosts. Lowercase forms such as https_proxy and no_proxy are also supported by Go’s HTTP stack.

If your proxy requires basic authentication, include credentials in the proxy URL:

HTTPS_PROXY=http://user:password@proxy.company.example:8080 dbxcli ls /

URL-encode special characters in proxy usernames or passwords. Be careful with proxy credentials in environment variables, shell history, CI logs, and process listings.

The browser authorization step in dbxcli login is outside dbxcli; configure your browser or operating-system proxy separately if that page also needs a proxy.

Features

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:

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

Useful resources