dbxcli is a Dropbox command line client designed for scripts

A CLI whose stated audience is scripts and agents

The project describes dbxcli as a scriptable Dropbox CLI for files, shared links, teams and automation workflows, and says it is built for humans in the terminal, scripts, CI jobs and agent-style workflows. That list of four audiences is a statement of priorities, because the same set of features serves them unevenly.

For a human at a terminal, the command set is conventional and pleasant. The file operations are `ls`, `cp`, `mkdir`, `mv`, `rm`, `put` and `get`, with recursive transfers through `put -r` and `get -r`. The interesting surface is beyond that. Shared links can be created, listed, inspected, updated, revoked and downloaded. Search, file revisions, restore, flexible sorting and time formatting are all there, alongside chunked uploads for large files and paginated listing for large directories.

The team side comes with administration commands and member-scoped access through an `--as-member` flag, which is the feature that turns this from a file transfer tool into something a platform team can use to act as one member on behalf of another.

Authentication is OAuth with refreshable saved credentials, and there are two environment overrides for automation. `DBXCLI_ACCESS_TOKEN` bypasses the saved credential entirely for direct token automation, and `DBXCLI_AUTH_FILE` points at an alternate saved-credential file, which is what makes it possible to run several identities side by side on one machine.

The implementation is Go on a module path of `github.com/dropbox/dbxcli/v3`, requiring Go 1.26.0, with cobra for the command tree, the Dropbox SDK for Go, and `golang.org/x/oauth2` for the token handling.

The JSON contract is the real interface

Most command line tools offer a JSON flag as an afterthought. Here it is the centre of the design, and there are two of them.

The first is structured execution output. For commands that support it, `--output=json` runs the command and emits stable schema v1 success and error envelopes. The word stable is doing real work in that sentence, because a script that parses the output of a command in a CI job will break if the shape changes. The documentation for it is `docs/automation.md`, which covers the envelopes, the error codes and the process exit codes, and those three things together are what a caller actually depends on.

The second is JSON help, which the documentation calls the machine-readable command-discovery surface. Asking for help with `--output=json` returns the command paths, the arguments, the flags, the aliases, the input schemas, the auth behaviour, the stdin and stdout behaviour, the schema references, and whether structured command execution output is supported at all.

That is a more ambitious contract than a flag list, and it is the piece that makes agent-style use practical. A tool that can describe its own interface in a machine-readable form can be driven by something that did not have the documentation memorised.

dbxcli ls --output=json /
dbxcli --help --output=json
dbxcli put --help --output=json

The schemas, the stability policy, the command contracts and the examples live in the JSON schema v1 documentation under `docs/json-schema/v1/`. The repository also carries a `jsonschema` dependency for the v6 library.

Pipes are how data moves, not an afterthought

The pipe support is the part of the design that most clearly separates this from a wrapper around a desktop client. Both directions are supported, and the examples in the documentation are the kind that only work if the implementation is genuinely stream oriented.

Uploading from a pipe, where the source is stdin and the destination is a path:

tar cz ./project | dbxcli put - /Backups/project.tgz

Downloading to stdout, where the source is a path and the destination is stdout:

dbxcli get /Backups/project.tgz - | tar tz

The dash is the argument that selects the standard stream in each case, and the second example is a complete round trip: fetch an archive and list its contents without ever writing it to disk.

The feature list adds that there are chunked uploads for large files and paginated listing for large directories, which are the two places where a naive implementation falls over. A large directory listed in one page is a truncated result, and a large file uploaded in a single request is a request that fails.

Shared link creation is pipe friendly too. In text mode, `share-link create` prints only the shared-link URL to stdout, which means the URL can be captured without parsing a message around it.

url="$(dbxcli share-link create /Reports/report.pdf)"

That single property is what makes the tool usable in a report pipeline, where the link has to end up in a ticket or a chat message and nothing else should be printed.

Conflict behaviour is set explicitly

Overwrite behaviour is the classic way a script does something irreversible by accident, and dbxcli makes you name the policy.

The `put` command takes `--if-exists` with four values, `overwrite`, `skip`, `autorename` and `fail`. The `cp` and `mv` commands take the same flag with three values, `fail`, `skip` and `autorename`. The difference in the sets is not an inconsistency, it is that copying has no meaningful overwrite case when the destination is a path you name, while an upload to a fixed destination has one.

The default is therefore a decision rather than an accident, and a script that wants the safe behaviour has to say so.

dbxcli put --if-exists fail report.md /Reports/report.md

The rest of the command surface follows the same discipline. The upload command takes a local path and a remote path, in that order, and the download command takes a remote path and a local path. Shared links have their own subcommand group with the full lifecycle available, `share-link create` among them, and each of those can also be revoked or downloaded.

The important part is that these behaviours are stable and documented, because the alternative, a script that shells out to a command and has to guess what happens when the file already exists, is the kind of thing that works in a test and fails at 2am.

Three install routes, and a checksum to verify them

Installation is covered from several angles, which says something about the audience.

Homebrew is the shortest route on a Mac or a Linux box:

brew install dbxcli

WinGet covers Windows:

winget install --exact --id Dropbox.dbxcli

Release archives are the third route, and the documentation treats verification as part of the installation rather than an optional extra. The archive for your platform is downloaded from the releases page along with a `SHA256SUMS` file, and the checksum is checked before the binary is unpacked and moved onto your PATH.

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/

The release assets cover darwin, linux, openbsd and windows, on amd64, arm64 and arm, so a platform matrix is available rather than a single build.

For Go developers the module path carries the major version, so the install is:

go install github.com/dropbox/dbxcli/v3@latest

or from a clone with `git clone`, `cd dbxcli` and `go build .`.

There is also a Claude Code plugin in the repository, under `plugin/`, `skills/` and `.claude-plugin/`, which is the fourth audience in the project's own list of who this is for.

Team accounts have a writable root, and it might not be yours

There is one failure mode the documentation goes out of its way to explain, and it is worth repeating because it is the first thing a new team user hits.

On some team accounts, the Dropbox root namespace is not writable. An upload to `/remote.txt` fails, and the reason is not a permission on the file but on the root. The fix is to run `dbxcli ls /` first, find a writable location, and upload there instead, typically a personal folder or a team folder.

That is the entire troubleshooting entry for it, and it appears both in the quickstart and again in the troubleshooting section.

The proxy configuration is the other documented behaviour worth knowing, because it is the standard Go behaviour and the documentation says so plainly. `dbxcli` uses Go's standard HTTP proxy behaviour, so `HTTPS_PROXY`, `HTTP_PROXY` and `NO_PROXY` apply to the Dropbox API requests and to the OAuth token exchange and refresh requests. Lowercase forms such as `https_proxy` and `no_proxy` also work, and `NO_PROXY` is how you bypass the proxy for local or internal hosts.

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

There is a sharp edge the documentation flags without being asked. If the proxy needs basic authentication, the credentials go in the proxy URL, and the URL-encode special characters in a username or password. The warning is about where those credentials then live, in environment variables, in shell history, in CI logs and in process listings, all of which are places a secret leaks from.

And one last detail. The browser authorisation step in `dbxcli login` happens outside the CLI, in your browser, so if that page also needs a proxy, the browser or operating system proxy has to be configured separately.

Where the CLI is the wrong tool

The honest limitation is that dbxcli is a command line client for a service, and the service has a management console. Shared link administration in the CLI covers the link lifecycle, create, list, inspect, update, revoke and download. A person doing occasional administration will be faster in the console.

The second limitation is that the CLI cannot give you semantics Dropbox does not have. The conflict policy options are a genuine improvement over a naive copy, but they are a policy on top of whatever the API does, not a locking mechanism. Two clients running the same script at the same time are still a race, and the tool's job is to make the outcome predictable per request, not to serialise requests.

The alternative, and it is a real one, is to talk to the Dropbox API directly. The Go module already depends on `github.com/dropbox/dropbox-sdk-go-unofficial/v6` and `golang.org/x/oauth2`, so the pieces a program needs are the same pieces the CLI uses. The difference in approach is that a direct program can make API calls the CLI does not expose, can shape the payloads exactly as the application needs them, and can manage its own token refresh, at the cost of writing the error handling, the retries and the pagination that the CLI already handles.

For a person moving files, the CLI is better because those things are already done. For a service that needs Dropbox as a backend, the API is better, and the CLI becomes a debugging tool for it.

Editorial conclusion

dbxcli suits a team that moves files into and out of Dropbox from scripts, from CI jobs, or from an agent workflow, and who need the output of a command to be parseable rather than decorative. It is the wrong tool if you need a rich interactive browser for shared links and permissions, since the CLI covers link lifecycle operations and not the whole management console, and the wrong tool for anything that needs file locking semantics Dropbox does not offer. Check first the schema v1 documentation in `docs/json-schema/v1/`, and test the root namespace of your team account, because a team account whose `/` is not writable will fail on the simplest upload.

Frequently asked questions

Official sources

1. dropbox/dbxcli on GitHub
2. Issues
3. Project website
4. README
5. Releases