A native Quickshell plugin that brings MEGA storage, transfers, and folder synchronization to the Omarchy bar. Inspired by the MEGAsync panel, it follows your Omarchy theme, fonts, and scaling.
The plugin uses MEGAcmd only. The MEGAsync desktop application is not required.
- Account storage usage and capacity.
- Transfer queue and progress, with pause, resume, and cancellation controls.
- File and folder uploads, plus downloads from remote paths or public links.
- Bidirectional folder syncs, with pause, resume, and local folder shortcuts.
- In-memory activity history for panel actions and connection changes.
- Shortcuts to MEGA on the web, account upgrades, and the MEGAcmd terminal.
- English, Portuguese, and Spanish localization, with English as the fallback.
- Omarchy with
omarchy-shelland plugin support. - Qt Quick Dialogs, provided by the desktop's Qt installation.
/usr/bin/python3.- MEGAcmd, with
mega-execandmega-cmdinstalled in/usr/binor/usr/local/bin. - Git to clone this repository.
Install the official MEGAcmd package for your distribution using the MEGA download page. If you use the Arch AUR package, you can install it through Omarchy:
omarchy pkg aur add megacmd-binCheck that both executables are available:
command -v mega-exec
command -v mega-cmdUse Omarchy's native plugin manager:
omarchy plugin add https://github.com/vitorpacheco/omarchy-mega.git --enableReview the code when prompted. Omarchy clones the public repository into ~/.config/omarchy/plugins/io.github.vitorpacheco.mega, validates the manifest, and enables the M icon in the right section of the bar. It does not run installation hooks or install MEGAcmd automatically.
Run the installation command as your normal desktop user. The plugin has no custom installer or setup hooks.
Click M → Sign in to MEGA. In the MEGAcmd terminal, enter:
login your@email.com
MEGAcmd prompts for your password and, if enabled, your two-factor authentication code. The plugin does not handle or store your credentials.
Once signed in, close only the terminal while leaving the background service running:
quit --only-shell
The panel detects the session automatically. You can reopen the terminal from ⋮ → Account / MEGA terminal, or launch mega-cmd from a regular terminal.
Open the widget settings in Omarchy, or edit its existing entry under bar.layout in ~/.config/omarchy/shell.json:
{
"id": "io.github.vitorpacheco.mega",
"refreshIntervalSec": 15,
"language": "auto"
}This is a single widget entry, not a replacement for the entire shell.json file.
| Setting | Default | Description |
|---|---|---|
refreshIntervalSec |
15 |
Polling interval while the panel is closed, in seconds. The settings editor accepts 5–300. |
language |
auto |
auto, en (English), pt (Portuguese), or es (Spanish). |
With auto, the panel follows the system locale. Unsupported locales and missing translations fall back to English. The selected language also applies to plugin messages, known status labels, numbers, and activity timestamps. Unknown MEGAcmd diagnostics remain verbatim, and native file chooser controls follow the system language.
While the panel is open, transfers and syncs refresh every 5 seconds. Storage is queried separately once per minute, so a slow storage response does not block the rest of the panel. Failed storage requests retry after 1–5 minutes; manual refresh can retry sooner. The last successful storage value remains visible with a “Last known value” label after a failure and is cleared when the account or backend changes. Each MEGAcmd command has a 25-second timeout, and overlapping polls are avoided. Settings changes are picked up by the shell automatically.
On the Transfers tab:
- Choose Upload, select a local file or folder, and enter an existing destination folder in MEGA.
- Choose Download, enter a remote path or public MEGA link, and select an existing local destination folder.
- Use the transfer controls to pause, resume, or cancel queued work. Cancellation requires a second click to confirm.
Remote paths start with /, such as /Documents. Create remote destination folders on the MEGA website or in the MEGAcmd terminal:
mkdir /Documents
The queue displays up to 100 transfers. Its counter is not the account's transfer quota.
- Create or choose an existing local folder.
- Create or choose an existing remote folder in MEGA.
- Open Syncs → + Sync folder.
- Enter the remote path and select the local folder.
- Click Confirm.
After a successful request, the form closes and returns to the sync list. If the request fails, the form stays open with the error message. Use Pause, Resume, or Open folder on the sync entry as needed.
Synchronization is bidirectional: changes and deletions propagate between the local and remote folders. MEGAcmd and MEGAsync have separate sessions, queues, and sync configurations; the plugin does not import the desktop application's configuration. Avoid syncing the same local folder with both clients simultaneously.
Activity records panel actions and connection changes in memory. It is not MEGA's account notification inbox and is cleared when the plugin reloads.
- Escape: close the current form or panel.
- Tab: move between controls.
- Middle-click the bar icon: refresh.
You can also toggle the panel through IPC:
omarchy-shell mega toggleMEGAcmd is not detected: the plugin only runs MEGAcmd from /usr/bin or /usr/local/bin, and only when the executable and every parent directory are owned by root and not writable by other users. Your PATH is ignored. Install MEGAcmd with your system package manager, then check ls -l /usr/bin/mega-exec /usr/bin/mega-cmd.
The panel asks you to sign in: run mega-cmd and use login your@email.com. Being signed in to the MEGAsync desktop application does not sign you in to MEGAcmd.
A sync reports that its local folder is unavailable: check whether the folder was moved, renamed, or deleted. Restore the intended local folder before resuming, or remove the obsolete sync configuration and create a new one. To remove only a sync configuration, use a regular terminal:
mega-sync
mega-sync --delete <SYNC_ID>Replace <SYNC_ID> with the ID shown by the first command. This removes the sync configuration, not the files in MEGA.
A sync already exists: check the Syncs tab or run mega-sync before submitting the same folder again.
Plugin changes do not appear: rescan the plugins:
omarchy-shell shell rescanPluginsIf the shell still uses cached code, restart it and ensure the plugin is enabled:
omarchy restart shell
omarchy plugin enable io.github.vitorpacheco.megaUse the native update command:
omarchy plugin update io.github.vitorpacheco.megaOmarchy fetches the repository, lets you review the changes, and updates the installed checkout.
omarchy plugin disable io.github.vitorpacheco.megaTo uninstall the plugin files:
omarchy plugin remove io.github.vitorpacheco.megaDisabling or removing the panel does not stop MEGAcmd or remove its sync configurations. Manage those separately through MEGAcmd.
Like other Omarchy shell plugins, this plugin runs unsandboxed with your desktop user's permissions. Its QML files run inside the existing omarchy-shell process; it does not start another shell instance during normal use.
The panel runs its bridge as /usr/bin/python3 -I with a cleared environment containing only a fixed PATH=/usr/bin and a UTF-8 locale, so user PATH entries, loader variables such as LD_PRELOAD, and Python variables such as PYTHONPATH never reach it. The bridge resolves mega-exec and mega-cmd only from /usr/bin or /usr/local/bin, accepts them only if the executable and every parent directory are root-owned and not writable by group or others, and runs that exact absolute path. There is no setting to choose another executable. MEGAcmd runs with a closed environment: HOME from the user database, PATH limited to its own directory and /usr/bin, and the C locale. MEGAcmd owns authentication, network connections to MEGA, file transfers, and the persistent mega-cmd-server background process. Commands run with the current user's file access. The plugin itself does not require root, read MEGAcmd's credential cache, or store passwords or transfer links in a plugin log. Each MEGAcmd call runs in its own process group under a 25-second deadline, with stdout capped at 2 MiB and stderr at 64 KiB; on timeout or overflow the whole group is terminated, killed, and reaped. At most 100 transfers and 100 syncs, with cells up to 4,096 characters, are passed to the bar widget.
The account shortcut opens the resolved mega-cmd path through /usr/bin/omarchy launch tui, and folder shortcuts use /usr/bin/xdg-open. Both start with a cleared environment that keeps only the desktop session variables they need (such as HOME, WAYLAND_DISPLAY, XDG_RUNTIME_DIR, and DBUS_SESSION_BUS_ADDRESS) and a fixed PATH of /usr/share/omarchy/bin:/usr/bin. Web shortcuts open MEGA URLs in the default browser. Installing system dependencies may require administrator authentication; that is separate from installing or running this plugin. There are no remote build steps or downloaded scripts executed by the plugin.
Run these commands from the repository root. Node.js is required only for the localization checks. The QML tests require an active Omarchy Wayland session; they stage a copy of the plugin whose bridge resolves a fake MEGAcmd executable instead of the system one.
omarchy plugin validate .
python3 -m unittest discover -s tests -v
node tests/test_i18n.cjs
python3 tests/qml_smoke.py
python3 tests/qml_storage.pyTo inspect the actual backend response, run:
/usr/bin/python3 -I bin/mega_bridge.py statusTests cover parsing, errors, timeouts, output and row limits, process-group cleanup, trusted executable resolution, the closed MEGAcmd environment, command construction, localization, and form completion. Real transfers require an authenticated session and user-selected files.