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#

ComponentExecutableFunctionServermega-cmd-serverRuns in background, processes commands, manages sync/backups/transfersShellmega-cmdInteractive mode (commands WITHOUT mega- prefix)Clientmega-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#

CommandDescriptionmega-login email password [--auth-code=XXXX]Login (optional 2FA)mega-logout [--keep-session]Logout (or keep cache)mega-whoami [-l]Account infomega-df [-h]Storage spacemega-masterkey ./file.txtSave recovery keymega-passwd [-f] [--auth-code=XXXX] new-passwordChange passwordmega-sessionShow session IDmega-killsession -aKill 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#

CommandDescriptionmega-ls [-lhR] [--versions] [path]List filesmega-ls -lDetailed list (type, size, date)mega-find [path] --pattern="*.pdf" [--type=f|d]Search filesmega-find / --pattern="*.tmp" --mtime="-7d"Search by datemega-du [-h] [--versions] [path]Folder disk usagemega-cd [path]Change remote directorymega-pwdCurrent remote directorymega-mountList root nodes

Upload & Download#

CommandDescriptionmega-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" ./dirDownload from public linkmega-cat pathDisplay 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#

CommandDescriptionmega-mkdir [-p] pathCreate directorymega-cp [--use-pcre] source destinationCopy (all remote)mega-mv [--use-pcre] source destinationMove/renamemega-rm [-r] [-f] pathDelete (recursive/forced)mega-export -a pathCreate public linkmega-export -d pathRemove linkmega-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#

CommandDescriptionmega-share -a --with="email" --level=N /folderLevels: 0=Read, 1=R+W, 2=Full, 3=Ownermega-share -d --with="email" /folderStop sharingmega-invite email [--message="..."]Invite contactmega-ipc email -aAccept invitationmega-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#

SymptomLikely causeSolutionRUN_STATE = DisabledSync pausedmega-sync -e IDSTATUS = Pending (never changes)Initial scan of many filesWait (can take hours with 100k+ files)Sync Issues > 0Local × cloud conflictsmega-sync-issues --detail ID, remove/move problematic filesERROR = "Sync Issues (N)"Problem filesRun step 3No transfers appearScan still in progressWait"rate limit" in logToo many requests in short periodWait a few minutes"quota" in logStorage quota exceededmega-df -h, free up spaceLOG full of "Can't find"Deleted/moved filesUsually 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#

OperationHow to verifyLoginmega-whoami shows the account emailListmega-ls /path lists files (or error if not found)Uploadmega-ls /destination shows the uploaded fileDownloadFile exists at the specified local pathSync activemega-sync shows STATUS = Synced, ERROR = NOSync in progressmega-transfers shows active transfersBackup createdmega-backup -lh shows history with STATUS = COMPLETEPublic linkmega-export /path shows the URLWebDAV activemega-webdav lists serving URLsFTP activemega-ftp lists serving URLsSession closedmega-whoami returns a not-logged-in error

---

Important Rules#

1. Always check exit code: mega-command || echo "FAILED ($?)"
2. Escape ! in links: mega-get https://mega.nz/#F\!ABcD\!Key ./dir
3. Master Key is ESSENTIAL: mega-masterkey ./recovery.txt — without it, losing your password means losing everything. Store it in an encrypted, access-restricted location.
4. Logout on shared machines
5. logout --keep-session on personal machines (preserves cache, resumes session)
6. --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.
7. Use -q (queue) for large operations in background
8. In syncs, exclude node_modules, .git, *.tmp with mega-sync-ignore
9. First sync is slower — 100k+ files can take hours to scan

Common Error Codes#

CodeNameMeaning0API_OKSuccess-2API_EACCESSAccess denied / permission-5API_ERATELIMITToo many requests — wait-10API_ENOENTFile/folder not found-13API_EEXISTAlready exists-16API_ESIDInvalid session — login again-18API_EOVERQUOTAStorage quota exceeded

Use mega-errorcode NUM to translate any code.

Compatibility#

FeatureLinuxmacOSWindowsFUSE mounts✅❌❌Autocomplete (bash)✅✅❌Unicode in shell✅✅ExperimentalAuto-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