opencode-skills-collection 3.1.12 → 3.1.14

package/bundled-skills/rclone-cli/references/providers/dropbox.md

@@ -0,0 +1,661 @@
+---
+title: "Dropbox"
+description: "Rclone docs for Dropbox"
+versionIntroduced: "v1.02"
+---
+
+> **Official documentation:** [https://rclone.org/dropbox/](https://rclone.org/dropbox/)
+# Dropbox
+
+Paths are specified as `remote:path`
+
+Dropbox paths may be as deep as required, e.g.
+`remote:directory/subdirectory`.
+
+## Configuration
+
+The initial setup for dropbox involves getting a token from Dropbox
+which you need to do in your browser.  `rclone config` walks you
+through it.
+
+Here is an example of how to make a remote called `remote`.  First run:
+
+```console
+rclone config
+```
+
+This will guide you through an interactive setup process:
+
+```text
+n) New remote
+d) Delete remote
+q) Quit config
+e/n/d/q> n
+name> remote
+Type of storage to configure.
+Choose a number from below, or type in your own value
+[snip]
+XX / Dropbox
+   \ "dropbox"
+[snip]
+Storage> dropbox
+Dropbox App Key - leave blank normally.
+app_key>
+Dropbox App Secret - leave blank normally.
+app_secret>
+Remote config
+Please visit:
+https://www.dropbox.com/1/oauth2/authorize?client_id=XXXXXXXXXXXXXXX&response_type=code
+Enter the code: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX_XXXXXXXXXX
+Configuration complete.
+Options:
+- type: dropbox
+- app_key:
+- app_secret:
+- token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXX_XXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+Keep this "remote" remote?
+y) Yes this is OK
+e) Edit this remote
+d) Delete this remote
+y/e/d> y
+```
+
+See the [remote setup docs](/remote_setup/) for how to set it up on a
+machine without an internet-connected web browser available.
+
+Note that rclone runs a webserver on your local machine to collect the
+token as returned from Dropbox. This only
+runs from the moment it opens your browser to the moment you get back
+the verification code.  This is on `http://127.0.0.1:53682/` and it
+may require you to unblock it temporarily if you are running a host
+firewall, or use manual mode.
+
+You can then use it like this,
+
+List directories in top level of your dropbox
+
+```console
+rclone lsd remote:
+```
+
+List all the files in your dropbox
+
+```console
+rclone ls remote:
+```
+
+To copy a local directory to a dropbox directory called backup
+
+```console
+rclone copy /home/source remote:backup
+```
+
+### Dropbox for business
+
+Rclone supports Dropbox for business and Team Folders.
+
+When using Dropbox for business `remote:` and `remote:path/to/file`
+will refer to your personal folder.
+
+If you wish to see Team Folders you must use a leading `/` in the
+path, so `rclone lsd remote:/` will refer to the root and show you all
+Team Folders and your User Folder.
+
+You can then use team folders like this `remote:/TeamFolder` and
+`remote:/TeamFolder/path/to/file`.
+
+A leading `/` for a Dropbox personal account will do nothing, but it
+will take an extra HTTP transaction so it should be avoided.
+
+### Modification times and hashes
+
+Dropbox supports modified times, but the only way to set a
+modification time is to re-upload the file.
+
+This means that if you uploaded your data with an older version of
+rclone which didn't support the v2 API and modified times, rclone will
+decide to upload all your old data to fix the modification times.  If
+you don't want this to happen use `--size-only` or `--checksum` flag
+to stop it.
+
+Dropbox supports [its own hash
+type](https://www.dropbox.com/developers/reference/content-hash) which
+is checked for all transfers.
+
+### Restricted filename characters
+
+| Character | Value | Replacement |
+| --------- |:-----:|:-----------:|
+| NUL       | 0x00  | ␀           |
+| /         | 0x2F  | ／           |
+| DEL       | 0x7F  | ␡           |
+| \         | 0x5C  | ＼           |
+
+File names can also not end with the following characters.
+These only get replaced if they are the last character in the name:
+
+| Character | Value | Replacement |
+| --------- |:-----:|:-----------:|
+| SP        | 0x20  | ␠           |
+
+Invalid UTF-8 bytes will also be [replaced](/overview/#invalid-utf8),
+as they can't be used in JSON strings.
+
+### Batch mode uploads {#batch-mode}
+
+Using batch mode uploads is very important for performance when using
+the Dropbox API. See [the dropbox performance guide](https://developers.dropbox.com/dbx-performance-guide)
+for more info.
+
+There are 3 modes rclone can use for uploads.
+
+#### --dropbox-batch-mode off
+
+In this mode rclone will not use upload batching. This was the default
+before rclone v1.55. It has the disadvantage that it is very likely to
+encounter `too_many_requests` errors like this
+
+```text
+NOTICE: too_many_requests/.: Too many requests or write operations. Trying again in 15 seconds.
+```
+
+When rclone receives these it has to wait for 15s or sometimes 300s
+before continuing which really slows down transfers.
+
+This will happen especially if `--transfers` is large, so this mode
+isn't recommended except for compatibility or investigating problems.
+
+#### --dropbox-batch-mode sync
+
+In this mode rclone will batch up uploads to the size specified by
+`--dropbox-batch-size` and commit them together.
+
+Using this mode means you can use a much higher `--transfers`
+parameter (32 or 64 works fine) without receiving `too_many_requests`
+errors.
+
+This mode ensures full data integrity.
+
+Note that there may be a pause when quitting rclone while rclone
+finishes up the last batch using this mode.
+
+#### --dropbox-batch-mode async
+
+In this mode rclone will batch up uploads to the size specified by
+`--dropbox-batch-size` and commit them together.
+
+However it will not wait for the status of the batch to be returned to
+the caller. This means rclone can use a much bigger batch size (much
+bigger than `--transfers`), at the cost of not being able to check the
+status of the upload.
+
+This provides the maximum possible upload speed especially with lots
+of small files, however rclone can't check the file got uploaded
+properly using this mode.
+
+If you are using this mode then using "rclone check" after the
+transfer completes is recommended. Or you could do an initial transfer
+with `--dropbox-batch-mode async` then do a final transfer with
+`--dropbox-batch-mode sync` (the default).
+
+Note that there may be a pause when quitting rclone while rclone
+finishes up the last batch using this mode.
+
+### Exporting files
+
+Certain files in Dropbox are "exportable", such as Dropbox Paper
+documents. These files need to be converted to another format in
+order to be downloaded. Often multiple formats are available for
+conversion.
+
+When rclone downloads a exportable file, it chooses the format to
+download based on the `--dropbox-export-formats` setting. By
+default, the export formats are `html,md`, which are sensible
+defaults for Dropbox Paper.
+
+Rclone chooses the first format ID in the export formats list that
+Dropbox supports for a given file. If no format in the list is
+usable, rclone will choose the default format that Dropbox suggests.
+
+Rclone will change the extension to correspond to the export format.
+Here are some examples of how extensions are mapped:
+
+| File type      | Filename in Dropbox | Filename in rclone |
+|----------------|---------------------|--------------------|
+| Paper          | mydoc.paper         | mydoc.html         |
+| Paper template | mydoc.papert        | mydoc.papert.html  |
+| other          | mydoc               | mydoc.html         |
+
+*Importing* exportable files is not yet supported by rclone.
+
+Here are the supported export extensions known by rclone. Note that
+rclone does not currently support other formats not on this list,
+even if Dropbox supports them. Also, Dropbox could change the list
+of supported formats at any time.
+
+| Format ID | Name     | Description          |
+|-----------|----------|----------------------|
+| html      | HTML     | HTML document        |
+| md        | Markdown | Markdown text format |
+
+<!-- autogenerated options start - DO NOT EDIT - instead edit fs.RegInfo in backend/dropbox/dropbox.go and run make backenddocs to verify --> <!-- markdownlint-disable-line line-length -->
+### Standard options
+
+Here are the Standard options specific to dropbox (Dropbox).
+
+#### --dropbox-client-id
+
+OAuth Client Id.
+
+Leave blank normally.
+
+Properties:
+
+- Config:      client_id
+- Env Var:     RCLONE_DROPBOX_CLIENT_ID
+- Type:        string
+- Required:    false
+
+#### --dropbox-client-secret
+
+OAuth Client Secret.
+
+Leave blank normally.
+
+Properties:
+
+- Config:      client_secret
+- Env Var:     RCLONE_DROPBOX_CLIENT_SECRET
+- Type:        string
+- Required:    false
+
+### Advanced options
+
+Here are the Advanced options specific to dropbox (Dropbox).
+
+#### --dropbox-token
+
+OAuth Access Token as a JSON blob.
+
+Properties:
+
+- Config:      token
+- Env Var:     RCLONE_DROPBOX_TOKEN
+- Type:        string
+- Required:    false
+
+#### --dropbox-auth-url
+
+Auth server URL.
+
+Leave blank to use the provider defaults.
+
+Properties:
+
+- Config:      auth_url
+- Env Var:     RCLONE_DROPBOX_AUTH_URL
+- Type:        string
+- Required:    false
+
+#### --dropbox-token-url
+
+Token server url.
+
+Leave blank to use the provider defaults.
+
+Properties:
+
+- Config:      token_url
+- Env Var:     RCLONE_DROPBOX_TOKEN_URL
+- Type:        string
+- Required:    false
+
+#### --dropbox-client-credentials
+
+Use client credentials OAuth flow.
+
+This will use the OAUTH2 client Credentials Flow as described in RFC 6749.
+
+Note that this option is NOT supported by all backends.
+
+Properties:
+
+- Config:      client_credentials
+- Env Var:     RCLONE_DROPBOX_CLIENT_CREDENTIALS
+- Type:        bool
+- Default:     false
+
+#### --dropbox-chunk-size
+
+Upload chunk size (< 150Mi).
+
+Any files larger than this will be uploaded in chunks of this size.
+
+Note that chunks are buffered in memory (one at a time) so rclone can
+deal with retries.  Setting this larger will increase the speed
+slightly (at most 10% for 128 MiB in tests) at the cost of using more
+memory.  It can be set smaller if you are tight on memory.
+
+Properties:
+
+- Config:      chunk_size
+- Env Var:     RCLONE_DROPBOX_CHUNK_SIZE
+- Type:        SizeSuffix
+- Default:     48Mi
+
+#### --dropbox-impersonate
+
+Impersonate this user when using a business account.
+
+Note that if you want to use impersonate, you should make sure this
+flag is set when running "rclone config" as this will cause rclone to
+request the "members.read" scope which it won't normally. This is
+needed to lookup a members email address into the internal ID that
+dropbox uses in the API.
+
+Using the "members.read" scope will require a Dropbox Team Admin
+to approve during the OAuth flow.
+
+You will have to use your own App (setting your own client_id and
+client_secret) to use this option as currently rclone's default set of
+permissions doesn't include "members.read". This can be added once
+v1.55 or later is in use everywhere.
+
+
+Properties:
+
+- Config:      impersonate
+- Env Var:     RCLONE_DROPBOX_IMPERSONATE
+- Type:        string
+- Required:    false
+
+#### --dropbox-shared-files
+
+Instructs rclone to work on individual shared files.
+
+In this mode rclone's features are extremely limited - only list (ls, lsl, etc.)
+operations and read operations (e.g. downloading) are supported in this mode.
+All other operations will be disabled.
+
+Properties:
+
+- Config:      shared_files
+- Env Var:     RCLONE_DROPBOX_SHARED_FILES
+- Type:        bool
+- Default:     false
+
+#### --dropbox-shared-folders
+
+Instructs rclone to work on shared folders.
+
+When this flag is used with no path only the List operation is supported and
+all available shared folders will be listed. If you specify a path the first part
+will be interpreted as the name of shared folder. Rclone will then try to mount this
+shared to the root namespace. On success shared folder rclone proceeds normally.
+The shared folder is now pretty much a normal folder and all normal operations
+are supported.
+
+Note that we don't unmount the shared folder afterwards so the
+--dropbox-shared-folders can be omitted after the first use of a particular
+shared folder.
+
+See also --dropbox-root-namespace for an alternative way to work with shared
+folders.
+
+Properties:
+
+- Config:      shared_folders
+- Env Var:     RCLONE_DROPBOX_SHARED_FOLDERS
+- Type:        bool
+- Default:     false
+
+#### --dropbox-pacer-min-sleep
+
+Minimum time to sleep between API calls.
+
+Properties:
+
+- Config:      pacer_min_sleep
+- Env Var:     RCLONE_DROPBOX_PACER_MIN_SLEEP
+- Type:        Duration
+- Default:     10ms
+
+#### --dropbox-encoding
+
+The encoding for the backend.
+
+See the [encoding section in the overview](/overview/#encoding) for more info.
+
+Properties:
+
+- Config:      encoding
+- Env Var:     RCLONE_DROPBOX_ENCODING
+- Type:        Encoding
+- Default:     Slash,BackSlash,Del,RightSpace,InvalidUtf8,Dot
+
+#### --dropbox-root-namespace
+
+Specify a different Dropbox namespace ID to use as the root for all paths.
+
+Properties:
+
+- Config:      root_namespace
+- Env Var:     RCLONE_DROPBOX_ROOT_NAMESPACE
+- Type:        string
+- Required:    false
+
+#### --dropbox-export-formats
+
+Comma separated list of preferred formats for exporting files
+
+Certain Dropbox files can only be accessed by exporting them to another format.
+These include Dropbox Paper documents.
+
+For each such file, rclone will choose the first format on this list that Dropbox
+considers valid. If none is valid, it will choose Dropbox's default format.
+
+Known formats include: "html", "md" (markdown)
+
+Properties:
+
+- Config:      export_formats
+- Env Var:     RCLONE_DROPBOX_EXPORT_FORMATS
+- Type:        CommaSepList
+- Default:     html,md
+
+#### --dropbox-skip-exports
+
+Skip exportable files in all listings.
+
+If given, exportable files practically become invisible to rclone.
+
+Properties:
+
+- Config:      skip_exports
+- Env Var:     RCLONE_DROPBOX_SKIP_EXPORTS
+- Type:        bool
+- Default:     false
+
+#### --dropbox-show-all-exports
+
+Show all exportable files in listings.
+
+Adding this flag will allow all exportable files to be server side copied.
+Note that rclone doesn't add extensions to the exportable file names in this mode.
+
+Do **not** use this flag when trying to download exportable files - rclone
+will fail to download them.
+
+
+Properties:
+
+- Config:      show_all_exports
+- Env Var:     RCLONE_DROPBOX_SHOW_ALL_EXPORTS
+- Type:        bool
+- Default:     false
+
+#### --dropbox-batch-mode
+
+Upload file batching sync|async|off.
+
+This sets the batch mode used by rclone.
+
+For full info see [the main docs](https://rclone.org/dropbox/#batch-mode)
+
+This has 3 possible values
+
+- off - no batching
+- sync - batch uploads and check completion (default)
+- async - batch upload and don't check completion
+
+Rclone will close any outstanding batches when it exits which may make
+a delay on quit.
+
+
+Properties:
+
+- Config:      batch_mode
+- Env Var:     RCLONE_DROPBOX_BATCH_MODE
+- Type:        string
+- Default:     "sync"
+
+#### --dropbox-batch-size
+
+Max number of files in upload batch.
+
+This sets the batch size of files to upload. It has to be less than 1000.
+
+By default this is 0 which means rclone will calculate the batch size
+depending on the setting of batch_mode.
+
+- batch_mode: async - default batch_size is 100
+- batch_mode: sync - default batch_size is the same as --transfers
+- batch_mode: off - not in use
+
+Rclone will close any outstanding batches when it exits which may make
+a delay on quit.
+
+Setting this is a great idea if you are uploading lots of small files
+as it will make them a lot quicker. You can use --transfers 32 to
+maximise throughput.
+
+
+Properties:
+
+- Config:      batch_size
+- Env Var:     RCLONE_DROPBOX_BATCH_SIZE
+- Type:        int
+- Default:     0
+
+#### --dropbox-batch-timeout
+
+Max time to allow an idle upload batch before uploading.
+
+If an upload batch is idle for more than this long then it will be
+uploaded.
+
+The default for this is 0 which means rclone will choose a sensible
+default based on the batch_mode in use.
+
+- batch_mode: async - default batch_timeout is 10s
+- batch_mode: sync - default batch_timeout is 500ms
+- batch_mode: off - not in use
+
+
+Properties:
+
+- Config:      batch_timeout
+- Env Var:     RCLONE_DROPBOX_BATCH_TIMEOUT
+- Type:        Duration
+- Default:     0s
+
+#### --dropbox-batch-commit-timeout
+
+Max time to wait for a batch to finish committing. (no longer used)
+
+Properties:
+
+- Config:      batch_commit_timeout
+- Env Var:     RCLONE_DROPBOX_BATCH_COMMIT_TIMEOUT
+- Type:        Duration
+- Default:     10m0s
+
+#### --dropbox-description
+
+Description of the remote.
+
+Properties:
+
+- Config:      description
+- Env Var:     RCLONE_DROPBOX_DESCRIPTION
+- Type:        string
+- Required:    false
+
+<!-- autogenerated options stop -->
+
+## Limitations
+
+Note that Dropbox is case insensitive so you can't have a file called
+"Hello.doc" and one called "hello.doc".
+
+There are some file names such as `thumbs.db` which Dropbox can't
+store.  There is a full list of them in the ["Ignored Files" section
+of this document](https://www.dropbox.com/en/help/145).  Rclone will
+issue an error message `File name disallowed - not uploading` if it
+attempts to upload one of those file names, but the sync won't fail.
+
+Some errors may occur if you try to sync copyright-protected files
+because Dropbox has its own [copyright detector](https://techcrunch.com/2014/03/30/how-dropbox-knows-when-youre-sharing-copyrighted-stuff-without-actually-looking-at-your-stuff/)
+that prevents this sort of file being downloaded. This will return the error
+`ERROR : /path/to/your/file: Failed to copy: failed to open source object: path/restricted_content/.`
+
+If you have more than 10,000 files in a directory then `rclone purge
+dropbox:dir` will return the error `Failed to purge: There are too
+many files involved in this operation`.  As a work-around do an
+`rclone delete dropbox:dir` followed by an `rclone rmdir dropbox:dir`.
+
+When using `rclone link` you'll need to set `--expire` if using a
+non-personal account otherwise the visibility may not be correct.
+(Note that `--expire` isn't supported on personal accounts). See the
+[forum discussion](https://forum.rclone.org/t/rclone-link-dropbox-permissions/23211)
+and the
+[dropbox SDK issue](https://github.com/dropbox/dropbox-sdk-go-unofficial/issues/75).
+
+Modification times for Dropbox Paper documents are not exact, and
+may  not change for some period after the document is edited.
+To make sure you get recent changes in a sync, either wait an hour
+or so, or use `--ignore-times` to force a full sync.
+
+## Get your own Dropbox App ID
+
+When you use rclone with Dropbox in its default configuration you are using
+rclone's App ID. This is shared between all the rclone users.
+
+Here is how to create your own Dropbox App ID for rclone:
+
+1. Log into the [Dropbox App console](https://www.dropbox.com/developers/apps/create)
+with your Dropbox Account (It need not to be the same account as the Dropbox you
+want to access)
+
+2. Choose an API => Usually this should be `Dropbox API`
+
+3. Choose the type of access you want to use => `Full Dropbox` or `App Folder`.
+If you want to use Team Folders, `Full Dropbox` is required
+([see here](https://www.dropboxforum.com/t5/Dropbox-API-Support-Feedback/How-to-create-team-folder-inside-my-app-s-folder/m-p/601005/highlight/true#M27911)).
+
+4. Name your App. The app name is global, so you can't use `rclone` for example
+
+5. Click the button `Create App`
+
+6. Switch to the `Permissions` tab. Enable at least the following permissions:
+`account_info.read`, `files.metadata.write`, `files.content.write`, `files.content.read`,
+`sharing.write`. The `files.metadata.read` and `sharing.read` checkboxes will be
+marked too. Click `Submit`
+
+7. Switch to the `Settings` tab. Fill `OAuth2 - Redirect URIs` as `http://localhost:53682/`
+and click on `Add`
+
+8. Find the `App key` and `App secret` values on the `Settings` tab. Use these
+values in rclone config to add a new remote or edit an existing remote.
+The `App key` setting corresponds to `client_id` in rclone config, the
+`App secret` corresponds to `client_secret`