make commanddocs for v1.56

docs/content/commands/rclone_about.md

@@ -12,10 +12,10 @@ Get quota information from the remote.
 ## Synopsis
 
 
-`rclone about`prints quota information about a remote to standard
+`rclone about` prints quota information about a remote to standard
 output. The output is typically used, free, quota and trash contents.
 
-E.g. Typical output from`rclone about remote:`is:
+E.g. Typical output from `rclone about remote:` is:
 
     Total:   17G
     Used:    7.444G
@@ -43,7 +43,7 @@ Applying a `--full` flag to the command prints the bytes in full, e.g.
     Trashed: 104857602
     Other:   8849156022
 
-A `--json`flag generates conveniently computer readable output, e.g.
+A `--json` flag generates conveniently computer readable output, e.g.
 
     {
         "total": 18253611008,

docs/content/commands/rclone_config.md

@@ -35,12 +35,12 @@ See the [global flags page](/flags/) for global options not listed here.
 * [rclone config delete](/commands/rclone_config_delete/)	 - Delete an existing remote `name`.
 * [rclone config disconnect](/commands/rclone_config_disconnect/)	 - Disconnects user from remote
 * [rclone config dump](/commands/rclone_config_dump/)	 - Dump the config file as JSON.
-* [rclone config edit](/commands/rclone_config_edit/)	 - Enter an interactive configuration session.
 * [rclone config file](/commands/rclone_config_file/)	 - Show path of configuration file in use.
 * [rclone config password](/commands/rclone_config_password/)	 - Update password in an existing remote.
 * [rclone config providers](/commands/rclone_config_providers/)	 - List in JSON format all the providers and options.
 * [rclone config reconnect](/commands/rclone_config_reconnect/)	 - Re-authenticates user with remote.
 * [rclone config show](/commands/rclone_config_show/)	 - Print (decrypted) config file, or the config for a single remote.
+* [rclone config touch](/commands/rclone_config_touch/)	 - Ensure configuration file exists.
 * [rclone config update](/commands/rclone_config_update/)	 - Update options in an existing remote.
 * [rclone config userinfo](/commands/rclone_config_userinfo/)	 - Prints info about logged in user of remote.
 

docs/content/commands/rclone_config_create.md

@@ -13,16 +13,23 @@ Create a new remote with name, type and options.
 
 
 Create a new remote of `name` with `type` and options.  The options
-should be passed in pairs of `key` `value`.
+should be passed in pairs of `key` `value` or as `key=value`.
 
 For example to make a swift remote of name myremote using auto config
 you would do:
 
     rclone config create myremote swift env_auth true
+    rclone config create myremote swift env_auth=true
+
+So for example if you wanted to configure a Google Drive remote but
+using remote authorization you would do this:
+
+    rclone config create mydrive drive config_is_local=false
 
 Note that if the config process would normally ask a question the
-default is taken.  Each time that happens rclone will print a message
-saying how to affect the value taken.
+default is taken (unless `--non-interactive` is used).  Each time
+that happens rclone will print or DEBUG a message saying how to
+affect the value taken.
 
 If any of the parameters passed is a password field, then rclone will
 automatically obscure them if they aren't already obscured before
@@ -32,15 +39,79 @@ putting them in the config file.
 consists only of base64 characters then rclone can get confused about
 whether the password is already obscured or not and put unobscured
 passwords into the config file. If you want to be 100% certain that
-the passwords get obscured then use the "--obscure" flag, or if you
+the passwords get obscured then use the `--obscure` flag, or if you
 are 100% certain you are already passing obscured passwords then use
-"--no-obscure".  You can also set obscured passwords using the
-"rclone config password" command.
+`--no-obscure`.  You can also set obscured passwords using the
+`rclone config password` command.
 
-So for example if you wanted to configure a Google Drive remote but
-using remote authorization you would do this:
+The flag `--non-interactive` is for use by applications that wish to
+configure rclone themeselves, rather than using rclone's text based
+configuration questions. If this flag is set, and rclone needs to ask
+the user a question, a JSON blob will be returned with the question in
+it.
+
+This will look something like (some irrelevant detail removed):
+
+```
+{
+    "State": "*oauth-islocal,teamdrive,,",
+    "Option": {
+        "Name": "config_is_local",
+        "Help": "Use auto config?\n * Say Y if not sure\n * Say N if you are working on a remote or headless machine\n",
+        "Default": true,
+        "Examples": [
+            {
+                "Value": "true",
+                "Help": "Yes"
+            },
+            {
+                "Value": "false",
+                "Help": "No"
+            }
+        ],
+        "Required": false,
+        "IsPassword": false,
+        "Type": "bool",
+        "Exclusive": true,
+    },
+    "Error": "",
+}
+```
+
+The format of `Option` is the same as returned by `rclone config
+providers`. The question should be asked to the user and returned to
+rclone as the `--result` option along with the `--state` parameter.
+
+The keys of `Option` are used as follows:
+
+- `Name` - name of variable - show to user
+- `Help` - help text. Hard wrapped at 80 chars. Any URLs should be clicky.
+- `Default` - default value - return this if the user just wants the default.
+- `Examples` - the user should be able to choose one of these
+- `Required` - the value should be non-empty
+- `IsPassword` - the value is a password and should be edited as such
+- `Type` - type of value, eg `bool`, `string`, `int` and others
+- `Exclusive` - if set no free-form entry allowed only the `Examples`
+- Irrelevant keys `Provider`, `ShortOpt`, `Hide`, `NoPrefix`, `Advanced`
+
+If `Error` is set then it should be shown to the user at the same
+time as the question.
+
+    rclone config update name --continue --state "*oauth-islocal,teamdrive,," --result "true"
+
+Note that when using `--continue` all passwords should be passed in
+the clear (not obscured). Any default config values should be passed
+in with each invocation of `--continue`.
+
+At the end of the non interactive process, rclone will return a result
+with `State` as empty string.
+
+If `--all` is passed then rclone will ask all the config questions,
+not just the post config questions. Any parameters are used as
+defaults for questions as usual.
 
-    rclone config create mydrive drive config_is_local false
+Note that `bin/config.py` in the rclone source implements this protocol
+as a readable demonstration.
 
 
 ```
@@ -50,9 +121,14 @@ rclone config create `name` `type` [`key` `value`]* [flags]
 ## Options
 
 ```
-  -h, --help         help for create
-      --no-obscure   Force any passwords not to be obscured.
-      --obscure      Force any passwords to be obscured.
+      --all               Ask the full set of config questions.
+      --continue          Continue the configuration process with an answer.
+  -h, --help              help for create
+      --no-obscure        Force any passwords not to be obscured.
+      --non-interactive   Don't interact with user and return questions.
+      --obscure           Force any passwords to be obscured.
+      --result string     Result - use with --continue.
+      --state string      State - use with --continue.
 ```
 
 See the [global flags page](/flags/) for global options not listed here.

docs/content/commands/rclone_config_edit.md

@@ -9,7 +9,7 @@ url: /commands/rclone_config_edit/
 
 Enter an interactive configuration session.
 
-## Synopsis
+# Synopsis
 
 Enter an interactive configuration session where you can setup new
 remotes and manage existing ones. You may also set or remove a
@@ -20,15 +20,15 @@ password to protect your configuration.
 rclone config edit [flags]
 ```
 
-## Options
+# Options
 
 ```
   -h, --help   help for edit
 ```
 
 See the [global flags page](/flags/) for global options not listed here.
 
-## SEE ALSO
+# SEE ALSO
 
 * [rclone config](/commands/rclone_config/)	 - Enter an interactive configuration session.
 

docs/content/commands/rclone_config_password.md

@@ -13,11 +13,13 @@ Update password in an existing remote.
 
 
 Update an existing remote's password. The password
-should be passed in pairs of `key` `value`.
+should be passed in pairs of `key` `password` or as `key=password`.
+The `password` should be passed in in clear (unobscured).
 
 For example to set password of a remote of name myremote you would do:
 
     rclone config password myremote fieldname mypassword
+    rclone config password myremote fieldname=mypassword
 
 This command is obsolete now that "config update" and "config create"
 both support obscuring passwords directly.

docs/content/commands/rclone_config_touch.md

@@ -0,0 +1,27 @@
+---
+title: "rclone config touch"
+description: "Ensure configuration file exists."
+slug: rclone_config_touch
+url: /commands/rclone_config_touch/
+# autogenerated - DO NOT EDIT, instead edit the source code in cmd/config/touch/ and as part of making a release run "make commanddocs"
+---
+# rclone config touch
+
+Ensure configuration file exists.
+
+```
+rclone config touch [flags]
+```
+
+## Options
+
+```
+  -h, --help   help for touch
+```
+
+See the [global flags page](/flags/) for global options not listed here.
+
+## SEE ALSO
+
+* [rclone config](/commands/rclone_config/)	 - Enter an interactive configuration session.
+

docs/content/commands/rclone_config_update.md

@@ -13,12 +13,23 @@ Update options in an existing remote.
 
 
 Update an existing remote's options. The options should be passed in
-in pairs of `key` `value`.
+pairs of `key` `value` or as `key=value`.
 
 For example to update the env_auth field of a remote of name myremote
 you would do:
 
-    rclone config update myremote swift env_auth true
+    rclone config update myremote env_auth true
+    rclone config update myremote env_auth=true
+
+If the remote uses OAuth the token will be updated, if you don't
+require this add an extra parameter thus:
+
+    rclone config update myremote swift env_auth=true config_refresh_token=false
+
+Note that if the config process would normally ask a question the
+default is taken (unless `--non-interactive` is used).  Each time
+that happens rclone will print or DEBUG a message saying how to
+affect the value taken.
 
 If any of the parameters passed is a password field, then rclone will
 automatically obscure them if they aren't already obscured before
@@ -28,15 +39,79 @@ putting them in the config file.
 consists only of base64 characters then rclone can get confused about
 whether the password is already obscured or not and put unobscured
 passwords into the config file. If you want to be 100% certain that
-the passwords get obscured then use the "--obscure" flag, or if you
+the passwords get obscured then use the `--obscure` flag, or if you
 are 100% certain you are already passing obscured passwords then use
-"--no-obscure".  You can also set obscured passwords using the
-"rclone config password" command.
+`--no-obscure`.  You can also set obscured passwords using the
+`rclone config password` command.
 
-If the remote uses OAuth the token will be updated, if you don't
-require this add an extra parameter thus:
+The flag `--non-interactive` is for use by applications that wish to
+configure rclone themeselves, rather than using rclone's text based
+configuration questions. If this flag is set, and rclone needs to ask
+the user a question, a JSON blob will be returned with the question in
+it.
+
+This will look something like (some irrelevant detail removed):
+
+```
+{
+    "State": "*oauth-islocal,teamdrive,,",
+    "Option": {
+        "Name": "config_is_local",
+        "Help": "Use auto config?\n * Say Y if not sure\n * Say N if you are working on a remote or headless machine\n",
+        "Default": true,
+        "Examples": [
+            {
+                "Value": "true",
+                "Help": "Yes"
+            },
+            {
+                "Value": "false",
+                "Help": "No"
+            }
+        ],
+        "Required": false,
+        "IsPassword": false,
+        "Type": "bool",
+        "Exclusive": true,
+    },
+    "Error": "",
+}
+```
+
+The format of `Option` is the same as returned by `rclone config
+providers`. The question should be asked to the user and returned to
+rclone as the `--result` option along with the `--state` parameter.
+
+The keys of `Option` are used as follows:
+
+- `Name` - name of variable - show to user
+- `Help` - help text. Hard wrapped at 80 chars. Any URLs should be clicky.
+- `Default` - default value - return this if the user just wants the default.
+- `Examples` - the user should be able to choose one of these
+- `Required` - the value should be non-empty
+- `IsPassword` - the value is a password and should be edited as such
+- `Type` - type of value, eg `bool`, `string`, `int` and others
+- `Exclusive` - if set no free-form entry allowed only the `Examples`
+- Irrelevant keys `Provider`, `ShortOpt`, `Hide`, `NoPrefix`, `Advanced`
+
+If `Error` is set then it should be shown to the user at the same
+time as the question.
+
+    rclone config update name --continue --state "*oauth-islocal,teamdrive,," --result "true"
+
+Note that when using `--continue` all passwords should be passed in
+the clear (not obscured). Any default config values should be passed
+in with each invocation of `--continue`.
+
+At the end of the non interactive process, rclone will return a result
+with `State` as empty string.
+
+If `--all` is passed then rclone will ask all the config questions,
+not just the post config questions. Any parameters are used as
+defaults for questions as usual.
 
-    rclone config update myremote swift env_auth true config_refresh_token false
+Note that `bin/config.py` in the rclone source implements this protocol
+as a readable demonstration.
 
 
 ```
@@ -46,9 +121,14 @@ rclone config update `name` [`key` `value`]+ [flags]
 ## Options
 
 ```
-  -h, --help         help for update
-      --no-obscure   Force any passwords not to be obscured.
-      --obscure      Force any passwords to be obscured.
+      --all               Ask the full set of config questions.
+      --continue          Continue the configuration process with an answer.
+  -h, --help              help for update
+      --no-obscure        Force any passwords not to be obscured.
+      --non-interactive   Don't interact with user and return questions.
+      --obscure           Force any passwords to be obscured.
+      --result string     Result - use with --continue.
+      --state string      State - use with --continue.
 ```
 
 See the [global flags page](/flags/) for global options not listed here.

docs/content/commands/rclone_copyurl.md

@@ -15,9 +15,9 @@ Copy url content to dest.
 Download a URL's content and copy it to the destination without saving
 it in temporary storage.
 
-Setting `--auto-filename`will cause the file name to be retrieved from
-the from URL (after any redirections) and used in the destination
-path. With `--print-filename` in addition, the resuling file name will
+Setting `--auto-filename` will cause the file name to be retrieved from
+the URL (after any redirections) and used in the destination
+path. With `--print-filename` in addition, the resulting file name will
 be printed.
 
 Setting `--no-clobber` will prevent overwriting file on the 

docs/content/commands/rclone_delete.md

@@ -23,8 +23,8 @@ If you supply the `--rmdirs` flag, it will remove all empty directories along wi
 You can also use the separate command `rmdir` or `rmdirs` to
 delete empty directories only.
 
-For example, to delete all files bigger than 100 MiByte, you may first want to check what
-would be deleted (use either):
+For example, to delete all files bigger than 100 MiB, you may first want to
+check what would be deleted (use either):
 
     rclone --min-size 100M lsl remote:path
     rclone --dry-run --min-size 100M delete remote:path
@@ -34,7 +34,7 @@ Then proceed with the actual delete:
     rclone --min-size 100M delete remote:path
 
 That reads "delete everything with a minimum size of 100 MiB", hence
-delete all files bigger than 100 MiByte.
+delete all files bigger than 100 MiB.
 
 **Important**: Since this can cause data loss, test first with the
 `--dry-run` or the `--interactive`/`-i` flag.