DOCSEARCHbyAlgolia
Submit Docs

dbxcli

repository·master·Indexed 22 days ago

https://github.com/dropbox/dbxcli

A scriptable command-line interface for Dropbox designed for terminal users, CI/CD pipelines, and automation workflows. It supports file management, shared link manipulation, and team-scoped operations. The tool provides structured JSON output (schema v1) for machine-readable results and command discovery via JSON help manifests.

Tokens
28.6K
Snippets
108
Records
143
Agent score
77%

What's inside dbxcli

  1. Manage Dropbox shared links with dbxcli share-link

    master

    The dbxcli share-link command provides a suite of subcommands to manage Dropbox shared links. You can use it to create, list, inspect, download, update, and revoke shared links via the CLI.

    Available subcommands include:

    • create: Create a new shared link.
    • download: Download content from a shared link.
    • info: Display information about a specific shared link.
    • list: List existing shared links.
    • revoke: Revoke existing shared links.
    • update: Update settings for an existing shared link.

  2. Use dbxcli for Dropbox automation and terminal workflows

    master
    dbxcli is a scriptable command-line interface for managing Dropbox files, folders, shared links, and team workflows. It is designed for both human interaction (text output) and automation (structured JSON output). It supports pipe-friendly transfers, refreshable OAuth login, and direct-token automation for CI/CD jobs and agent-style workflows.

  3. Use JSON help manifests for command discovery

    master

    JSON help is a machine-readable surface that does not require Dropbox authentication and works for all commands, even those that do not support structured execution output. Use it to discover command paths, arguments, flags, input schemas, aliases, and more.

    To check if a command supports structured command output via JSON help, inspect results[].result.supports_structured_output.

    dbxcli --help --output=json
dbxcli put --help --output=json
dbxcli share-link create --help --output=json
dbxcli --output=json help share-link create

  4. Use JSON output for automation

    master

    For scripting and automation, dbxcli provides structured machine-readable output using the --output=json flag. This flag works for both command execution results and help discovery.

    Structured Command Execution

    Use --output=json to receive stable schema v1 success and error envelopes.

    dbxcli ls --output=json /

    Machine-Readable Help Discovery

    Use --help --output=json to discover command paths, arguments, flags, aliases, input schemas, and supported automation features.

    dbxcli --help --output=json
dbxcli put --help --output=json
    dbxcli ls --output=json /

  5. How Command Manifest v1 works

    master

    The Command Manifest is the canonical surface for discovering command structures via JSON help (e.g., dbxcli <cmd> --help --output=json).

    Each manifest result has status: "described", kind: "command", and a result object that validates against manifest.schema.json.

    Key features of Manifest v1:

    • input_schema: A JSON Schema object describing the command's arguments and flags. This is intended for automation planners to validate inputs before building a CLI invocation.
    • x-cli-name: Preserves the original CLI name for flags/arguments.
    • schema_refs:
      • command_success_schema: Points to the command's definition in commands.schema.json.
      • command_contract: Points to the source entry in commands.json.
    • dropbox_scopes: Best-effort audited list of required scopes.
    • args and flags: Enriched metadata including enum values, conflicts, and sensitive input markers (writeOnly, x-sensitive).

    Note: Commands like login and completion do not support structured command-result JSON yet, but their help output is still available as a JSON manifest.

  6. Quickstart with dbxcli

    master

    Follow these steps to authenticate and perform basic file operations:

    1. Login: Authenticate your session. dbxcli login
    2. List files: View the contents of the root directory. dbxcli ls /
    3. Upload a file: Upload a local file to a remote path. dbxcli put local.txt /remote.txt
    4. Download a file: Download a remote file to your local machine. dbxcli get /remote.txt ./remote.txt
    5. Create a shared link: Generate a link for a remote file. dbxcli share-link create /remote.txt

    Note for Team Accounts: If uploading to / fails, it may be because the root namespace is not writable. Run dbxcli ls / to identify writable personal or team folders and upload to those instead.

    dbxcli login
dbxcli ls /
dbxcli put local.txt /remote.txt
dbxcli get /remote.txt ./remote.txt
dbxcli share-link create /remote.txt

  7. Manage Dropbox teams with dbxcli team

    master

    The dbxcli team command provides a suite of subcommands for team management, including adding/removing members, viewing team information, and listing groups or members.

    Note that these commands are part of the team management feature set and may require specific Dropbox permissions (scopes) depending on the action being performed.

    dbxcli team [subcommand] [options]

  8. Log in to Dropbox with dbxcli login

    master

    Use the login command to authenticate and save your Dropbox credentials. By default, logging in stores credentials for regular Dropbox user commands.

    Depending on your account type and the commands you intend to run, you can specify a token-type argument:

    • personal: Default. Stores credentials for regular Dropbox user commands.
    • team-access: Use this for commands prefixed with --as-member.
    • team-manage: Use this for team management commands.

    If you are using a specific Dropbox app key, provide it using the --app-key flag.

    dbxcli login [personal|team-access|team-manage] [--app-key <string>]

  9. Enable autocompletion for the fish shell

    master

    You can generate autocompletion scripts for the fish shell to improve your command-line experience with dbxcli.

    To load completions immediately in your current shell session, pipe the output to source:

    dbxcli completion fish | source

    To make completions permanent so they are available in every new session, write the output to your fish completions directory:

    dbxcli completion fish > ~/.config/fish/completions/dbxcli.fish

    Note: You must start a new shell session for the permanent setup to take effect.

  10. Enable zsh autocompletion for dbxcli

    master

    To use autocompletion for dbxcli in the zsh shell, you must first ensure shell completion is enabled in your environment. If not already enabled, add the following to your ~/.zshrc file:

    echo "autoload -U compinit; compinit" >> ~/.zshrc

    Then, you can load completions for the current session or permanently as described below.

    echo "autoload -U compinit; compinit" >> ~/.zshrc

  11. Automate dbxcli with JSON output

    master

    For shell scripts and CI jobs, use the --output=json flag to receive structured command results. In this mode, the command result and error envelopes are written to stdout, while human-facing warnings, progress, diagnostics, and verbose logs are written to stderr.

    To check if a command supports structured output, use the JSON help manifest:

    dbxcli <command> --help --output=json

    Successful JSON responses follow a stable envelope containing ok, schema_version, command, input, results, and warnings. Error responses include an error object with a message and a machine-readable code.

    dbxcli ls --output=json /
dbxcli account --output=json
dbxcli logout --output=json

  12. Generate autocompletion scripts for dbxcli

    master

    You can generate autocompletion scripts for various shells to improve your command-line experience with dbxcli. Supported shells include bash, zsh, fish, and powershell.

    After generating the script, you must follow your specific shell's instructions to source or install the script so that dbxcli commands and flags are automatically completed when you press the Tab key.

    dbxcli completion [bash|zsh|fish|powershell] [flags]