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:

# 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

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-)

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-)

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

> ⚠️ 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

Upload & Download

> ⚠️ 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

> ⚠️ 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

Synchronization (Sync)

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

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:

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

Filter format: :

• 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).

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

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

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.

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"

fusermount -u /mnt/mega

Transfers

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

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

# 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

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

Step 3: Check conflicts

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

Step 4: Check transfers

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

Step 5: Check logs

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

Step 6: Check storage

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

Common causes and solutions

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

Action plan for stuck sync

# 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

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

Use mega-errorcode NUM to translate any code.

Compatibility

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