MEGAcmd

CLI agent for MEGA.nz. Activate when the user asks to upload files to MEGA, download from MEGA, sync local folders with MEGA cloud, schedule backups to MEGA, share files via MEGA public links, mount MEGA as a local folder (FUSE on Linux), serve files via MEGA WebDAV/FTP, or manage MEGA account settings.

Alefsander Ribeiro@alefsanderribeiro

Install

openclaw skills install @alefsanderribeiro/megacmd

MEGAcmd — AI Agent Guide

What this skill does

Instructions for agents to use MEGAcmd, the official CLI interface for MEGA.nz. Covers file operations, bidirectional sync, scheduled backups, WebDAV/FTP servers, FUSE mount, sharing, and account management.

Important: This skill is for MEGAcmd USERS. If the goal is to BUILD, DEBUG, or CONTRIBUTE to the source code, do not activate this skill.

When to use

The user asks to upload/download files on MEGA.nz
The user wants to sync local folders ↔ MEGA cloud
The user needs scheduled backups with version retention
The user wants to share files via public links
The user needs to serve files via WebDAV or FTP
The user wants to mount a MEGA folder as a local filesystem (Linux)
The user needs to manage account, password, sessions, or contacts
The user reports that sync is not working

When NOT to use

The user wants to use the MEGA web interface (browser)
The user wants to BUILD, DEBUG, or CONTRIBUTE to MEGAcmd source code — that is a different skill
The user wants to use the MEGA SDK for custom integration
MEGAcmd is not installed (this skill does not install it — only provides installation instructions)
The user wants to access files via the MEGA Desktop App (not CLI)

⚠️ Security Overview This skill can perform powerful operations on your MEGA account, including file management, bidirectional sync, scheduled backups, public link sharing, and network services (WebDAV/FTP). Agent caution: Require explicit user confirmation before login, deleting files, syncing folders, creating backups, exporting links, sharing folders, changing account settings, mounting FUSE, or starting WebDAV/FTP. Credential safety: Avoid putting passwords, session IDs, proxy credentials, or recovery keys directly in commands or chat-visible logs. Prefer interactive login or protected secrets mechanisms.

Prerequisites

Before using any command, ALWAYS check:

bash

# 1. Is MEGAcmd installed?
which mega-exec 2>/dev/null && echo "INSTALLED" || echo "NOT INSTALLED"

# 2. Is the server running?
ps aux | grep -q "[m]ega-cmd-server" && echo "SERVER OK" || echo "SERVER STOPPED"

# 3. Are you logged in?
mega-whoami >/dev/null 2>&1 && echo "LOGGED IN" || echo "NOT LOGGED IN"

If the server is not running: mega-cmd-server & If not logged in: mega-login email password

Architecture

Component	Executable	Function
Server	`mega-cmd-server`	Runs in background, processes commands, manages sync/backups/transfers
Shell	`mega-cmd`	Interactive mode (commands WITHOUT `mega-` prefix)
Client	`mega-exec` + `mega-*`	Scriptable mode (commands WITH `mega-` prefix)

Data location: $HOME/.megaCmd/ (Linux) | %LOCALAPPDATA%\MEGAcmd\.megaCmd\ (Windows)

Session: Login saves local cache. logout clears it. logout --keep-session preserves cache.

Usage Modes — PAY ATTENTION TO PREFIXES

Scriptable Mode (agent uses this → ALWAYS use `mega-`)

bash

mega-login email password
mega-put ~/file.pdf /Destination/
mega-get /remote/file.pdf ~/Downloads/
exit code 0 = success, != 0 = failure

Interactive Mode (MEGAcmd shell → commands WITHOUT `mega-`)

bash

mega-cmd
MEGA CMD> login email password
MEGA CMD> put ~/file.pdf /Destination/

⚠️ Agent rule: You are in a bash terminal. ALWAYS use mega- as prefix. Commands without mega- (sync, webdav, ftp, log) only work INSIDE the interactive shell (mega-cmd).

Essential Commands

⚠️ Security Warning — Credential Exposure Running mega-login with an inline password exposes credentials to shell history, process listings, audit logs, and agent telemetry. In shared or automated environments, prefer login methods that do not pass the password as a command-line argument. Recommendation: Use mega-login interactively (without the password argument) when possible. Always enable 2FA for account protection. Avoid including credentials in scripts or automation output.

Login & Account

Command	Description
`mega-login email password [--auth-code=XXXX]`	Login (optional 2FA)
`mega-logout [--keep-session]`	Logout (or keep cache)
`mega-whoami [-l]`	Account info
`mega-df [-h]`	Storage space
`mega-masterkey ./file.txt`	Save recovery key
`mega-passwd [-f] [--auth-code=XXXX] new-password`	Change password
`mega-session`	Show session ID
`mega-killsession -a`	Kill all other sessions

⚠️ Security Warning — Recovery Key The master key (recovery key) is essential for data recovery. If lost, you cannot recover your data without the password. If exposed, an attacker gains durable access to your account. Recommendation: Save the master key to encrypted storage (password manager, encrypted USB). Store it with restricted file permissions (e.g., chmod 600). Do NOT sync the plaintext file to cloud storage.

⚠️ Security Warning — Session Token The session ID is a bearer credential. If exposed, anyone can impersonate your session until it expires or is revoked. Recommendation: Do not share the session output in logs, screenshots, scripts, or automated reports.

Navigation & Listing

Command	Description
`mega-ls [-lhR] [--versions] [path]`	List files
`mega-ls -l`	Detailed list (type, size, date)
`mega-find [path] --pattern="*.pdf" [--type=f\|d]`	Search files
`mega-find / --pattern="*.tmp" --mtime="-7d"`	Search by date
`mega-du [-h] [--versions] [path]`	Folder disk usage
`mega-cd [path]`	Change remote directory
`mega-pwd`	Current remote directory
`mega-mount`	List root nodes

Upload & Download

Command	Description
`mega-put [-c] [-q] local [destination]`	Upload (`-c`=create folder, `-q`=background)
`mega-get [-q] source [local]`	Download (`--password` for protected links)
`mega-get "link#key" ./dir`	Download from public link
`mega-cat path`	Display text file contents

⚠️ Security Warning — Data Disclosure Creating public links exposes your cloud data to anyone with the link. Links with --writable grant write access to the shared folder. Recommendation: Use --password to protect sensitive files. Set --expire dates for time-limited access. Periodically review and remove unused export links.

File Management

Command	Description
`mega-mkdir [-p] path`	Create directory
`mega-cp [--use-pcre] source destination`	Copy (all remote)
`mega-mv [--use-pcre] source destination`	Move/rename
`mega-rm [-r] [-f] path`	Delete (recursive/forced)
`mega-export -a path`	Create public link
`mega-export -d path`	Remove link
`mega-export -a path --password="x" --expire="30d"`	Password-protected link (PRO)
`mega-import link [destination]`	Import link to cloud

⚠️ Security Warning — Folder Sharing Sharing folders gives external users access to your MEGA content. Permission levels range from Read (0) to Owner (3). Over-sharing or granting excessive permissions can expose sensitive data. Recommendation: Grant the minimum permission level needed. Remove sharing when no longer required. Review shared folders periodically.

Sharing

Command	Description
`mega-share -a --with="email" --level=N /folder`	Levels: 0=Read, 1=R+W, 2=Full, 3=Owner
`mega-share -d --with="email" /folder`	Stop sharing
`mega-invite email [--message="..."]`	Invite contact
`mega-ipc email -a`	Accept invitation
`mega-users [-s]`	List contacts

Synchronization (Sync)

Sync is bidirectional. Removed files go to SyncDebris in the Rubbish Bin.

bash

mega-sync ~/Documents /MEGA/Documents     # Create sync
mega-sync                                    # List syncs
mega-sync -p ID                              # Pause
mega-sync -e ID                              # Resume
mega-sync -d ID                              # Remove (does not delete files)

Ignore patterns:

bash

mega-sync-ignore --add "-f:*.tmp" ID
mega-sync-ignore --add "-f:node_modules" ID
mega-sync-ignore --show ID

Filter format: <CLASS><TARGET><TYPE><STRATEGY>:<PATTERN>

CLASS: - (exclude) / + (include)
TARGET: d(dir), f(file), s(symlink), a(all)
TYPE: N(local name), p(path), n(subtree name)
STRATEGY: G/g(glob), R/r(regexp). Upper=case-sensitive

Verify: mega-sync shows STATUS = Synced when everything is OK.

Backups

BETA feature. Backups are unidirectional (local → cloud).

bash

mega-backup ~/Photos /Backups/Photos --period="0 0 4 * * *" --num-backups=10
mega-backup ~/Projects /Backups --period="2h" --num-backups=24

# Manage
mega-backup                    # List
mega-backup -lh                # With history
mega-backup -a TAG             # Abort
mega-backup -d ~/Photos        # Remove configuration

Storage pattern: /remote/folder_bk_TIMESTAMP

Verify: mega-backup -lh shows STATUS COMPLETE and history.

WebDAV & FTP Servers

BETA. Only one server at a time. First location's configuration applies to all.

⚠️ Security Warning — Network Exposure Starting WebDAV exposes your MEGA content over the network. Without TLS, traffic is unencrypted. The --public flag makes the service accessible beyond localhost. Recommendation: Use --tls with valid certificates. Avoid --public unless necessary. Stop services when not in use with mega-webdav -d.

WebDAV

bash

mega-webdav /Videos                            # Serve folder (port 4443)
mega-webdav /movie.mp4                         # Streaming
mega-webdav /Docs --tls --certificate=cert.pem --key=key.pem  # HTTPS
mega-webdav /Public --public --port=8080       # Public
mega-webdav -d /Videos                         # Stop
mega-webdav -d --all                           # Stop all

⚠️ Security Warning — Network Exposure Starting FTP exposes your MEGA content via unencrypted FTP. Without --tls, credentials and data are sent in plain text. By default the server is local-only; use --public to allow remote access. Recommendation: Use --tls with valid certificates for secure FTP. Avoid serving sensitive content over plain FTP. Stop services when not in use with mega-ftp -d.

FTP

bash

mega-ftp /Public                               # Serve folder (port 4990)
mega-ftp /Docs --tls --certificate=cert.pem --key=key.pem  # FTPs
mega-ftp -d /Public                            # Stop

Verify: mega-webdav or mega-ftp lists active URLs.

FUSE (Linux only)

BETA. Streaming not supported — files are fully downloaded. Cache at $HOME/.megaCmd/fuse-cache.

bash

mega-fuse-add --name=my-docs /mnt/mega /Documents
mega-fuse-show                                 # List
mega-fuse-enable my-docs                       # Enable
mega-fuse-disable my-docs                      # Disable
mega-fuse-remove my-docs                       # Remove (must be disabled first)

Issue: "Transport endpoint is not connected"

bash

fusermount -u /mnt/mega

Transfers

bash

mega-transfers                            # List active
mega-transfers --summary                  # Summary
mega-transfers -c TAG                     # Cancel
mega-transfers -p TAG                     # Pause
mega-transfers -r TAG                     # Resume
mega-transfers -c -a                      # Cancel all
mega-speedlimit -d 2M                     # Limit download
mega-speedlimit -u 1M                     # Limit upload

Settings

bash

mega-https on|off
mega-proxy URL|--auto|--none
mega-configure
mega-configure max_nodes_in_cache N
mega-permissions --files -s 600          # Unix only
mega-log -c DEBUG                        # Adjust MEGAcmd log level
mega-log -s INFO                         # Adjust SDK log level

⚠️ If using proxy authentication, avoid passing credentials on the command line where they may be captured by shell history or process listings. Prefer environment variables or a configuration file instead.

Quick Diagnostics — Sync Not Working

When sync is stuck or failing:

Step 1: General state

bash

# Is the server running?
ps aux | grep -c "[m]ega-cmd-server"
# Should return 1 or more

# Are you logged in?
mega-whoami
# Should show the account email

Step 2: Check sync

bash

mega-sync
# Columns: RUN_STATE (Running/Pending/Disabled), STATUS (Synced/Pending/Syncing), ERROR

Step 3: Check conflicts

bash

mega-sync-issues
# If there are issues, investigate:
mega-sync-issues --detail ISSUE_ID

Step 4: Check transfers

bash

mega-transfers --summary
# Active uploads or downloads? Progress?

Step 5: Check logs

bash

tail -50 ~/.megaCmd/megacmdserver.log
# Look for: ERR, WARN, "sync issues", "quota", "rate limit"

Step 6: Check storage

bash

mega-df -h
# Quota exceeded? (USED STORAGE near 100%)

Common causes and solutions

Symptom	Likely cause	Solution
RUN_STATE = Disabled	Sync paused	`mega-sync -e ID`
STATUS = Pending (never changes)	Initial scan of many files	Wait (can take hours with 100k+ files)
Sync Issues > 0	Local × cloud conflicts	`mega-sync-issues --detail ID`, remove/move problematic files
ERROR = "Sync Issues (N)"	Problem files	Run step 3
No transfers appear	Scan still in progress	Wait
"rate limit" in log	Too many requests in short period	Wait a few minutes
"quota" in log	Storage quota exceeded	`mega-df -h`, free up space
LOG full of "Can't find"	Deleted/moved files	Usually resolves itself after rescan

⚠️ The following commands delete local files without confirmation. Verify paths are correct before running.

Action plan for stuck sync

bash

# 1. Pause
mega-sync -p BK0pIuFWODQ    # use your actual sync ID

# 2. Resolve issues (if any)
# Remove problematic files (Zone.Identifier, .lnk, .megaignore)
find ~/sync-folder -name "*:Zone.Identifier" -delete 2>/dev/null
find ~/sync-folder -name "*.lnk" -type f -delete 2>/dev/null
find ~/sync-folder -name ".megaignore" -delete 2>/dev/null

# 3. Resume
mega-sync -e BK0pIuFWODQ

# 4. Monitor
sleep 10 && mega-sync && mega-transfers --summary

Verification — How to Confirm It Worked

Operation	How to verify
Login	`mega-whoami` shows the account email
List	`mega-ls /path` lists files (or error if not found)
Upload	`mega-ls /destination` shows the uploaded file
Download	File exists at the specified local path
Sync active	`mega-sync` shows STATUS = `Synced`, ERROR = `NO`
Sync in progress	`mega-transfers` shows active transfers
Backup created	`mega-backup -lh` shows history with STATUS = `COMPLETE`
Public link	`mega-export /path` shows the URL
WebDAV active	`mega-webdav` lists serving URLs
FTP active	`mega-ftp` lists serving URLs
Session closed	`mega-whoami` returns a not-logged-in error

Important Rules

Always check exit code: mega-command || echo "FAILED ($?)"
Escape ! in links: mega-get https://mega.nz/#F\!ABcD\!Key ./dir
Master Key is ESSENTIAL: mega-masterkey ./recovery.txt — without it, losing your password means losing everything. Store it in an encrypted, access-restricted location.
Logout on shared machines
logout --keep-session on personal machines (preserves cache, resumes session)
--writable links expose the shared folder — anyone with the link can upload, modify, or delete files in that folder. Only share writable links with trusted parties.
Use -q (queue) for large operations in background
In syncs, exclude node_modules, .git, *.tmp with mega-sync-ignore
First sync is slower — 100k+ files can take hours to scan

Common Error Codes

Code	Name	Meaning
`0`	API_OK	Success
`-2`	API_EACCESS	Access denied / permission
`-5`	API_ERATELIMIT	Too many requests — wait
`-10`	API_ENOENT	File/folder not found
`-13`	API_EEXIST	Already exists
`-16`	API_ESID	Invalid session — login again
`-18`	API_EOVERQUOTA	Storage quota exceeded

Use mega-errorcode NUM to translate any code.

Compatibility

Feature	Linux	macOS	Windows
FUSE mounts	✅	❌	❌
Autocomplete (bash)	✅	✅	❌
Unicode in shell	✅	✅	Experimental
Auto-update	❌ (pkg manager)	✅	✅
File permissions	✅	✅	❌

Full Reference

For detailed documentation of ALL 76 commands (full syntax, all flags, examples), see:

Always available: mega-command --help for each command's help

MEGAcmd

Install

MEGAcmd — AI Agent Guide

What this skill does

When to use

When NOT to use

Prerequisites

Architecture

Usage Modes — PAY ATTENTION TO PREFIXES

Scriptable Mode (agent uses this → ALWAYS use mega-)

Interactive Mode (MEGAcmd shell → commands WITHOUT mega-)

Essential Commands

Login & Account

Navigation & Listing

Upload & Download

File Management

Sharing

Synchronization (Sync)

Backups

WebDAV & FTP Servers

WebDAV

FTP

FUSE (Linux only)

Transfers

Settings

Quick Diagnostics — Sync Not Working

Step 1: General state

Step 2: Check sync

Step 3: Check conflicts

Step 4: Check transfers

Step 5: Check logs

Step 6: Check storage

Common causes and solutions

Action plan for stuck sync

Verification — How to Confirm It Worked

Important Rules

Common Error Codes

Compatibility

Full Reference

Related skills

Scriptable Mode (agent uses this → ALWAYS use `mega-`)

Interactive Mode (MEGAcmd shell → commands WITHOUT `mega-`)