From 1d780dab94969a91491e5732f367824166f62745 Mon Sep 17 00:00:00 2001 From: Andrey Markelov Date: Sun, 28 Jun 2026 10:27:42 -0700 Subject: [PATCH] Add auth modes to generated docs and polish README Export CommandManifestAuthModes for gen-docs to include auth mode metadata in command reference pages. Update README with automation link, share-link capture example, and troubleshooting section. --- README.md | 21 ++++++++++++++----- cmd/help_json.go | 5 +++++ docs/commands/dbxcli.md | 1 + docs/commands/dbxcli_account.md | 1 + docs/commands/dbxcli_completion.md | 1 + docs/commands/dbxcli_completion_bash.md | 1 + docs/commands/dbxcli_completion_fish.md | 1 + docs/commands/dbxcli_completion_powershell.md | 1 + docs/commands/dbxcli_completion_zsh.md | 1 + docs/commands/dbxcli_cp.md | 1 + docs/commands/dbxcli_du.md | 1 + docs/commands/dbxcli_get.md | 1 + docs/commands/dbxcli_login.md | 1 + docs/commands/dbxcli_logout.md | 1 + docs/commands/dbxcli_ls.md | 1 + docs/commands/dbxcli_mkdir.md | 1 + docs/commands/dbxcli_mv.md | 1 + docs/commands/dbxcli_put.md | 1 + docs/commands/dbxcli_restore.md | 1 + docs/commands/dbxcli_revs.md | 1 + docs/commands/dbxcli_rm.md | 1 + docs/commands/dbxcli_search.md | 1 + docs/commands/dbxcli_share-link.md | 1 + docs/commands/dbxcli_share-link_create.md | 1 + docs/commands/dbxcli_share-link_download.md | 1 + docs/commands/dbxcli_share-link_info.md | 1 + docs/commands/dbxcli_share-link_list.md | 1 + docs/commands/dbxcli_share-link_revoke.md | 1 + docs/commands/dbxcli_share-link_update.md | 1 + docs/commands/dbxcli_share.md | 1 + docs/commands/dbxcli_share_list.md | 1 + docs/commands/dbxcli_share_list_folder.md | 1 + docs/commands/dbxcli_team.md | 1 + docs/commands/dbxcli_team_add-member.md | 1 + docs/commands/dbxcli_team_info.md | 1 + docs/commands/dbxcli_team_list-groups.md | 1 + docs/commands/dbxcli_team_list-members.md | 1 + docs/commands/dbxcli_team_remove-member.md | 1 + docs/commands/dbxcli_version.md | 1 + tools/gen-docs/main.go | 12 +++++++++++ 40 files changed, 70 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 6130d61..27fb3ff 100644 --- 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 index ade4710..c47280e 100644 --- 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 index 7900b55..a4ed30f 100644 --- 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 index 7475328..00df951 100644 --- a/docs/commands/dbxcli_account.md +++ b/docs/commands/dbxcli_account.md @@ -33,6 +33,7 @@ dbxcli account [flags] [] * 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 index db935a4..199373a 100644 --- 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 index 379f62b..51109df 100644 --- 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 index 9e5971b..bf72bf9 100644 --- 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 index 8047c55..ae2d494 100644 --- 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 index fa74cb3..55a91f1 100644 --- 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 index 841d6d3..9267a49 100644 --- a/docs/commands/dbxcli_cp.md +++ b/docs/commands/dbxcli_cp.md @@ -26,6 +26,7 @@ dbxcli cp [flags] [more sources] * 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 index ff5bff5..3a4b95c 100644 --- 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 index c195e70..b30fc69 100644 --- a/docs/commands/dbxcli_get.md +++ b/docs/commands/dbxcli_get.md @@ -44,6 +44,7 @@ dbxcli get [flags] [] * 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 index 0d96562..c848587 100644 --- 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 index 5cd11ef..b6e2424 100644 --- 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 index 23d02be..14bd496 100644 --- a/docs/commands/dbxcli_ls.md +++ b/docs/commands/dbxcli_ls.md @@ -43,6 +43,7 @@ dbxcli ls [flags] [] * 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 index 6e35852..36d31f2 100644 --- a/docs/commands/dbxcli_mkdir.md +++ b/docs/commands/dbxcli_mkdir.md @@ -27,6 +27,7 @@ dbxcli mkdir [flags] * 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 index e3e737f..0213bb2 100644 --- a/docs/commands/dbxcli_mv.md +++ b/docs/commands/dbxcli_mv.md @@ -26,6 +26,7 @@ dbxcli mv [flags] * 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 index 6ecca38..0fcc158 100644 --- a/docs/commands/dbxcli_put.md +++ b/docs/commands/dbxcli_put.md @@ -54,6 +54,7 @@ dbxcli put [flags] [] * 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 index dd32a90..96352a6 100644 --- a/docs/commands/dbxcli_restore.md +++ b/docs/commands/dbxcli_restore.md @@ -40,6 +40,7 @@ dbxcli restore [flags] * 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 index e021910..9a2e108 100644 --- a/docs/commands/dbxcli_revs.md +++ b/docs/commands/dbxcli_revs.md @@ -29,6 +29,7 @@ dbxcli revs [flags] * 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 index 2ba7d93..323a987 100644 --- a/docs/commands/dbxcli_rm.md +++ b/docs/commands/dbxcli_rm.md @@ -29,6 +29,7 @@ dbxcli rm [flags] * 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 index 9d41d77..d2a37d7 100644 --- a/docs/commands/dbxcli_search.md +++ b/docs/commands/dbxcli_search.md @@ -34,6 +34,7 @@ dbxcli search [flags] [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 index fa95286..9945feb 100644 --- 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 index 25fa902..7089e89 100644 --- a/docs/commands/dbxcli_share-link_create.md +++ b/docs/commands/dbxcli_share-link_create.md @@ -51,6 +51,7 @@ dbxcli share-link create [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 index 38e855c..1c91ce4 100644 --- a/docs/commands/dbxcli_share-link_download.md +++ b/docs/commands/dbxcli_share-link_download.md @@ -50,6 +50,7 @@ dbxcli share-link download [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 index 2f6a0a8..5a016f0 100644 --- a/docs/commands/dbxcli_share-link_info.md +++ b/docs/commands/dbxcli_share-link_info.md @@ -42,6 +42,7 @@ dbxcli share-link info [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 index d765a3e..5c4ec02 100644 --- 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 index 7a5a500..c4d3e33 100644 --- 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 index 1c60839..3cddf74 100644 --- a/docs/commands/dbxcli_share-link_update.md +++ b/docs/commands/dbxcli_share-link_update.md @@ -50,6 +50,7 @@ dbxcli share-link update [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 index a0aabfc..4f0ea0d 100644 --- 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 index bf948ea..74edabb 100644 --- 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 index 17c56ef..9154bf6 100644 --- 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 index 5b4456d..f442b54 100644 --- 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 index df75cca..c8502cd 100644 --- 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] * 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 index 7c8ba3f..5006851 100644 --- 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 index 13c174b..d3a7191 100644 --- 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 index a1cf6c6..f157653 100644 --- 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 index d36c98f..28cbd71 100644 --- 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] * 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 index 6df3328..9aff3d7 100644 --- 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 index 199162d..7c0be85 100644 --- 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, ", ") +}