This file defines the functions to configure and interact with Maestral from the command line. Some imports are deferred to the functions that required them in order to reduce the startup time of individual CLI commands.

Module Contents

maestral.cli.stop_daemon_with_cli_feedback(config_name: str)None[source]

Wrapper around daemon.stop_maestral_daemon_process() with command line feedback.

maestral.cli.select_dbx_path_dialog(config_name: str, default_dir_name: Optional[str] = None, allow_merge: bool = False)str[source]

A CLI dialog to ask for a local Dropbox folder location.

  • config_name – The configuration to use for the default folder name.

  • default_dir_name – The default directory name. Defaults to “Dropbox ({config_name})” if not given.

  • allow_merge – If True, allows the selection of an existing folder without deleting it. Defaults to False.


Path given by user.

A CLI dialog for linking a Dropbox account.


m – Proxy to Maestral daemon.


Checks if updates are available by reading the cached release number from the config file and notifies the user. Prints an update note to the command line.

maestral.cli.check_for_fatal_errors(m: Union[‘MaestralProxy’, ‘Maestral’])bool[source]

Checks the given Maestral instance for fatal errors such as revoked Dropbox access, deleted Dropbox folder etc. Prints a nice representation to the command line.


m – Proxy to Maestral daemon or Maestral instance.


True in case of fatal errors, False otherwise.

maestral.cli.convert_py_errors(func: Callable) → Callable[source]

Decorator that catches a MaestralApiError and prints it as a useful message to the command line instead of printing the full stacktrace.

class maestral.cli.DropboxPath(file_okay: bool = True, dir_okay: bool = True)[source]

Bases: click.ParamType

A command line parameter representing a Dropbox path

  • file_okay – Controls if a file is a possible value.

  • dir_okay – Controls if a directory is a possible value.

name = Dropbox path[source]
class maestral.cli.ConfigName(existing: bool = True)[source]

Bases: click.ParamType

A command line parameter representing a Dropbox path


existing – If True require an existing config, otherwise create a new config on demand.

name = config[source]
convert(self, value: Optional[str], param: Optional[click.Parameter], ctx: Optional[click.Context]) → Optional[str][source]
class maestral.cli.OrderedGroup[source]

Bases: click.Group

Click command group with customizable order of help output.

command(self, *args, **kwargs) → Callable[source]

Behaves the same as click.Group.command() except captures a section name for listing command names in help.

group(self, *args, **kwargs) → Callable[source]

Behaves the same as except captures a section name for listing command names in help.

format_commands(self, ctx: click.Context, formatter: click.HelpFormatter)None[source]

Extra format methods for multi methods that adds all the commands after the options.

maestral.cli.start(foreground: bool, verbose: bool, config_name: str)None[source]
maestral.cli.stop(config_name: str)None[source]
maestral.cli.gui(config_name: str)None[source]
maestral.cli.pause(config_name: str)None[source]
maestral.cli.resume(config_name: str)None[source]
maestral.cli.auth_status(config_name: str)None[source]
maestral.cli.status(config_name: str)None[source]
maestral.cli.filestatus(local_path: str, config_name: str)None[source]
maestral.cli.activity(config_name: str)None[source]
maestral.cli.history(config_name: str)None[source] bool, dropbox_path: str, include_deleted: bool, config_name: str)None[source]
maestral.cli.config_files(clean: bool)None[source]
maestral.cli.autostart(yes: bool, no: bool, config_name: str)None[source]
maestral.cli.excluded_list(config_name: str)None[source]
maestral.cli.excluded_add(dropbox_path: str, config_name: str)None[source]
maestral.cli.excluded_remove(dropbox_path: str, config_name: str)None[source]
maestral.cli.notify_level(level_name: str, config_name: str)None[source]
maestral.cli.notify_snooze(minutes: int, config_name: str)None[source]
maestral.cli.move_dir(new_path: str, config_name: str)None[source]
maestral.cli.rebuild_index(config_name: str)None[source]
maestral.cli.revs(dropbox_path: str, limit: int, config_name: str)None[source]
maestral.cli.diff(dropbox_path: str, rev: List[str], no_color: bool, no_pager: bool, limit: int, config_name: str)None[source]
maestral.cli.restore(dropbox_path: str, rev: str, limit: int, config_name: str)None[source]
maestral.cli.log_show(external: bool, config_name: str)None[source]
maestral.cli.log_clear(config_name: str)None[source]
maestral.cli.log_level(level_name: str, config_name: str)None[source]
maestral.cli.config_get(key: str, config_name: str)None[source]
maestral.cli.config_set(key: str, value: str, config_name: str)None[source]