Merge pull request #316 from dropbox/feat/docs-refresh

Update docs, root command description, and add Dependabot

Author: AndreyVMarkelov

.github/dependabot.yml

@@ -0,0 +1,43 @@
+version: 2
+updates:
+  - package-ecosystem: gomod
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "09:00"
+      timezone: America/Los_Angeles
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - go
+    commit-message:
+      prefix: deps
+    groups:
+      go-dependencies:
+        patterns:
+          - "*"
+        update-types:
+          - minor
+          - patch
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "09:00"
+      timezone: America/Los_Angeles
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - github-actions
+    commit-message:
+      prefix: deps
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+        update-types:
+          - minor
+          - patch

CHANGELOG.md

@@ -4,6 +4,22 @@
 
 [Full Changelog](https://github.com/dropbox/dbxcli/compare/v3.5.1...HEAD)
 
+**Added:**
+
+- Added Dependabot configuration for Go modules and GitHub Actions dependencies.
+- Added automation documentation with CI, direct-token, saved-auth-file, and JSON error-handling examples.
+- Added richer JSON `error.details` fields for operation context, paths, URLs, revisions, email addresses, member IDs, Dropbox API summaries, and retry-after values.
+
+**Changed:**
+
+- Updated root command help and generated command docs to reflect current files, shared-link, team, and automation workflows.
+
+**Infrastructure:**
+
+- Added golden JSON error output fixtures and live JSON error envelope tests.
+- Hardened JSON error detail collection through wrapped and joined errors.
+- Reduced false-positive Dropbox `api_summary` detection for local path errors.
+
 ## [v3.5.1](https://github.com/dropbox/dbxcli/tree/v3.5.1) (2026-06-28)
 [Full Changelog](https://github.com/dropbox/dbxcli/compare/v3.5.0...v3.5.1)
 

README.md

@@ -4,7 +4,7 @@
 [![Go Report Card](https://goreportcard.com/badge/github.com/dropbox/dbxcli/v3?cache=v3)](https://goreportcard.com/report/github.com/dropbox/dbxcli/v3)
 
 `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,
+automation workflows. It is built for humans in the terminal, scripts, CI jobs,
 and agent-style workflows.
 
 ## Why use dbxcli?
@@ -26,6 +26,9 @@ 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:
 
 ```sh
@@ -37,14 +40,19 @@ dbxcli put --help --output=json
 Stable JSON error codes and process exit codes are documented in
 [Automation and JSON output](https://github.com/dropbox/dbxcli/blob/master/docs/automation.md).
 
-## JSON contract stability
+## JSON output
+
+`--output=json` emits stable schema v1 success and error envelopes for
+automation. Use JSON help for machine-readable command manifests:
+
+```sh
+dbxcli --help --output=json
+dbxcli put --help --output=json
+```
 
-`--output=json` uses schema v1 success and error envelopes. Schema v1 keeps
-top-level fields, stable error codes, and result status meanings stable within
-the v1 contract; minor releases may add fields, commands, warnings, and error
-details. Use JSON help for machine-readable command manifests, and use the
+See the
 [JSON schema v1 docs](https://github.com/dropbox/dbxcli/blob/master/docs/json-schema/v1/README.md)
-for schemas, command contracts, and examples.
+for schemas, stability policy, command contracts, and examples.
 
 ## Common workflows
 
@@ -116,6 +124,8 @@ folder or a team folder.
 brew install dbxcli
 ```
 
+Homebrew formula: [formulae.brew.sh/formula/dbxcli](https://formulae.brew.sh/formula/dbxcli)
+
 ### Release archives
 
 Download the archive for your platform from the

cmd/help_json_test.go

@@ -886,7 +886,7 @@ func newJSONHelpTestRoot(t *testing.T) *cobra.Command {
 
 	root := &cobra.Command{
 		Use:               "dbxcli",
-		Short:             "A command line tool for Dropbox users and team admins",
+		Short:             "Scriptable Dropbox CLI for files, shared links, teams, and automation",
 		SilenceUsage:      true,
 		SilenceErrors:     true,
 		PersistentPreRunE: initDbx,

cmd/root.go

@@ -227,9 +227,11 @@ func rootNamespaceID(account *users.FullAccount) string {
 // RootCmd represents the base command when called without any subcommands
 var RootCmd = &cobra.Command{
 	Use:   "dbxcli",
-	Short: "A command line tool for Dropbox users and team admins",
-	Long: `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!`,
+	Short: "Scriptable Dropbox CLI for files, shared links, teams, and automation",
+	Long: `Use dbxcli to work with Dropbox files, folders, shared links, and team
+workflows from a terminal. It supports text output for humans, structured JSON
+output for automation, pipe-friendly transfers, refreshable OAuth login, and
+direct-token automation for scripts, CI jobs, and agent-style workflows.`,
 	SilenceUsage:      true,
 	SilenceErrors:     true,
 	PersistentPreRunE: initDbx,

docs/automation.md

@@ -23,11 +23,11 @@ Use JSON help to discover whether a command supports structured command output:
 dbxcli put --help --output=json
 ```
 
-JSON help is also the Command Manifest v1 surface for tools and agents. Each
-command manifest includes structured positional arguments, flag enum values and
-conflicts, prompt/sensitive-input metadata, examples, auth modes, best-effort
-Dropbox scopes, stdin/stdout behavior, schema refs, result statuses/kinds, and
-known warning codes.
+JSON help is also the Command Manifest v1 surface for tools and agents. Command
+manifests expose machine-readable metadata such as structured positional
+arguments, flag enum values and conflicts, prompt/sensitive-input metadata,
+examples, auth modes, best-effort Dropbox scopes, stdin/stdout behavior, schema
+refs, result statuses/kinds, and known warning codes when available.
 
 Successful JSON responses use a stable envelope:
 
@@ -88,7 +88,7 @@ Automation should treat the CLI and schemas as the stable interface:
 * Use `error.schema.json` to validate JSON error responses.
 * Prefer schema URLs from a pinned release tag when reproducibility matters.
 
-dbxcli intentionally does not expose a separate machine protocol. Tools should
+dbxcli currently does not expose a separate machine protocol. Tools should
 invoke the CLI, read stdout as JSON in `--output=json` mode, and treat stderr as
 status, progress, warnings, diagnostics, and verbose logs.
 
@@ -130,6 +130,60 @@ 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.
 
+Check auth and identity before running a job:
+
+```sh
+dbxcli account --output=json
+```
+
+Use direct token auth for short-lived CI jobs:
+
+```sh
+DBXCLI_ACCESS_TOKEN="$DROPBOX_ACCESS_TOKEN" dbxcli ls --output=json /
+```
+
+Use a dedicated saved-auth file when a job needs refreshable credentials. Store
+the file in a private temp or secret-backed path, not in the repository working
+directory:
+
+```sh
+export DBXCLI_AUTH_FILE="${RUNNER_TEMP:-/tmp}/dbxcli-auth.json"
+dbxcli login
+dbxcli ls /
+```
+
+Do not commit, cache, or upload this file as an artifact; it can contain refresh
+tokens.
+
+Capture JSON output and handle failure by exit code:
+
+```sh
+if ! dbxcli put --if-exists fail --output=json report.md /Reports/report.md >result.json; then
+  jq -r '.error.code + ": " + .error.message' result.json >&2
+  exit 1
+fi
+
+jq -r '.results[] | [.status, .kind] | @tsv' result.json
+```
+
+GitHub Actions example:
+
+This example assumes `dbxcli` is already installed on the runner.
+
+```yaml
+jobs:
+  publish-report:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Upload report to Dropbox
+        env:
+          DBXCLI_ACCESS_TOKEN: ${{ secrets.DROPBOX_ACCESS_TOKEN }}
+        run: |
+          dbxcli account --output=json
+          dbxcli put --if-exists fail --output=json report.md /Reports/report.md
+```
+
 ## Authentication for automation
 
 By default, `dbxcli` stores OAuth credentials in:
@@ -225,6 +279,10 @@ 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.
 
+Commands that write file bytes to stdout cannot also write JSON results to
+stdout. `dbxcli get <path> - --output=json` and
+`dbxcli share-link download <url> - --output=json` return `invalid_arguments`.
+
 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 `./-`.
@@ -245,19 +303,22 @@ exit `0`, including successful commands that return warnings.
 | `5` | Conflict | `path_conflict` |
 | `6` | Rate limited | `rate_limited` |
 | `7` | Validation or usage error | `invalid_arguments`, `unknown_command`, `unknown_flag`, `structured_output_unsupported` |
-| `8` | Partial stdout/output transfer | `partial_transfer` |
+| `8` | Partial stdout transfer | `partial_transfer` |
 
 In JSON mode, inspect both the process exit code and `error.code` for the most
 specific machine-readable failure reason.
 
 ## Shell completion
 
-Shell completion commands intentionally remain text-only because shells expect
-completion scripts or protocol output:
+Completion script/protocol output is text-only because shells expect completion
+scripts or protocol output:
 
 ```sh
 dbxcli completion bash
 dbxcli completion zsh
 dbxcli completion fish
 dbxcli completion powershell
 ```
+
+Passing `--output=json` to completion commands returns
+`structured_output_unsupported`.

docs/commands/dbxcli.md

@@ -2,12 +2,14 @@
 
 ## dbxcli
 
-A command line tool for Dropbox users and team admins
+Scriptable Dropbox CLI for files, shared links, teams, and automation
 
 ### Synopsis
 
-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!
+Use dbxcli to work with Dropbox files, folders, shared links, and team
+workflows from a terminal. It supports text output for humans, structured JSON
+output for automation, pipe-friendly transfers, refreshable OAuth login, and
+direct-token automation for scripts, CI jobs, and agent-style workflows.
 
 ### Options
 

docs/commands/dbxcli_account.md

@@ -46,5 +46,5 @@ dbxcli account [flags] [<account-id>]
 
 ### SEE ALSO
 
-* [dbxcli](dbxcli.md)	 - A command line tool for Dropbox users and team admins
+* [dbxcli](dbxcli.md)	 - Scriptable Dropbox CLI for files, shared links, teams, and automation
 

docs/commands/dbxcli_completion.md

@@ -40,7 +40,7 @@ dbxcli completion [bash|zsh|fish|powershell] [flags]
 
 ### SEE ALSO
 
-* [dbxcli](dbxcli.md)	 - A command line tool for Dropbox users and team admins
+* [dbxcli](dbxcli.md)	 - Scriptable Dropbox CLI for files, shared links, teams, and automation
 * [dbxcli completion bash](dbxcli_completion_bash.md)	 - Generate the autocompletion script for bash
 * [dbxcli completion fish](dbxcli_completion_fish.md)	 - Generate the autocompletion script for fish
 * [dbxcli completion powershell](dbxcli_completion_powershell.md)	 - Generate the autocompletion script for powershell

docs/commands/dbxcli_cp.md

@@ -40,5 +40,5 @@ dbxcli cp [flags] <source> [more sources] <target>
 
 ### SEE ALSO
 
-* [dbxcli](dbxcli.md)	 - A command line tool for Dropbox users and team admins
+* [dbxcli](dbxcli.md)	 - Scriptable Dropbox CLI for files, shared links, teams, and automation