### Install Documentation Dependencies Source: https://github.com/samschott/maestral/blob/main/CONTRIBUTING.md Install Maestral with the `docs` extra to get the required dependencies for building the documentation locally using Sphinx. ```bash pip3 install maestral[docs] ``` -------------------------------- ### Install Maestral Python Package Source: https://github.com/samschott/maestral/blob/main/README.md Recommended installation within a virtual environment. Includes instructions for upgrading and installing with GUI support. ```bash python3 -m venv maestral-venv source maestral-venv/bin/activate (maestral-venv)$ python3 -m pip install --upgrade maestral ``` ```bash (maestral-venv)$ python3 -m pip install --upgrade 'maestral[gui]' ``` -------------------------------- ### Maestral CLI: Initial Setup and Daemon Control Source: https://context7.com/samschott/maestral/llms.txt Commands for initial setup, launching the GUI, and starting/stopping the Maestral sync daemon. Includes options for foreground execution. ```bash # Initial setup and start maestral gui # Launch GUI (creates daemon if needed) maestral start # Start sync daemon in background maestral start -f # Start in foreground (blocks terminal) maestral stop # Stop sync daemon ``` -------------------------------- ### Maestral Configuration File Example Source: https://github.com/samschott/maestral/blob/main/docs/background/config_files.rst This is an example of the Maestral configuration file, showing various settings across different sections. Do not manually edit 'path' or 'excluded_items'. ```ini [main] # Config file version (not the Maestral version!) version = 15.0.0 [auth] # Unique Dropbox account ID. The account's email # address may change and is therefore not stored here. account_id = dbid:AABP7CC5bpYd8ghjIColDFrMoc9SdhACA4 # The keychain to use to store user credentials. If "automatic", # will be set automatically from available backends when # completing the OAuth flow. Mus be a fully qualified class name. keyring = keyring.backends.macOS.Keyring [app] # Level for desktop notifications: # 15 = FILECHANGE # 30 = SYNCISSUE # 40 = ERROR # 100 = NONE notification_level = 15 # Level for log messages: # 10 = DEBUG # 20 = INFO # 30 = WARNING # 40 = ERR0R log_level = 20 # Interval in sec to check for updates update_notification_interval = 604800 [sync] # The current Dropbox directory path = /Users/UserName/Dropbox (Maestral) # List of excluded files and folders excluded_items = ['/test_folder', '/sub/folder'] # Interval in sec to perform a full reindexing reindex_interval = 604800 # Maximum CPU usage per core max_cpu_percent = 20.0 # Sync history to keep in seconds keep_history = 604800 # Enable upload syncing upload = True # Enable download syncing download = True ``` -------------------------------- ### Install Maestral with GUI support Source: https://github.com/samschott/maestral/wiki/Home Install Maestral with the 'gui' extra to include the necessary components for the graphical user interface. This installs either maestral-qt for Linux or maestral-cocoa for macOS. ```console python3 -m pip install --upgrade maestral[gui] ``` -------------------------------- ### Install Maestral via Homebrew, PyPI, or Docker Source: https://context7.com/samschott/maestral/llms.txt Installation instructions for Maestral on macOS and Linux using different package managers. Includes options for GUI support and Docker. ```bash # Homebrew (macOS) brew install maestral ``` ```bash # PyPI (macOS + Linux), inside a virtual environment python3 -m venv maestral-venv source maestral-venv/bin/activate pip install --upgrade maestral ``` ```bash # With GUI support pip install --upgrade 'maestral[gui]' ``` ```bash # Docker (x86, arm/v7, arm64) docker pull maestraldbx/maestral ``` -------------------------------- ### Install python-systemd on Debian/Ubuntu/Mint Source: https://github.com/samschott/maestral/wiki/Installation-Requirements Installs the python-systemd package using apt-get, recommended for Debian, Ubuntu, and Mint systems. ```bash apt-get install python3-systemd ``` -------------------------------- ### Start Maestral with a specific config name Source: https://github.com/samschott/maestral/blob/main/README.md Use the `--config-name` option to start Maestral with a specific configuration file, allowing for multiple Dropbox accounts. ```console $ maestral start --config-name="personal" ``` ```console $ maestral start --config-name="work" ``` -------------------------------- ### Install Maestral with Syslog Support Source: https://github.com/samschott/maestral/wiki/Installation-Requirements Install Maestral with support for logging to the systemd journal. This requires the 'syslog' extra, which will install python-systemd. ```bash python3 -m pip install --upgrade maestral[syslog] ``` -------------------------------- ### Install Maestral with Homebrew Source: https://github.com/samschott/maestral/blob/main/README.md Use this command to install Maestral if you have Homebrew on your system. ```bash brew install maestral ``` -------------------------------- ### Install Development Dependencies Source: https://github.com/samschott/maestral/blob/main/CONTRIBUTING.md Install Maestral with the `dev` extra to include all necessary packages for development, such as linters and pre-commit hooks. ```bash pip3 install maestral[dev] ``` -------------------------------- ### Start Maestral GUI with a Specific Configuration Name Source: https://github.com/samschott/maestral/wiki/Multiple-Dropbox-Accounts Use the `--config-name` option to launch a Maestral GUI instance with a dedicated configuration. This is useful for managing separate Dropbox accounts. ```shell maestral gui --config-name="personal" ``` ```shell maestral gui --config-name="work" ``` -------------------------------- ### Install Maestral from PyPI Source: https://github.com/samschott/maestral/wiki/Home Install the Maestral Python package from PyPI. This command installs the core package and its dependencies for command-line usage. ```shell python3 -m pip install --upgrade maestral ``` -------------------------------- ### Install python-systemd on Fedora/RHEL/CentOS Source: https://github.com/samschott/maestral/wiki/Installation-Requirements Installs the python-systemd package using dnf, recommended for Fedora, RHEL, and CentOS systems. ```bash dnf install python3-systemd ``` -------------------------------- ### Start Maestral Daemon with a Specific Configuration Name Source: https://github.com/samschott/maestral/wiki/Multiple-Dropbox-Accounts Use the `--config-name` option to start a Maestral daemon instance with a dedicated configuration. This allows for background syncing of a specific Dropbox account. ```shell maestral start --config-name="personal" ``` -------------------------------- ### Install Maestral GUI on Raspberry Pi Source: https://github.com/samschott/maestral/wiki/Installation-Requirements Installs Maestral with GUI support on a Raspberry Pi using Python 3.6. This command is used after ensuring Python 3.6 and potentially PyQt5 are built. ```bash python3.6 -m pip install --upgrade maestral[gui] ``` -------------------------------- ### Install Maestral Docker Image Source: https://github.com/samschott/maestral/blob/main/README.md Pull the Maestral Docker image. Available for x86, arm/v7 (32bit), and arm64 platforms. ```bash docker pull maestraldbx/maestral ``` -------------------------------- ### Display Help for a Specific Maestral Command Source: https://github.com/samschott/maestral/wiki/Command-Line-Interface Use this to get detailed information, arguments, and options for any specific Maestral command. ```bash maestral COMMAND --help ``` -------------------------------- ### Run Pre-commit Hooks Source: https://github.com/samschott/maestral/blob/main/CONTRIBUTING.md Execute all pre-commit hooks to check code formatting, style, and type hints across the entire project. This can also be installed to run automatically on each commit. ```bash pre-commit run -a ``` -------------------------------- ### start_maestral_daemon_process / stop_maestral_daemon_process / MaestralProxy Source: https://context7.com/samschott/maestral/llms.txt Start and stop the Maestral sync daemon as a background process, and communicate with it via a transparent IPC proxy. ```APIDOC ## `start_maestral_daemon_process` / `stop_maestral_daemon_process` / `MaestralProxy` — Daemon management Start and stop the Maestral sync daemon as a background process, and communicate with it via a transparent IPC proxy. ```python from maestral.daemon import ( start_maestral_daemon_process, stop_maestral_daemon_process, MaestralProxy, Start, Stop, is_running, ) # Start the daemon (idempotent: returns AlreadyRunning if already up) result = start_maestral_daemon_process("maestral", timeout=30) if result == Start.Ok: print("Daemon started.") elif result == Start.AlreadyRunning: print("Daemon was already running.") elif result == Start.Failed: print("Failed to start daemon.") # Interact with the running daemon through a transparent Pyro5 proxy with MaestralProxy("maestral") as m: print(m.status) # forwarded to the daemon print(m.connected) activity = m.get_activity(limit=5) for event in activity: print(event.dbx_path) # Stop the daemon gracefully (SIGTERM then SIGKILL if needed) result = stop_maestral_daemon_process("maestral", timeout=10) if result == Stop.Ok: print("Daemon stopped cleanly.") elif result == Stop.Killed: print("Daemon was force-killed.") elif result == Stop.NotRunning: print("Daemon was not running.") print("Running?", is_running("maestral")) # False ``` ``` -------------------------------- ### Manage systemd User Service for Maestral Source: https://context7.com/samschott/maestral/llms.txt Commands to reload the systemd daemon, enable and start the Maestral service, check its status, and follow its logs. ```bash # Enable and manage the service systemctl --user daemon-reload systemctl --user enable --now maestral systemctl --user status maestral journalctl --user -u maestral -f # Follow logs ``` -------------------------------- ### Maestral.start_sync / Maestral.stop_sync / Maestral.pause / Maestral.resume Source: https://context7.com/samschott/maestral/llms.txt Controls the lifecycle of the background synchronization process. Allows starting, stopping, pausing, and resuming sync threads. ```APIDOC ## Maestral.start_sync / Maestral.stop_sync / Maestral.pause / Maestral.resume — Sync lifecycle control Start, stop, pause, and resume the background sync threads. ```python from maestral.main import Maestral from maestral.exceptions import NotLinkedError, NoDropboxDirError m = Maestral(config_name="maestral") try: m.start_sync() print("Sync started. running =", m.running) # True # Pause (user-initiated, keeps threads alive) # Note: pause/resume are CLI-level concepts mapped to manager.autostart m.stop_sync() print("Sync stopped. paused =", m.paused) # True m.start_sync() print("Sync restarted.") except NotLinkedError: print("Link an account first.") except NoDropboxDirError: print("Set up a local Dropbox directory first.") ``` ``` -------------------------------- ### Manual systemd Service Configuration for Maestral Source: https://github.com/samschott/maestral/wiki/Systemd-Integration Manually create a systemd user service file to manage the Maestral daemon. This allows Maestral to start automatically on login and integrate with systemd's notification system. ```ini [Unit] Description = Maestral daemon Documentation = https://github.com/SamSchott/maestral-dropbox/wiki [Service] Type = notify NotifyAccess = exec ExecStart = /usr/bin/maestral start -f ExecStop = /usr/bin/maestral stop ExecStopPost=/usr/bin/env bash -c "if [ ${SERVICE_RESULT} != success ];\nthen notify-send Maestral 'Daemon failed'; fi" WatchdogSec = 30s [Install] WantedBy = default.target ``` -------------------------------- ### List, Diff, and Restore File Revisions with Maestral Source: https://context7.com/samschott/maestral/llms.txt Use `list_revisions` to get historical versions, `get_file_diff` to compare them, and `restore` to revert to an older version. Note that `get_file_diff` may raise `UnsupportedFileTypeForDiff` for certain file types. ```python from maestral.main import Maestral from maestral.exceptions import UnsupportedFileTypeForDiff m = Maestral(config_name="maestral") # List the last 5 revisions revisions = m.list_revisions("/Notes/todo.txt", limit=5) for rev in revisions: print(f"Rev: {rev.rev} Modified: {rev.client_modified} Size: {rev.size}") # Compare two revisions as a unified diff old_rev = revisions[-1].rev new_rev = revisions[0].rev try: diff_lines = m.get_file_diff(old_rev=old_rev, new_rev=new_rev) print("".join(diff_lines)) except UnsupportedFileTypeForDiff as e: print(f"Cannot diff: {e.title}") # Restore the oldest revision restored = m.restore("/Notes/todo.txt", rev=old_rev) print(f"Restored to rev {restored.rev} ({restored.client_modified})") ``` -------------------------------- ### Maestral Initialization and Linking Source: https://github.com/samschott/maestral/blob/main/docs/index.rst Demonstrates how to initialize a Maestral instance, obtain an authorization URL, and link it to a Dropbox account. ```APIDOC ## Maestral Initialization and Linking ### Description Initialize a Maestral instance and link it to a Dropbox account using the OAuth2 PKCE flow. ### Method Python SDK ### Code ```python from maestral.main import Maestral # Initialize a Maestral instance with a configuration name m = Maestral(config_name="private") # Get the Dropbox authorization URL url = m.get_auth_url() print(f"Please go to {url} to retrieve a Dropbox authorization token.") # Prompt user for the auth token token = input("Enter auth token: ") # Link the instance to the Dropbox account using the token res = m.link(token) # Check the result of the linking process if res == 0: print("Successfully linked to Dropbox.") # Create a local Dropbox directory and start syncing m.create_dropbox_directory("~/Dropbox (Private)") m.start_sync() else: print(f"Linking failed with code: {res}") ``` ### Parameters #### Initialization Parameters - **config_name** (str) - The name of the configuration to use or create. #### Linking Parameters - **token** (str) - The authorization token obtained from Dropbox. ### Return Values - **m.link(token)**: Returns 0 on success, 1 for an invalid code, and 2 for connection errors. ### Notes - Configuration files will be created on-demand. - Credentials will be saved in the system keyring upon successful linking. ``` -------------------------------- ### Manage Maestral Accounts and Settings Source: https://context7.com/samschott/maestral/llms.txt Use these commands to start/stop accounts, manage configuration files, and unlink accounts. ```bash maestral start -c personal # Start "personal" account daemon ``` ```bash maestral start -c work # Start "work" account daemon ``` ```bash maestral config-files # List all config files and linked accounts ``` ```bash maestral auth unlink -c work # Unlink "work" account ``` -------------------------------- ### Control Maestral System Integration Source: https://context7.com/samschott/maestral/llms.txt Manage autostart behavior, view and clear logs, and control desktop notifications. ```bash maestral autostart -Y # Enable start on login (launchd/systemd) ``` ```bash maestral autostart -N # Disable start on login ``` ```bash maestral log show # View log ``` ```bash maestral log clear # Clear log ``` ```bash maestral notify snooze 60 # Snooze desktop notifications for 60 min ``` -------------------------------- ### Display Maestral CLI Help Source: https://github.com/samschott/maestral/wiki/Command-Line-Interface Run this command to see an overview of all available Maestral commands and options. ```bash maestral -h ``` -------------------------------- ### Initialize Maestral Instance Source: https://github.com/samschott/maestral/blob/main/docs/index.rst Import the main module and initialize a Maestral instance with a configuration name. Config files are created on-demand. ```python from maestral.main import Maestral m = Maestral(config_name="private") ``` -------------------------------- ### Maestral.__init__ Source: https://context7.com/samschott/maestral/llms.txt Instantiates a Maestral API object for a given configuration name. This allows managing multiple Dropbox accounts simultaneously. ```APIDOC ## Maestral.__init__ — Instantiate the public API Creates a `Maestral` instance for the given named configuration. Multiple instances with different `config_name` values can coexist to sync multiple Dropbox accounts simultaneously. ```python from maestral.main import Maestral # Create instance for a "work" account config m = Maestral(config_name="work") print(m.version) # e.g. "1.9.6" print(m.config_name) # "work" print(m.pending_link) # True if no account is linked yet ``` ``` -------------------------------- ### Manage Local Dropbox Directory with Maestral Source: https://context7.com/samschott/maestral/llms.txt Use `create_dropbox_directory` to set up the initial local sync folder and `move_dropbox_directory` to relocate it. The latter automatically pauses and resumes sync. Handle `FileExistsError` if the target directory already exists and `OSError` for other move failures. ```python from maestral.main import Maestral m = Maestral(config_name="maestral") # Initial setup: create the local Dropbox folder before first sync m.create_dropbox_directory("~/Dropbox") # Later: move the folder to a new location (sync is paused/resumed automatically) try: m.move_dropbox_directory("~/ExternalDrive/Dropbox") print(f"Dropbox folder moved to: {m.dropbox_path}") except FileExistsError: print("Target path already exists.") except OSError as e: print(f"Move failed: {e}") ``` -------------------------------- ### Get Sync Status of a Local File Source: https://github.com/samschott/maestral/wiki/Command-Line-Interface This command takes an absolute path to a local file and returns its current sync status. If syncing is paused or Maestral is not running, it returns 'unwatched'. ```bash maestral file-status /path/to/local/file ``` -------------------------------- ### Catching Maestral API Errors in Python Source: https://context7.com/samschott/maestral/llms.txt This example demonstrates how to catch and handle various Maestral-specific exceptions. It's recommended to catch specific errors before the general MaestralApiError for more granular control. ```python from maestral.main import Maestral from maestral.exceptions import ( MaestralApiError, NotLinkedError, NoDropboxDirError, DropboxAuthError, TokenExpiredError, TokenRevokedError, InsufficientSpaceError, InsufficientPermissionsError, BusyError, NotFoundError, ConnectionError, ) m = Maestral(config_name="maestral") try: m.start_sync() entries = m.list_folder("/") link = m.create_shared_link("/important.txt") except NotLinkedError as e: print(f"Not linked: {e.title} — {e.message}") except NoDropboxDirError as e: print(f"No local folder: {e.title} — {e.message}") except TokenExpiredError as e: print(f"Token expired: {e.title} — re-link the account") except TokenRevokedError as e: print(f"Token revoked: {e.title} — re-link the account") except DropboxAuthError as e: print(f"Auth error: {e.title} — {e.message}") except InsufficientSpaceError as e: print(f"Out of space: {e.title}") except BusyError as e: print(f"Busy: {e.title} — {e.message}") except NotFoundError as e: print(f"Not found: {e.dbx_path}") except ConnectionError: print("No connection to Dropbox servers.") except MaestralApiError as e: # Catch-all for any other Maestral error print(f"Error [{type(e).__name__}]: {e.title} — {e.message}") ``` -------------------------------- ### List Maestral configuration files and accounts Source: https://github.com/samschott/maestral/blob/main/README.md The `maestral config-files` command lists all currently linked accounts, their associated configuration names, and their file paths. ```console $ maestral config-files Config name Account Path maestral user@gmail.com ~/Library/Application Support/maestral/maestral.ini private user@mycorp.org ~/Library/Application Support/maestral/private.ini ``` -------------------------------- ### Get File/Folder Metadata with Maestral Source: https://context7.com/samschott/maestral/llms.txt Fetch live metadata for any path on Dropbox using `get_metadata`. The function returns either `FileMetadata` or `FolderMetadata` objects. Handle `NotFoundError` if the specified item does not exist. ```python from maestral.main import Maestral from maestral.core import FileMetadata, FolderMetadata from maestral.exceptions import NotFoundError m = Maestral(config_name="maestral") try: md = m.get_metadata("/Documents/contract.pdf") if isinstance(md, FileMetadata): print(f"File: {md.path_display}") print(f"Size: {md.size} bytes") print(f"Rev: {md.rev}") print(f"Hash: {md.content_hash}") elif isinstance(md, FolderMetadata): print(f"Folder: {md.path_display}, id={md.id}") except NotFoundError: print("Item does not exist on Dropbox.") ``` -------------------------------- ### Control Maestral Sync Lifecycle Source: https://context7.com/samschott/maestral/llms.txt Manage the background sync threads by starting, stopping, pausing, or resuming the synchronization process. Handles potential errors like not being linked or lacking a Dropbox directory. ```python from maestral.main import Maestral from maestral.exceptions import NotLinkedError, NoDropboxDirError m = Maestral(config_name="maestral") try: m.start_sync() print("Sync started. running =", m.running) # True # Pause (user-initiated, keeps threads alive) # Note: pause/resume are CLI-level concepts mapped to manager.autostart m.stop_sync() print("Sync stopped. paused =", m.paused) # True m.start_sync() print("Sync restarted.") except NotLinkedError: print("Link an account first.") except NoDropboxDirError: print("Set up a local Dropbox directory first.") ``` -------------------------------- ### Instantiate Maestral API Source: https://context7.com/samschott/maestral/llms.txt Create a Maestral instance for a specific configuration name. This allows managing multiple Dropbox accounts simultaneously. ```python from maestral.main import Maestral # Create instance for a "work" account config m = Maestral(config_name="work") print(m.version) # e.g. "1.9.6" print(m.config_name) # "work" print(m.pending_link) # True if no account is linked yet ``` -------------------------------- ### Manage Maestral Daemon Process Source: https://context7.com/samschott/maestral/llms.txt Starts, stops, and interacts with the Maestral sync daemon as a background process using an IPC proxy. Includes checks for daemon status and handling of different start/stop outcomes. ```python from maestral.daemon import ( start_maestral_daemon_process, stop_maestral_daemon_process, MaestralProxy, Start, Stop, is_running, ) # Start the daemon (idempotent: returns AlreadyRunning if already up) result = start_maestral_daemon_process("maestral", timeout=30) if result == Start.Ok: print("Daemon started.") elif result == Start.AlreadyRunning: print("Daemon was already running.") elif result == Start.Failed: print("Failed to start daemon.") # Interact with the running daemon through a transparent Pyro5 proxy with MaestralProxy("maestral") as m: print(m.status) # forwarded to the daemon print(m.connected) activity = m.get_activity(limit=5) for event in activity: print(event.dbx_path) # Stop the daemon gracefully (SIGTERM then SIGKILL if needed) result = stop_maestral_daemon_process("maestral", timeout=10) if result == Stop.Ok: print("Daemon stopped cleanly.") elif result == Stop.Killed: print("Daemon was force-killed.") elif result == Stop.NotRunning: print("Daemon was not running.") print("Running?", is_running("maestral")) # False ``` -------------------------------- ### Add excluded item via CLI - Maestral Source: https://github.com/samschott/maestral/wiki/Initial-Setup Use this command to manually add files or folders to the exclusion list after initial setup. Use 'maestral excluded list' to view current exclusions. ```bash maestral excluded add ``` -------------------------------- ### List All Existing Maestral Configurations Source: https://github.com/samschott/maestral/wiki/Multiple-Dropbox-Accounts Run the `maestral configs` command to view a list of all currently active configurations for Maestral. ```shell maestral configs ``` -------------------------------- ### Monitor Status Changes with Long Polling Source: https://context7.com/samschott/maestral/llms.txt Use `status_change_longpoll` to efficiently detect status changes without busy-waiting. Ideal for frontend applications polling for updates. Requires starting sync and running in a separate thread. ```python from maestral.main import Maestral import threading m = Maestral(config_name="maestral") m.start_sync() def watch_status(): while True: changed = m.status_change_longpoll(timeout=30) if changed: print(f"Status changed: {m.status}") if m.fatal_errors: for err in m.fatal_errors: print(f"Fatal error: {err.title} - {err.message}") m.clear_fatal_errors() t = threading.Thread(target=watch_status, daemon=True) t.start() ``` -------------------------------- ### Include a folder for syncing with Maestral CLI Source: https://github.com/samschott/maestral/wiki/Selective-Sync Use this command to re-enable syncing for a previously excluded folder. The folder and its contents will be downloaded to your local drive if they are not already present. ```shell $ maestral excluded remove Pictures ``` -------------------------------- ### Set Bandwidth Limits with Maestral API Source: https://context7.com/samschott/maestral/llms.txt Sets per-direction bandwidth caps in bytes per second. A value of 0.0 indicates unlimited bandwidth. Demonstrates setting upload limits and then removing all limits. ```python from maestral.main import Maestral m = Maestral(config_name="maestral") # Limit uploads to 1 MB/s, leave downloads unlimited m.bandwidth_limit_up = 1_000_000.0 m.bandwidth_limit_down = 0.0 print(f"Upload limit: {m.bandwidth_limit_up} B/s") print(f"Download limit: {m.bandwidth_limit_down} B/s") # Remove all limits m.bandwidth_limit_up = 0.0 m.bandwidth_limit_down = 0.0 ```