dropbox · AndreyVMarkelov · Jun 28, 2026 · Jun 28, 2026
diff --git a/README.md b/README.md
diff --git a/docs/automation.md 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
@@ -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
@@ -29,6 +29,12 @@ dbxcli account [flags] [<account-id>]
   -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -22,6 +22,12 @@ dbxcli cp [flags] <source> [more sources] <target>
   -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
@@ -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
@@ -40,6 +40,13 @@ dbxcli get [flags] <source> [<target>]
   -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
@@ -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
@@ -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
@@ -39,6 +39,12 @@ dbxcli ls [flags] [<path>]
   -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
@@ -23,6 +23,12 @@ dbxcli mkdir [flags] <directory>
   -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
@@ -22,6 +22,12 @@ dbxcli mv [flags] <source> <target>
   -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
@@ -50,6 +50,13 @@ dbxcli put [flags] <source> [<target>]
   -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
@@ -36,6 +36,12 @@ dbxcli restore [flags] <target-path> <revision>
   -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