Merge pull request #303 from dropbox/docs/readme-auth-modes

AndreyVMarkelov · web-flow · commit 1d0c204e0ab8 · 2026-06-28T10:31:43.000-07:00
Add auth modes to generated docs and polish README
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 # `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/v3)](https://goreportcard.com/report/github.com/dropbox/dbxcli/v3)
+[![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,
@@ -34,6 +34,9 @@ dbxcli --help --output=json
 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).
+
 ## Common workflows
 
 Upload a file:
@@ -66,12 +69,20 @@ Create a shared link:
 dbxcli share-link create /Reports/report.pdf
 ```
 
-Use JSON output:
+In text mode, `share-link create` prints only the shared-link URL to stdout:
 
 ```sh
-dbxcli ls --output=json /
+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.
+
 ## Features
 
 * File operations: `ls`, `cp`, `mkdir`, `mv`, `rm`, `put`, and `get`
@@ -174,8 +185,8 @@ dbxcli put --help --output=json
 * [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)
 
-Generated Cobra command docs live under `docs/commands/` and are kept close to
-the actual CLI by `go run ./tools/gen-docs`.
+Generated Cobra command docs live under `docs/commands/`, and CI verifies they
+stay in sync with the CLI.
 
 ## Contributing
 
diff --git a/cmd/help_json.go b/cmd/help_json.go
@@ -338,6 +338,11 @@ func setCommandDestructiveLevel(cmd *cobra.Command, level string) {
 	setCommandAnnotationList(cmd, commandDestructiveLevelAnnotation, []string{level})
 }
 
+// CommandManifestAuthModes returns the auth modes published in JSON help.
+func CommandManifestAuthModes(cmd *cobra.Command) []string {
+	return commandManifestAuthModes(cmd)
+}
+
 func setCommandAnnotationList(cmd *cobra.Command, key string, values []string) {
 	if cmd.Annotations == nil {
 		cmd.Annotations = make(map[string]string)
diff --git a/docs/commands/dbxcli.md b/docs/commands/dbxcli.md
@@ -22,6 +22,7 @@ manage your team and more. It is easy, scriptable and works on all platforms!
 
 * Structured JSON output: no
 * JSON help manifest: yes
+* Auth modes: none
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_account.md b/docs/commands/dbxcli_account.md
@@ -33,6 +33,7 @@ dbxcli account [flags] [<account-id>]
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `personal`, `team-access`
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_completion.md b/docs/commands/dbxcli_completion.md
@@ -32,6 +32,7 @@ dbxcli completion [bash|zsh|fish|powershell] [flags]
 
 * Structured JSON output: no
 * JSON help manifest: yes
+* Auth modes: none
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_completion_bash.md b/docs/commands/dbxcli_completion_bash.md
@@ -51,6 +51,7 @@ dbxcli completion bash
 
 * Structured JSON output: no
 * JSON help manifest: yes
+* Auth modes: none
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_completion_fish.md b/docs/commands/dbxcli_completion_fish.md
@@ -42,6 +42,7 @@ dbxcli completion fish [flags]
 
 * Structured JSON output: no
 * JSON help manifest: yes
+* Auth modes: none
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_completion_powershell.md b/docs/commands/dbxcli_completion_powershell.md
@@ -39,6 +39,7 @@ dbxcli completion powershell [flags]
 
 * Structured JSON output: no
 * JSON help manifest: yes
+* Auth modes: none
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_completion_zsh.md b/docs/commands/dbxcli_completion_zsh.md
@@ -53,6 +53,7 @@ dbxcli completion zsh [flags]
 
 * Structured JSON output: no
 * JSON help manifest: yes
+* Auth modes: none
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_cp.md b/docs/commands/dbxcli_cp.md
@@ -26,6 +26,7 @@ dbxcli cp [flags] <source> [more sources] <target>
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `personal`, `team-access`
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_du.md b/docs/commands/dbxcli_du.md
@@ -26,6 +26,7 @@ dbxcli du [flags]
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `personal`, `team-access`
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_get.md b/docs/commands/dbxcli_get.md
@@ -44,6 +44,7 @@ dbxcli get [flags] <source> [<target>]
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `personal`, `team-access`
 * Stdin/stdout behavior: Use `-` as the local target to write downloaded file bytes to stdout; diagnostics go to stderr.
 
 
diff --git a/docs/commands/dbxcli_login.md b/docs/commands/dbxcli_login.md
@@ -34,6 +34,7 @@ dbxcli login [personal|team-access|team-manage] [flags]
 
 * Structured JSON output: no
 * JSON help manifest: yes
+* Auth modes: none
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_logout.md b/docs/commands/dbxcli_logout.md
@@ -35,6 +35,7 @@ dbxcli logout [flags]
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: none
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_ls.md b/docs/commands/dbxcli_ls.md
@@ -43,6 +43,7 @@ dbxcli ls [flags] [<path>]
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `personal`, `team-access`
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_mkdir.md b/docs/commands/dbxcli_mkdir.md
@@ -27,6 +27,7 @@ dbxcli mkdir [flags] <directory>
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `personal`, `team-access`
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_mv.md b/docs/commands/dbxcli_mv.md
@@ -26,6 +26,7 @@ dbxcli mv [flags] <source> <target>
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `personal`, `team-access`
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_put.md b/docs/commands/dbxcli_put.md
@@ -54,6 +54,7 @@ dbxcli put [flags] <source> [<target>]
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `personal`, `team-access`
 * Stdin/stdout behavior: Use `-` as the local source to upload from stdin; stdin is spooled to a temporary file before upload.
 
 
diff --git a/docs/commands/dbxcli_restore.md b/docs/commands/dbxcli_restore.md
@@ -40,6 +40,7 @@ dbxcli restore [flags] <target-path> <revision>
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `personal`, `team-access`
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_revs.md b/docs/commands/dbxcli_revs.md
@@ -29,6 +29,7 @@ dbxcli revs [flags] <file>
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `personal`, `team-access`
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_rm.md b/docs/commands/dbxcli_rm.md
@@ -29,6 +29,7 @@ dbxcli rm [flags] <file>
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `personal`, `team-access`
 * Destructive behavior: `delete`
 
 
diff --git a/docs/commands/dbxcli_search.md b/docs/commands/dbxcli_search.md
@@ -34,6 +34,7 @@ dbxcli search [flags] <query> [path-scope]
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `personal`, `team-access`
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_share-link.md b/docs/commands/dbxcli_share-link.md
@@ -26,6 +26,7 @@ Create, list, inspect, download, update, and revoke Dropbox shared links.
 
 * Structured JSON output: no
 * JSON help manifest: yes
+* Auth modes: none
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_share-link_create.md b/docs/commands/dbxcli_share-link_create.md
@@ -51,6 +51,7 @@ dbxcli share-link create <path> [flags]
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `personal`, `team-access`
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_share-link_download.md b/docs/commands/dbxcli_share-link_download.md
@@ -50,6 +50,7 @@ dbxcli share-link download <url> [target] [flags]
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `personal`, `team-access`
 * 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.
 
 
diff --git a/docs/commands/dbxcli_share-link_info.md b/docs/commands/dbxcli_share-link_info.md
@@ -42,6 +42,7 @@ dbxcli share-link info <url> [flags]
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `personal`, `team-access`
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_share-link_list.md b/docs/commands/dbxcli_share-link_list.md
@@ -38,6 +38,7 @@ dbxcli share-link list [path] [flags]
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `personal`, `team-access`
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_share-link_revoke.md b/docs/commands/dbxcli_share-link_revoke.md
@@ -38,6 +38,7 @@ dbxcli share-link revoke [url] [flags]
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `personal`, `team-access`
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_share-link_update.md b/docs/commands/dbxcli_share-link_update.md
@@ -50,6 +50,7 @@ dbxcli share-link update <url> [flags]
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `personal`, `team-access`
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_share.md b/docs/commands/dbxcli_share.md
@@ -22,6 +22,7 @@ Sharing commands
 
 * Structured JSON output: no
 * JSON help manifest: yes
+* Auth modes: none
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_share_list.md b/docs/commands/dbxcli_share_list.md
@@ -22,6 +22,7 @@ List shared things
 
 * Structured JSON output: no
 * JSON help manifest: yes
+* Auth modes: none
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_share_list_folder.md b/docs/commands/dbxcli_share_list_folder.md
@@ -26,6 +26,7 @@ dbxcli share list folder [flags]
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `personal`, `team-access`
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_team.md b/docs/commands/dbxcli_team.md
@@ -22,6 +22,7 @@ Team management commands
 
 * Structured JSON output: no
 * JSON help manifest: yes
+* Auth modes: none
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_team_add-member.md b/docs/commands/dbxcli_team_add-member.md
@@ -26,6 +26,7 @@ dbxcli team add-member [flags] <email> <first-name> <last-name>
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `team-manage`
 * Destructive behavior: `admin`
 
 
diff --git a/docs/commands/dbxcli_team_info.md b/docs/commands/dbxcli_team_info.md
@@ -26,6 +26,7 @@ dbxcli team info [flags]
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `team-manage`
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_team_list-groups.md b/docs/commands/dbxcli_team_list-groups.md
@@ -26,6 +26,7 @@ dbxcli team list-groups [flags]
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `team-manage`
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_team_list-members.md b/docs/commands/dbxcli_team_list-members.md
@@ -26,6 +26,7 @@ dbxcli team list-members [flags]
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `team-manage`
 
 
 ### SEE ALSO
diff --git a/docs/commands/dbxcli_team_remove-member.md b/docs/commands/dbxcli_team_remove-member.md
@@ -26,6 +26,7 @@ dbxcli team remove-member [flags] <email>
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: `team-manage`
 * Destructive behavior: `admin`
 
 
diff --git a/docs/commands/dbxcli_version.md b/docs/commands/dbxcli_version.md
@@ -26,6 +26,7 @@ dbxcli version [flags]
 
 * Structured JSON output: yes
 * JSON help manifest: yes
+* Auth modes: none
 
 
 ### SEE ALSO
diff --git a/tools/gen-docs/main.go b/tools/gen-docs/main.go
@@ -144,6 +144,7 @@ func commandMetadataSection(command *cobra.Command) []byte {
 	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")
+	buf.WriteString("* Auth modes: " + markdownValueList(cmd.CommandManifestAuthModes(command)) + "\n")
 
 	if aliases := sortedAliases(command); len(aliases) > 0 {
 		buf.WriteString("* Aliases: ")
@@ -218,3 +219,14 @@ func yesNo(value bool) string {
 	}
 	return "no"
 }
+
+func markdownValueList(values []string) string {
+	if len(values) == 0 {
+		return "none"
+	}
+	quoted := make([]string, 0, len(values))
+	for _, value := range values {
+		quoted = append(quoted, "`"+value+"`")
+	}
+	return strings.Join(quoted, ", ")
+}
