Update docs, root command description, and add Dependabot config

Refresh root command Short/Long to reflect current CLI capabilities.
Expand automation docs with CI examples, auth patterns, and JSON error
handling. Add schema validation guide and stability notes. Add
Dependabot for Go modules and GitHub Actions. Remove outdated
Chocolatey README.

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