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)

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

Login & Account

Navigation & Listing

Upload & Download

File Management

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: \x3CCLASS>\x3CTARGET>\x3CTYPE>\x3CSTRATEGY>:\x3CPATTERN>

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

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

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

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

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
4. Logout on shared machines
5. logout --keep-session on personal machines (preserves cache, resumes session)
6. --writable links expose your account — use with caution
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:

• OpenCode: .opencode/skills/megacmd/references/complete-commands-reference.en.md
• Fallback (any tool): AGENTS.en.md at the project root
• Always available: mega-command --help for each command's help