diff --git a/README.md b/README.md index 20c14d4..e14ba84 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,20 @@ -# `dbxcli`: A command line tool for Dropbox users and team admins +# `dbxcli`: Dropbox from the command line [![CI](https://github.com/dropbox/dbxcli/actions/workflows/ci.yml/badge.svg)](https://github.com/dropbox/dbxcli/actions/workflows/ci.yml) [![Go Report Card](https://goreportcard.com/badge/github.com/dropbox/dbxcli)](https://goreportcard.com/report/github.com/dropbox/dbxcli) -## 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. +`dbxcli` is a scriptable Dropbox CLI for files, shared links, teams, and +automation workflows. It is built for humans at the terminal, scripts, CI jobs, +and agent-style workflows. -## Features +## Why use dbxcli? - * File operations: `ls`, `cp`, `mkdir`, `mv`, `rm`, `put`, and `get` - * Recursive upload and download with `put -r` and `get -r` - * Pipe-friendly transfers: upload from stdin with `put -` and download to stdout with `get ... -` - * Upload conflict control with `put --if-exists overwrite|skip|fail` - * Shared-link management with `share-link create`, `list`, `info`, `update`, `revoke`, and `download` - * 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`, and `DBXCLI_AUTH_FILE` - * Team administration commands and member-scoped access with `--as-member` +* 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 @@ -30,447 +26,167 @@ dbxcli get /remote.txt ./remote.txt dbxcli share-link create /remote.txt ``` -See the [GitHub Releases](https://github.com/dropbox/dbxcli/releases) page for version-by-version changes. - -## Installation - -### Homebrew (macOS and Linux) +For automation, use structured command output and JSON help discovery: ```sh -brew install dbxcli +dbxcli ls --output=json / +dbxcli --help --output=json +dbxcli put --help --output=json ``` -### Linux +## Common workflows -Download the archive for your architecture, verify its checksum, and install. Replace `X.Y.Z` with the latest version from the [Releases](https://github.com/dropbox/dbxcli/releases) page (without the leading `v`). +Upload a file: ```sh -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/ +dbxcli put report.pdf /Reports/report.pdf ``` -For ARM systems, use `linux_arm64` or `linux_arm` instead of `linux_amd64`. - -### macOS (manual) - -If you prefer not to use Homebrew: +Upload without overwriting: ```sh -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/ +dbxcli put --if-exists fail report.md /Reports/report.md ``` -Use `darwin_amd64` for Intel Macs. - -### Windows - -Download `dbxcli_X.Y.Z_windows_amd64.zip` from the [Releases](https://github.com/dropbox/dbxcli/releases) page, extract it, and add the directory to your `PATH`. - -### Release assets - -All release archives are available at the [releases](https://github.com/dropbox/dbxcli/releases) page: - -* `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` - -### Instructions for building yourself - -1. Make sure `git` and `go` are installed. -2. Install the latest released version: - ```sh - $ go install github.com/dropbox/dbxcli@latest - ``` -3. Or build from source: - ```sh - $ 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: +Upload from a pipe: ```sh -$ dbxcli login --app-key=your-app-key +tar cz ./project | dbxcli put - /Backups/project.tgz ``` -## Usage - -`dbxcli` is largely self-documenting. Run `dbxcli -h` for a list of supported commands: +Download to stdout: ```sh -$ 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. +dbxcli get /Backups/project.tgz - | tar tz ``` -The complete generated command reference is available in [docs/commands/dbxcli.md](https://github.com/dropbox/dbxcli/blob/master/docs/commands/dbxcli.md). - -### Output formats - -Text output is the default. JSON output is available through the global `--output` flag for migrated commands and for help manifests: - -```sh -$ dbxcli ls --output=json / -$ dbxcli ls --help --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. - -```json -{ - "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`: - -```json -{ - "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](https://github.com/dropbox/dbxcli/tree/master/docs/json-schema/v1). Commands that intentionally do not support structured command-result JSON yet include `login` and `completion`, but their help is available as JSON with `--help --output=json`. Shell-completion protocol commands remain text-only. - -### Authentication - -By default, `dbxcli` stores OAuth credentials in `~/.config/dbxcli/auth.json`. -Run `dbxcli login` to authorize dbxcli and save credentials: - -```sh -$ dbxcli login -``` - -Dropbox API commands require authentication. Run `dbxcli login` to save -credentials, or provide a short-lived 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: +Create a shared link: ```sh -$ dbxcli login --app-key=your-app-key +dbxcli share-link create /Reports/report.pdf ``` -You can also set custom app keys with environment variables: +Use JSON output: ```sh -$ 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-manage +dbxcli ls --output=json / ``` -Saved 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. - -Run `dbxcli logout` to revoke saved Dropbox access tokens and remove local saved -credentials. If `DBXCLI_ACCESS_TOKEN` is set, unset it before running logout; -environment-provided tokens are not saved locally and cannot be removed by -dbxcli. - -Set `DBXCLI_AUTH_FILE` to use a different credentials file: - -```sh -$ DBXCLI_AUTH_FILE=/path/to/auth.json dbxcli login -``` - -For 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: - -```sh -$ DBXCLI_ACCESS_TOKEN=sl.xxxxxx dbxcli ls / -``` - -### Listing files - -```sh -$ 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.png -``` - -#### Time format - -By default, `ls -l`, `search -l`, and `revs -l` show relative timestamps ("3 weeks ago"). Use `--time-format` for absolute dates: - -```sh -$ 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.jpg -``` - -Use `--time=client` to display client-modified time instead of server-modified (default): - -```sh -$ dbxcli ls -l --time=client --time-format=short /Photos -``` - -#### Sorting - -Sort results with `--sort` and optionally `--reverse`: - -```sh -$ 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 -``` - -### Searching - -```sh -$ 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`. - -### Sharing +## Features -Create shared links: +* 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 +* Upload conflict control with `put --if-exists overwrite|skip|fail` +* 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` -```sh -$ 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 link -``` +## Installation -Inspect and list shared links: +### Homebrew ```sh -$ dbxcli share-link info # display shared link information -$ dbxcli share-link info --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 path +brew install dbxcli ``` -Download shared links: +### Release archives -```sh -$ dbxcli share-link download [target] # download a shared-link file -$ dbxcli share-link download --path /nested/file.txt # download a file inside a folder shared link -$ dbxcli share-link download ./local.txt --path /nested/file.txt # download nested file to a local target -$ dbxcli share-link download [target] --recursive # download a folder shared link -``` +Download the archive for your platform from the +[releases](https://github.com/dropbox/dbxcli/releases) page, verify its +checksum, and install the `dbxcli` binary somewhere on your `PATH`. -Update shared links: +Linux example: ```sh -$ dbxcli share-link update --allow-download # update shared link settings -$ dbxcli share-link update --disallow-download # disable downloads from a shared link -$ dbxcli share-link update --audience public # update shared link audience -$ dbxcli share-link update --expires 2026-07-01T00:00:00Z # update shared link expiration -$ dbxcli share-link update --remove-expiration # remove shared link expiration -$ dbxcli share-link update --password-prompt # set or change a shared link password -$ dbxcli share-link update --remove-password # remove a shared link password +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/ ``` -Revoke shared links: +Release assets include: -```sh -$ dbxcli share-link revoke # revoke a shared link -$ dbxcli share-link revoke --path /file.txt # revoke direct shared links for a path -``` +* `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` -Compatibility and shared folders: +### Build from source ```sh -$ dbxcli share list link # deprecated compatibility command -$ dbxcli share list folder # list shared folders +go install github.com/dropbox/dbxcli@latest ``` -`share-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 `, `--password-prompt`, and `--password-file ` 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. - -### Team management +Or build from a clone: ```sh -$ 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. +git clone https://github.com/dropbox/dbxcli.git +cd dbxcli +go build . ``` -The `--verbose` option will turn on verbose logging and is useful for debugging. - -### Uploading files and directories +## Support posture -```sh -$ 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 exists -``` +`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. -By 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. +## Command reference -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: +The complete generated command reference is available here: -```sh -$ dbxcli put -w 1 -c 134217728 large.zip /backup/large.zip -``` +* [dbxcli command reference](https://github.com/dropbox/dbxcli/blob/master/docs/commands/dbxcli.md) -### Downloading files and directories +For command-specific help, run: ```sh -$ dbxcli get /remote/file.txt ./local-file.txt # download a single file -$ dbxcli get -r /remote/folder ./local-folder # recursively download a folder +dbxcli --help +dbxcli put --help +dbxcli share-link --help +dbxcli share-link create --help ``` -### Piping with stdin/stdout - -Use `-` as the local operand to stream through pipes: +For machine-readable command discovery, use JSON help: ```sh -$ 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 file +dbxcli --help --output=json +dbxcli put --help --output=json ``` -Stdin 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. +## Deeper documentation -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 `./-`. +* [Automation and JSON output](https://github.com/dropbox/dbxcli/blob/master/docs/automation.md) +* [Sharing workflows](https://github.com/dropbox/dbxcli/blob/master/docs/sharing.md) +* [JSON schema v1](https://github.com/dropbox/dbxcli/blob/master/docs/json-schema/v1/README.md) +* [Release history](https://github.com/dropbox/dbxcli/blob/master/CHANGELOG.md) -### Removing files and folders - -```sh -$ 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 -``` - -### Creating directories - -```sh -$ dbxcli mkdir /projects/2026/reports # creates all intermediate directories -$ dbxcli mkdir -p /projects/2026/reports # no error if directory already exists -``` +Generated Cobra command docs live under `docs/commands/` and are kept close to +the actual CLI by `go run ./tools/gen-docs`. ## Contributing - * If you're submitting a non-trivial change, please fill out the [Dropbox Contributor License Agreement](https://opensource.dropbox.com/cla/) first. - * Open a [pull request](https://help.github.com/articles/using-pull-requests/) with a clear description of the change. - * Include tests or manual validation details when relevant. - -## Useful Resources +* If you are submitting a non-trivial change, please fill out the + [Dropbox Contributor License Agreement](https://opensource.dropbox.com/cla/) + first. +* Open a [pull request](https://help.github.com/articles/using-pull-requests/) + with a clear description of the change. +* Include tests or manual validation details when relevant. + +## Useful resources * [Go SDK documentation](https://pkg.go.dev/github.com/dropbox/dropbox-sdk-go-unofficial) -* [API documentation](https://www.dropbox.com/developers/documentation/http/documentation) +* [Dropbox API documentation](https://www.dropbox.com/developers/documentation/http/documentation) diff --git a/docs/automation.md b/docs/automation.md new file mode 100644 index 0000000..fb58ef6 --- /dev/null +++ b/docs/automation.md @@ -0,0 +1,176 @@ +# Automation and JSON output + +`dbxcli` supports text output for humans, structured JSON command output for +scripts, and JSON help for machine-readable command discovery. + +Command results and JSON errors are written to stdout. Status, progress, +human-facing warnings, diagnostics, and verbose logs are written to stderr. + +## JSON command output + +Text output is the default. JSON command output is available through the global +`--output` flag for commands that support structured execution output: + +```sh +dbxcli ls --output=json / +dbxcli account --output=json +dbxcli logout --output=json +``` + +Use JSON help to discover whether a command supports structured command output: + +```sh +dbxcli put --help --output=json +``` + +Successful JSON responses use a stable envelope: + +```json +{ + "ok": true, + "schema_version": "1", + "command": "ls", + "input": { + "path": "/Reports" + }, + "results": [ + { + "status": "listed", + "kind": "file", + "input": {}, + "result": { + "type": "file", + "path_display": "/Reports/q1.pdf", + "path_lower": "/reports/q1.pdf" + } + } + ], + "warnings": [] +} +``` + +In JSON mode, error responses are written to stdout and the process exits with +a non-zero status: + +```json +{ + "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 +[json-schema/v1](json-schema/v1/README.md). + +## JSON help manifest + +JSON help is the machine-readable command discovery surface. It is separate +from command execution output, does not require Dropbox auth, and works even for +commands that do not support structured command execution output. + +```sh +dbxcli --help --output=json +dbxcli put --help --output=json +dbxcli share-link create --help --output=json +dbxcli --output=json help share-link create +``` + +Use JSON help to discover command paths, flags, aliases, known auth modes, known +destructive levels, and whether normal structured command output is supported. + +## Safe scripting patterns + +Prefer flags that make automation outcomes explicit: + +```sh +dbxcli put --if-exists fail report.md /Reports/report.md +dbxcli put --if-exists skip report.md /Reports/report.md --output=json +dbxcli rm /Reports/old-report.md --output=json +``` + +Use `--output=json` when the caller needs stable statuses, result kinds, +warnings, or error codes. Use text output when a command is part of a human +terminal workflow or when the command intentionally writes file bytes to stdout. + +## Authentication for automation + +By default, `dbxcli` stores OAuth credentials in: + +```text +~/.config/dbxcli/auth.json +``` + +Use `dbxcli login` to save refreshable credentials: + +```sh +dbxcli login +``` + +Use `DBXCLI_ACCESS_TOKEN` for automation with short-lived Dropbox access tokens: + +```sh +DBXCLI_ACCESS_TOKEN=sl.xxxxxx dbxcli ls --output=json / +``` + +This token is used directly and is not saved or refreshed. If it expires, the +command fails and you must provide a fresh token. + +Set `DBXCLI_AUTH_FILE` to use a different saved credentials file: + +```sh +DBXCLI_AUTH_FILE=/path/to/auth.json dbxcli login +DBXCLI_AUTH_FILE=/path/to/auth.json dbxcli ls / +``` + +`dbxcli logout` revokes saved Dropbox tokens and removes local saved +credentials. If `DBXCLI_ACCESS_TOKEN` is set, unset it before running logout; +environment-provided tokens are not saved locally and cannot be removed by +dbxcli. + +## Stdin and stdout + +Use `-` as the local operand to stream through pipes: + +```sh +printf 'hello' | dbxcli put - /hello.txt +tar cz ./src | dbxcli put - /backups/src.tgz +dbxcli get /backups/src.tgz - | tar tz +dbxcli get /file.txt - > local-copy.txt +``` + +Stdin 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: progress, +diagnostic output, human-facing warnings, and verbose logs go 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 `./-`. + +## Exit status + +Current behavior: + +* `0` means success. +* Non-zero means failure. +* In JSON mode, inspect `error.code` for stable machine handling. + +Specific error-code-to-exit-code mapping is planned as a future automation +milestone. + +## Shell completion + +Shell completion commands intentionally remain text-only because shells expect +completion scripts or protocol output: + +```sh +dbxcli completion bash +dbxcli completion zsh +dbxcli completion fish +dbxcli completion powershell +``` diff --git a/docs/commands/dbxcli.md b/docs/commands/dbxcli.md index eea78d4..7900b55 100644 --- a/docs/commands/dbxcli.md +++ b/docs/commands/dbxcli.md @@ -18,6 +18,12 @@ manage your team and more. It is easy, scriptable and works on all platforms! -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: no +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli account](dbxcli_account.md) - Display account information diff --git a/docs/commands/dbxcli_account.md b/docs/commands/dbxcli_account.md index 7f3c402..7475328 100644 --- a/docs/commands/dbxcli_account.md +++ b/docs/commands/dbxcli_account.md @@ -29,6 +29,12 @@ dbxcli account [flags] [] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli](dbxcli.md) - A command line tool for Dropbox users and team admins diff --git a/docs/commands/dbxcli_completion.md b/docs/commands/dbxcli_completion.md index a651d84..db935a4 100644 --- a/docs/commands/dbxcli_completion.md +++ b/docs/commands/dbxcli_completion.md @@ -28,6 +28,12 @@ dbxcli completion [bash|zsh|fish|powershell] [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: no +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli](dbxcli.md) - A command line tool for Dropbox users and team admins diff --git a/docs/commands/dbxcli_completion_bash.md b/docs/commands/dbxcli_completion_bash.md index 95a54d0..379f62b 100644 --- a/docs/commands/dbxcli_completion_bash.md +++ b/docs/commands/dbxcli_completion_bash.md @@ -47,6 +47,12 @@ dbxcli completion bash -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: no +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli completion](dbxcli_completion.md) - Generate the autocompletion script for the specified shell diff --git a/docs/commands/dbxcli_completion_fish.md b/docs/commands/dbxcli_completion_fish.md index 1063915..9e5971b 100644 --- a/docs/commands/dbxcli_completion_fish.md +++ b/docs/commands/dbxcli_completion_fish.md @@ -38,6 +38,12 @@ dbxcli completion fish [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: no +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli completion](dbxcli_completion.md) - Generate the autocompletion script for the specified shell diff --git a/docs/commands/dbxcli_completion_powershell.md b/docs/commands/dbxcli_completion_powershell.md index ff0b5c2..8047c55 100644 --- a/docs/commands/dbxcli_completion_powershell.md +++ b/docs/commands/dbxcli_completion_powershell.md @@ -35,6 +35,12 @@ dbxcli completion powershell [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: no +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli completion](dbxcli_completion.md) - Generate the autocompletion script for the specified shell diff --git a/docs/commands/dbxcli_completion_zsh.md b/docs/commands/dbxcli_completion_zsh.md index 716e400..fa74cb3 100644 --- a/docs/commands/dbxcli_completion_zsh.md +++ b/docs/commands/dbxcli_completion_zsh.md @@ -49,6 +49,12 @@ dbxcli completion zsh [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: no +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli completion](dbxcli_completion.md) - Generate the autocompletion script for the specified shell diff --git a/docs/commands/dbxcli_cp.md b/docs/commands/dbxcli_cp.md index 5f37acc..841d6d3 100644 --- a/docs/commands/dbxcli_cp.md +++ b/docs/commands/dbxcli_cp.md @@ -22,6 +22,12 @@ dbxcli cp [flags] [more sources] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli](dbxcli.md) - A command line tool for Dropbox users and team admins diff --git a/docs/commands/dbxcli_du.md b/docs/commands/dbxcli_du.md index e1b80b3..ff5bff5 100644 --- a/docs/commands/dbxcli_du.md +++ b/docs/commands/dbxcli_du.md @@ -22,6 +22,12 @@ dbxcli du [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli](dbxcli.md) - A command line tool for Dropbox users and team admins diff --git a/docs/commands/dbxcli_get.md b/docs/commands/dbxcli_get.md index aeff3db..c195e70 100644 --- a/docs/commands/dbxcli_get.md +++ b/docs/commands/dbxcli_get.md @@ -40,6 +40,13 @@ dbxcli get [flags] [] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes +* Stdin/stdout behavior: Use `-` as the local target to write downloaded file bytes to stdout; diagnostics go to stderr. + + ### SEE ALSO * [dbxcli](dbxcli.md) - A command line tool for Dropbox users and team admins diff --git a/docs/commands/dbxcli_login.md b/docs/commands/dbxcli_login.md index c98966c..0d96562 100644 --- a/docs/commands/dbxcli_login.md +++ b/docs/commands/dbxcli_login.md @@ -30,6 +30,12 @@ dbxcli login [personal|team-access|team-manage] [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: no +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli](dbxcli.md) - A command line tool for Dropbox users and team admins diff --git a/docs/commands/dbxcli_logout.md b/docs/commands/dbxcli_logout.md index e4d7f25..5cd11ef 100644 --- a/docs/commands/dbxcli_logout.md +++ b/docs/commands/dbxcli_logout.md @@ -31,6 +31,12 @@ dbxcli logout [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli](dbxcli.md) - A command line tool for Dropbox users and team admins diff --git a/docs/commands/dbxcli_ls.md b/docs/commands/dbxcli_ls.md index 3152ab0..23d02be 100644 --- a/docs/commands/dbxcli_ls.md +++ b/docs/commands/dbxcli_ls.md @@ -39,6 +39,12 @@ dbxcli ls [flags] [] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli](dbxcli.md) - A command line tool for Dropbox users and team admins diff --git a/docs/commands/dbxcli_mkdir.md b/docs/commands/dbxcli_mkdir.md index 6023f4a..6e35852 100644 --- a/docs/commands/dbxcli_mkdir.md +++ b/docs/commands/dbxcli_mkdir.md @@ -23,6 +23,12 @@ dbxcli mkdir [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli](dbxcli.md) - A command line tool for Dropbox users and team admins diff --git a/docs/commands/dbxcli_mv.md b/docs/commands/dbxcli_mv.md index d0b307c..e3e737f 100644 --- a/docs/commands/dbxcli_mv.md +++ b/docs/commands/dbxcli_mv.md @@ -22,6 +22,12 @@ dbxcli mv [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli](dbxcli.md) - A command line tool for Dropbox users and team admins diff --git a/docs/commands/dbxcli_put.md b/docs/commands/dbxcli_put.md index 5df0abf..6ecca38 100644 --- a/docs/commands/dbxcli_put.md +++ b/docs/commands/dbxcli_put.md @@ -50,6 +50,13 @@ dbxcli put [flags] [] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes +* Stdin/stdout behavior: Use `-` as the local source to upload from stdin; stdin is spooled to a temporary file before upload. + + ### SEE ALSO * [dbxcli](dbxcli.md) - A command line tool for Dropbox users and team admins diff --git a/docs/commands/dbxcli_restore.md b/docs/commands/dbxcli_restore.md index 9b73abf..dd32a90 100644 --- a/docs/commands/dbxcli_restore.md +++ b/docs/commands/dbxcli_restore.md @@ -36,6 +36,12 @@ dbxcli restore [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli](dbxcli.md) - A command line tool for Dropbox users and team admins diff --git a/docs/commands/dbxcli_revs.md b/docs/commands/dbxcli_revs.md index 1e3056c..e021910 100644 --- a/docs/commands/dbxcli_revs.md +++ b/docs/commands/dbxcli_revs.md @@ -25,6 +25,12 @@ dbxcli revs [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli](dbxcli.md) - A command line tool for Dropbox users and team admins diff --git a/docs/commands/dbxcli_rm.md b/docs/commands/dbxcli_rm.md index 33e9577..2ba7d93 100644 --- a/docs/commands/dbxcli_rm.md +++ b/docs/commands/dbxcli_rm.md @@ -25,6 +25,13 @@ dbxcli rm [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes +* Destructive behavior: `delete` + + ### SEE ALSO * [dbxcli](dbxcli.md) - A command line tool for Dropbox users and team admins diff --git a/docs/commands/dbxcli_search.md b/docs/commands/dbxcli_search.md index b0f0fda..31d2c8c 100644 --- a/docs/commands/dbxcli_search.md +++ b/docs/commands/dbxcli_search.md @@ -27,6 +27,12 @@ dbxcli search [flags] [path-scope] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli](dbxcli.md) - A command line tool for Dropbox users and team admins diff --git a/docs/commands/dbxcli_share-link.md b/docs/commands/dbxcli_share-link.md index 5fbd31e..fa95286 100644 --- a/docs/commands/dbxcli_share-link.md +++ b/docs/commands/dbxcli_share-link.md @@ -22,6 +22,12 @@ Create, list, inspect, download, update, and revoke Dropbox shared links. -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: no +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli](dbxcli.md) - A command line tool for Dropbox users and team admins diff --git a/docs/commands/dbxcli_share-link_create.md b/docs/commands/dbxcli_share-link_create.md index 7ba3658..25fa902 100644 --- a/docs/commands/dbxcli_share-link_create.md +++ b/docs/commands/dbxcli_share-link_create.md @@ -47,6 +47,12 @@ dbxcli share-link create [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli share-link](dbxcli_share-link.md) - Shared link commands diff --git a/docs/commands/dbxcli_share-link_download.md b/docs/commands/dbxcli_share-link_download.md index 1f758dc..38e855c 100644 --- a/docs/commands/dbxcli_share-link_download.md +++ b/docs/commands/dbxcli_share-link_download.md @@ -46,6 +46,13 @@ dbxcli share-link download [target] [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes +* Stdin/stdout behavior: Use `-` as the target for file shared links to write bytes to stdout; folder shared links require `--recursive` and cannot be written to stdout. + + ### SEE ALSO * [dbxcli share-link](dbxcli_share-link.md) - Shared link commands diff --git a/docs/commands/dbxcli_share-link_info.md b/docs/commands/dbxcli_share-link_info.md index e9ece49..2f6a0a8 100644 --- a/docs/commands/dbxcli_share-link_info.md +++ b/docs/commands/dbxcli_share-link_info.md @@ -38,6 +38,12 @@ dbxcli share-link info [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli share-link](dbxcli_share-link.md) - Shared link commands diff --git a/docs/commands/dbxcli_share-link_list.md b/docs/commands/dbxcli_share-link_list.md index 788f9dc..d765a3e 100644 --- a/docs/commands/dbxcli_share-link_list.md +++ b/docs/commands/dbxcli_share-link_list.md @@ -34,6 +34,12 @@ dbxcli share-link list [path] [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli share-link](dbxcli_share-link.md) - Shared link commands diff --git a/docs/commands/dbxcli_share-link_revoke.md b/docs/commands/dbxcli_share-link_revoke.md index 0fec1b0..7a5a500 100644 --- a/docs/commands/dbxcli_share-link_revoke.md +++ b/docs/commands/dbxcli_share-link_revoke.md @@ -34,6 +34,12 @@ dbxcli share-link revoke [url] [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli share-link](dbxcli_share-link.md) - Shared link commands diff --git a/docs/commands/dbxcli_share-link_update.md b/docs/commands/dbxcli_share-link_update.md index dd70836..1c60839 100644 --- a/docs/commands/dbxcli_share-link_update.md +++ b/docs/commands/dbxcli_share-link_update.md @@ -46,6 +46,12 @@ dbxcli share-link update [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli share-link](dbxcli_share-link.md) - Shared link commands diff --git a/docs/commands/dbxcli_share.md b/docs/commands/dbxcli_share.md index e482874..a0aabfc 100644 --- a/docs/commands/dbxcli_share.md +++ b/docs/commands/dbxcli_share.md @@ -18,6 +18,12 @@ Sharing commands -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: no +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli](dbxcli.md) - A command line tool for Dropbox users and team admins diff --git a/docs/commands/dbxcli_share_list.md b/docs/commands/dbxcli_share_list.md index 19d05b6..bf948ea 100644 --- a/docs/commands/dbxcli_share_list.md +++ b/docs/commands/dbxcli_share_list.md @@ -18,6 +18,12 @@ List shared things -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: no +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli share](dbxcli_share.md) - Sharing commands diff --git a/docs/commands/dbxcli_share_list_folder.md b/docs/commands/dbxcli_share_list_folder.md index bd6563f..17c56ef 100644 --- a/docs/commands/dbxcli_share_list_folder.md +++ b/docs/commands/dbxcli_share_list_folder.md @@ -22,6 +22,12 @@ dbxcli share list folder [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli share list](dbxcli_share_list.md) - List shared things diff --git a/docs/commands/dbxcli_team.md b/docs/commands/dbxcli_team.md index 9f2280e..5b4456d 100644 --- a/docs/commands/dbxcli_team.md +++ b/docs/commands/dbxcli_team.md @@ -18,6 +18,12 @@ Team management commands -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: no +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli](dbxcli.md) - A command line tool for Dropbox users and team admins diff --git a/docs/commands/dbxcli_team_add-member.md b/docs/commands/dbxcli_team_add-member.md index b451e3f..df75cca 100644 --- a/docs/commands/dbxcli_team_add-member.md +++ b/docs/commands/dbxcli_team_add-member.md @@ -22,6 +22,13 @@ dbxcli team add-member [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes +* Destructive behavior: `admin` + + ### SEE ALSO * [dbxcli team](dbxcli_team.md) - Team management commands diff --git a/docs/commands/dbxcli_team_info.md b/docs/commands/dbxcli_team_info.md index 11c731c..7c8ba3f 100644 --- a/docs/commands/dbxcli_team_info.md +++ b/docs/commands/dbxcli_team_info.md @@ -22,6 +22,12 @@ dbxcli team info [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli team](dbxcli_team.md) - Team management commands diff --git a/docs/commands/dbxcli_team_list-groups.md b/docs/commands/dbxcli_team_list-groups.md index f07f63a..13c174b 100644 --- a/docs/commands/dbxcli_team_list-groups.md +++ b/docs/commands/dbxcli_team_list-groups.md @@ -22,6 +22,12 @@ dbxcli team list-groups [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli team](dbxcli_team.md) - Team management commands diff --git a/docs/commands/dbxcli_team_list-members.md b/docs/commands/dbxcli_team_list-members.md index 55d412e..a1cf6c6 100644 --- a/docs/commands/dbxcli_team_list-members.md +++ b/docs/commands/dbxcli_team_list-members.md @@ -22,6 +22,12 @@ dbxcli team list-members [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli team](dbxcli_team.md) - Team management commands diff --git a/docs/commands/dbxcli_team_remove-member.md b/docs/commands/dbxcli_team_remove-member.md index ff780fd..d36c98f 100644 --- a/docs/commands/dbxcli_team_remove-member.md +++ b/docs/commands/dbxcli_team_remove-member.md @@ -22,6 +22,13 @@ dbxcli team remove-member [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes +* Destructive behavior: `admin` + + ### SEE ALSO * [dbxcli team](dbxcli_team.md) - Team management commands diff --git a/docs/commands/dbxcli_version.md b/docs/commands/dbxcli_version.md index 90d75cc..6df3328 100644 --- a/docs/commands/dbxcli_version.md +++ b/docs/commands/dbxcli_version.md @@ -22,6 +22,12 @@ dbxcli version [flags] -v, --verbose Enable verbose logging ``` +### Command metadata + +* Structured JSON output: yes +* JSON help manifest: yes + + ### SEE ALSO * [dbxcli](dbxcli.md) - A command line tool for Dropbox users and team admins diff --git a/docs/sharing.md b/docs/sharing.md new file mode 100644 index 0000000..364af76 --- /dev/null +++ b/docs/sharing.md @@ -0,0 +1,127 @@ +# Sharing workflows + +`dbxcli share-link` manages Dropbox shared links for files, folders, and nested +paths inside folder shared links. + +## Output contract + +Text output is the default. With `--output=json`, shared-link commands use the +standard JSON envelope with `ok`, `schema_version`, `command`, `input`, +`results`, and `warnings`. Result statuses include `created`, `existing`, +`listed`, `found`, `updated`, `revoked`, and `downloaded`. Result kinds use the +link or target type, such as `file`, `folder`, or `shared_link`. + +In text mode, `share-link create` prints only the shared-link URL to stdout. +Status, warnings, diagnostics, and verbose logs go to stderr. + +```sh +url="$(dbxcli share-link create /file.txt)" +``` + +For automation: + +```sh +dbxcli share-link create /file.txt --output=json +dbxcli share-link list /file.txt --output=json +``` + +## Create shared links + +```sh +dbxcli share-link create /file.txt +dbxcli share-link create /file.txt --access viewer +dbxcli share-link create /file.txt --audience team +dbxcli share-link create /file.txt --allow-download +dbxcli share-link create /file.txt --disallow-download +dbxcli share-link create /file.txt --expires 2026-07-01T00:00:00Z +dbxcli share-link create /file.txt --password-prompt +dbxcli share-link create /file.txt --remove-expiration +``` + +`share-link create` creates a new shared link or returns the existing direct +shared link for the path. + +When `share-link create` returns an existing link, `--remove-expiration` +removes the expiration from that existing link. + +`share-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` supports `public`, `team`, `members`, and +`no-one`. Dropbox team and folder policies can still resolve the effective +audience differently. + +## Inspect and list shared links + +```sh +dbxcli share-link info +dbxcli share-link info --path nested/file.txt +dbxcli share-link list +dbxcli share-link list /file.txt +``` + +`share-link list /file.txt` lists direct shared links for that path, not +parent-folder links. + +## Update shared links + +```sh +dbxcli share-link update --allow-download +dbxcli share-link update --disallow-download +dbxcli share-link update --audience public +dbxcli share-link update --expires 2026-07-01T00:00:00Z +dbxcli share-link update --remove-expiration +dbxcli share-link update --password-prompt +dbxcli share-link update --remove-password +``` + +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/`. + +## Revoke shared links + +```sh +dbxcli share-link revoke +dbxcli share-link revoke --path /file.txt +``` + +Revoking a file's direct shared link does not revoke links to parent folders +that may still expose the file. + +## Download shared links + +```sh +dbxcli share-link download [target] +dbxcli share-link download --path nested/file.txt +dbxcli share-link download ./local.txt --path nested/file.txt +dbxcli share-link download [target] --recursive +``` + +`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. + +## Password-protected links + +`share-link create`, `share-link update`, `share-link info`, and +`share-link download` support `--password `, `--password-prompt`, and +`--password-file ` for password-protected links. Use `--password-prompt` +for interactive use so the password is not echoed. + +Avoid `--password ` in shared shells because it may be saved in shell +history. Prefer `--password-prompt` for interactive use or `--password-file` +for automation. + +## Compatibility commands + +Older sharing commands remain available for compatibility: + +```sh +dbxcli share list link +dbxcli share list folder +``` + +Prefer `share-link` commands for shared-link workflows. diff --git a/tools/gen-docs/main.go b/tools/gen-docs/main.go index 8c9b09b..aa0f9dd 100644 --- a/tools/gen-docs/main.go +++ b/tools/gen-docs/main.go @@ -15,9 +15,12 @@ package main import ( + "bytes" "fmt" "os" "path/filepath" + "sort" + "strings" "github.com/dropbox/dbxcli/cmd" "github.com/spf13/cobra" @@ -26,6 +29,18 @@ import ( const outputDir = "docs/commands" +const ( + structuredOutputSupportedAnnotation = "dbxcli.supportsStructuredOutput" + commandDestructiveLevelAnnotation = "dbxcli.destructiveLevel" + destructiveLevelNone = "none" +) + +var stdinStdoutNotes = map[string]string{ + "get": "Use `-` as the local target to write downloaded file bytes to stdout; diagnostics go to stderr.", + "put": "Use `-` as the local source to upload from stdin; stdin is spooled to a temporary file before upload.", + "share-link download": "Use `-` as the target for file shared links to write bytes to stdout; folder shared links require `--recursive` and cannot be written to stdout.", +} + func main() { if err := run(); err != nil { fmt.Fprintln(os.Stderr, err) @@ -60,6 +75,9 @@ func run() error { if err := doc.GenMarkdownTreeCustom(root, outputDir, prepender, linkHandler); err != nil { return fmt.Errorf("generate command docs: %w", err) } + if err := addCommandMetadata(root); err != nil { + return err + } return nil } @@ -69,3 +87,134 @@ func disableAutoGenTag(command *cobra.Command) { disableAutoGenTag(child) } } + +func addCommandMetadata(root *cobra.Command) error { + return walkCommands(root, func(command *cobra.Command) error { + path := filepath.Join(outputDir, strings.ReplaceAll(command.CommandPath(), " ", "_")+".md") + contents, err := os.ReadFile(path) + if err != nil { + return fmt.Errorf("read generated doc %s: %w", path, err) + } + + updated := insertMetadataSection(contents, commandMetadataSection(command)) + if err := os.WriteFile(path, updated, 0o644); err != nil { + return fmt.Errorf("write generated doc %s: %w", path, err) + } + return nil + }) +} + +func walkCommands(command *cobra.Command, fn func(*cobra.Command) error) error { + if !command.IsAvailableCommand() || command.IsAdditionalHelpTopicCommand() { + return nil + } + if err := fn(command); err != nil { + return err + } + + children := append([]*cobra.Command{}, command.Commands()...) + sort.Slice(children, func(i, j int) bool { + return children[i].Name() < children[j].Name() + }) + for _, child := range children { + if err := walkCommands(child, fn); err != nil { + return err + } + } + return nil +} + +func insertMetadataSection(contents []byte, section []byte) []byte { + marker := []byte("\n### SEE ALSO\n\n") + index := bytes.Index(contents, marker) + if index == -1 { + return append(append(contents, '\n'), section...) + } + + result := make([]byte, 0, len(contents)+len(section)+1) + result = append(result, contents[:index]...) + result = append(result, '\n') + result = append(result, section...) + result = append(result, contents[index:]...) + return result +} + +func commandMetadataSection(command *cobra.Command) []byte { + var buf bytes.Buffer + buf.WriteString("### Command metadata\n\n") + buf.WriteString(fmt.Sprintf("* Structured JSON output: %s\n", yesNo(commandSupportsStructuredOutput(command)))) + buf.WriteString("* JSON help manifest: yes\n") + + if aliases := sortedAliases(command); len(aliases) > 0 { + buf.WriteString("* Aliases: ") + for i, alias := range aliases { + if i > 0 { + buf.WriteString(", ") + } + buf.WriteString("`" + alias + "`") + } + buf.WriteString("\n") + } + + if note, ok := stdinStdoutNotes[relativeCommandPath(command)]; ok { + buf.WriteString("* Stdin/stdout behavior: " + note + "\n") + } + + if level := commandDestructiveLevel(command); level != destructiveLevelNone { + buf.WriteString("* Destructive behavior: `" + level + "`\n") + } + + buf.WriteString("\n") + return buf.Bytes() +} + +func commandSupportsStructuredOutput(command *cobra.Command) bool { + return command != nil && command.Annotations[structuredOutputSupportedAnnotation] == "true" +} + +func commandDestructiveLevel(command *cobra.Command) string { + if command == nil || command.Annotations == nil { + return destructiveLevelNone + } + level := strings.TrimSpace(command.Annotations[commandDestructiveLevelAnnotation]) + if level == "" { + return destructiveLevelNone + } + parts := strings.Split(level, ",") + level = strings.TrimSpace(parts[0]) + if level == "" { + return destructiveLevelNone + } + return level +} + +func sortedAliases(command *cobra.Command) []string { + if command == nil || len(command.Aliases) == 0 { + return nil + } + aliases := append([]string{}, command.Aliases...) + sort.Strings(aliases) + return aliases +} + +func relativeCommandPath(command *cobra.Command) string { + if command == nil { + return "" + } + path := command.CommandPath() + if command.Root() != nil { + rootName := command.Root().Name() + if path == rootName { + return path + } + return strings.TrimPrefix(path, rootName+" ") + } + return path +} + +func yesNo(value bool) string { + if value { + return "yes" + } + return "no" +}