MEGAcmd — Developer Guide#

What this skill does#

Instructions for BUILDING, DEBUGGING, TESTING, and CONTRIBUTING to the MEGAcmd repository. This skill is for developers who need to compile the project, set up the environment, or investigate the C++ source code.

⚠️ Do not activate this skill if the user just wants to USE MEGAcmd (upload, sync, backup). That is what the megacmd skill is for.

When to use#

• The user wants to compile/install MEGAcmd from source code
• The user wants to set up a development environment (CMake, vcpkg)
• The user wants to run tests (unit or integration)
• The user wants to debug server/client issues
• The user wants to create packages (Debian, RPM, Arch, Synology, Windows)
• The user wants to contribute code or pull requests
• The user asks about the internal code architecture

When NOT to use#

• The user wants to upload, download, sync, backup, or share — use megacmd
• The user wants to use the MEGA web interface
• The user wants to install MEGAcmd via ready-made packages (mega.nz/cmd)

---

Project Structure#

text

MEGAcmd/
├── CMakeLists.txt              # Main build system (488 lines)
├── vcpkg.json                  # vcpkg-managed dependencies
├── src/
│   ├── megacmd_server_main.cpp # Server entry point
│   ├── megacmd.cpp/h           # MEGAcmd core
│   ├── megacmdexecuter.cpp/h   # Command executor
│   ├── megacmdutils.cpp/h      # Utilities
│   ├── megacmdcommonutils.cpp/h # Common utilities
│   ├── megacmdlogger.cpp/h     # Logging system
│   ├── megacmd_fuse.cpp/h      # FUSE support
│   ├── megacmdshell/           # Interactive shell
│   ├── client/                 # Client (mega-exec + mega-* wrappers)
│   │   ├── megacmd_client_main.cpp
│   │   ├── megacmdclient.cpp/h
│   │   ├── mega-*              # Bash wrappers (Linux/macOS)
│   │   └── win/mega-*.bat      # Windows wrappers
│   ├── comunicationsmanager.cpp/h  # IPC (File Sockets / Named Pipes)
│   ├── configurationmanager.cpp/h  # Configuration
│   ├── listeners.cpp/h         # SDK listeners
│   ├── sync_command.cpp/h      # Sync command
│   ├── sync_ignore.cpp/h       # Ignore patterns
│   └── sync_issues.cpp/h       # Sync issues
├── tests/
│   ├── unit/                   # Unit tests (C++)
│   ├── integration/            # Integration tests (C++)
│   └── *.sh, *.py              # Shell/Python tests
├── build/
│   ├── cmake/modules/          # CMake modules
│   ├── installer/              # Installers (NSIS, DMG, scripts)
│   ├── megacmd/                # Debian packages
│   └── templates/megacmd/      # RPM spec, PKGBUILD, DSC
├── contrib/
│   ├── docs/                   # Documentation (76 commands + guides)
│   ├── sanitizer/              # ASan, LSan, TSan suppressions
│   └── updater/                # Updater file lists
├── sdk/                        # MEGA SDK (git submodule)
└── jenkinsfile/                # CI/CD (Jenkins)

---

Build#

Prerequisites#

bash

# Git + submodules
git clone https://github.com/meganz/MEGAcmd.git
cd MEGAcmd && git submodule update --init --recursive

Compile#

bash

# Debug
cmake -B build/build-cmake-Debug -DCMAKE_BUILD_TYPE=Debug
cmake --build build/build-cmake-Debug -j$(nproc)

# Release
cmake -B build/build-cmake-Release -DCMAKE_BUILD_TYPE=Release
cmake --build build/build-cmake-Release -j$(nproc)

# With tests
cmake -B build/build-cmake-Debug -DCMAKE_BUILD_TYPE=Debug -DENABLE_MEGACMD_TESTS=ON
cmake --build build/build-cmake-Debug -j$(nproc)

Install (Linux/macOS)#

bash

sudo cmake --install build/build-cmake-Release

Important Build Options#

FlagDescription-DVCPKG_ROOT=/pathPath to vcpkg (default: ../vcpkg)-DCMAKE_CXX_COMPILER_LAUNCHER=ccacheUse ccache-DENABLE_MEGACMD_TESTS=ONBuild tests-DCMAKE_INSTALL_PREFIX=/pathInstallation directory

CMake Targets#

TargetTypeDescriptionmega-cmd-serverExecutableServermega-cmdExecutableInteractive shellmega-execExecutableNon-interactive clientmega-cmd-updaterExecutableUpdatermega-cmd-tests-unitExecutableUnit testsmega-cmd-tests-integrationExecutableIntegration testsLMegaCmdCommonUtilsStatic libraryCommon utilitiesLMegacmdServerStatic libraryServer logicLMegacmdClientStatic libraryClient logic

---

Dependencies (vcpkg)#

Required#

pcre, cryptopp, curl (with zstd), icu, libsodium, sqlite3

Optional (vcpkg.json features)#

FeatureDependencyActivationuse-opensslopensslCMakeuse-mediainfolibmediainfoCMakeuse-freeimagefreeimage + jasperCMakeuse-ffmpegffmpeg (avcodec, avformat, swresample, swscale)CMakeuse-libuvlibuvCMake (WebDAV/FTP)use-pdfiumpdfiumCMakeuse-readlinereadlineCMakemegacmd-enable-testsgtest-DENABLE_MEGACMD_TESTS=ON

---

Tests#

bash

# Unit tests
./build/build-cmake-Debug/tests/mega-cmd-tests-unit

# Integration tests (requires server running)
./build/build-cmake-Debug/tests/mega-cmd-tests-integration

# Python tests
python3 tests/megacmd_put_test.py
python3 tests/megacmd_get_test.py
python3 tests/megacmd_find_test.py

---

Docker#

bash

# Standard build
docker build -f build-with-docker/Dockerfile.cmake .

# Synology cross-compile
docker build -f build/SynologyNAS/dockerfile/synology-cross-build.dockerfile .

---

Debug#

Logging#

bash

# Start server with debug
MEGAcmdServer --debug          # MEGAcmd=DEBUG, SDK=DEFAULT
MEGAcmdServer --debug-full     # MEGAcmd=DEBUG, SDK=DEBUG
MEGAcmdServer --verbose-full   # MEGAcmd=VERBOSE, SDK=VERBOSE

# Or via env var
MEGACMD_LOGLEVEL=FULLVERBOSE MEGAcmdServer
MEGACMD_JSON_LOGS=1 MEGAcmdServer  # JSON HTTP request logging

Log Files#

• Linux/macOS: $HOME/.megaCmd/megacmdserver.log
• Windows: %LOCALAPPDATA%\MEGAcmd\.megaCmd\megacmdserver.log

Rotating Logger#

Configure via megacmd.cfg in the log directory:

text

RotatingLogger:RotationType=Timestamp    # Timestamp | Numbered
RotatingLogger:CompressionType=Gzip      # Gzip | None
RotatingLogger:MaxFileMB=50
RotatingLogger:MaxFilesToKeep=20
RotatingLogger:MaxFileAgeSeconds=2592000 # 30 days
RotatingLogger:MaxMessageBusMB=512

Sanitizers#

Files in contrib/sanitizer/:

• asan.suppressions — AddressSanitizer
• lsan.suppressions — LeakSanitizer
• tsan.suppressions — ThreadSanitizer

---

CI/CD#

Jenkins#

Jenkinsfiles in jenkinsfile/:

• Jenkinsfile_MR_linux, Jenkinsfile_MR_macos, Jenkinsfile_MR_windows
• Jenkinsfile_MR_linux_packages
• Branch_status/ — Release build pipelines

GitHub Issues#

Template at .github/ISSUE_TEMPLATE/bug_report.yml

---

Packaging#

Debian/APT#

Files in build/megacmd/: control, rules, postinst, prerm, changelog

RPM (Fedora/SUSE)#

build/templates/megacmd/megacmd.spec

Arch Linux#

build/templates/megacmd/PKGBUILD

Windows (NSIS)#

• build/installer_win.nsi — Installer script
• build/installer/ — Icons, banners, resources

macOS (DMG)#

• build/installer_mac.sh — Installation script
• build/installer/Info.plist.in — Info.plist template

Synology NAS#

• build/SynologyNAS/generate_pkg.sh — Generate SPK package
• build/SynologyNAS/toolkit/source/MEGAcmd/ — Installation scripts
• Docker cross-compile available

Generate Changelog#

bash

./build/generate_deb_changelog_entry.sh
./build/generate_rpm_changelog_entry.sh

---

Updater#

Files in src/updater/ and contrib/updater/:

• MegaUpdater.cpp — Update logic
• fileswin.txt, fileswin64.txt, filesmacos.txt — File lists per platform

---

IPC (Client-Server Communication)#

File Sockets (Unix/Linux/macOS)#

Used between mega-exec and mega-cmd-server. Implementation in comunicationsmanagerfilesockets.cpp.

Named Pipes (Windows)#

Used on Windows. Implementation in comunicationsmanagernamedpipes.cpp and megacmdshellcommunicationsnamedpipes.cpp.

TCP Socket (Python alternative)#

src/client/python/mega-execports — connects on port 12300:

1. Connect to 127.0.0.1:12300
2. Send command as string
3. Receive 2 bytes (socketOutId)
4. Connect to 127.0.0.1:12300 + socketOutId
5. Receive 4 bytes (outCode) + output
6. Exit code = -outCode (if negative) or outCode

---

Advanced Settings#

CMake Options#

Options in build/cmake/modules/megacmd_options.cmake:

• USE_PCRE — PCRE for regular expressions (default: ON)
• USE_MEDIAINFO — MediaInfo (default: ON)
• USE_FREEIMAGE — FreeImage (default: ON)
• USE_FFMPEG — FFMPEG (default: ON)
• USE_LIBUV — libuv for WebDAV/FTP (default: ON)
• USE_PDFIUM — PDFium (default: ON)
• USE_READLINE — Readline (default: ON)
• ENABLE_MEGACMD_TESTS — Build tests (default: OFF)

Version#

File build/version contains the current version: 2.5.2

---

Tips for Contributors#

1. The codebase uses C++17
2. Main namespace: megacmd
3. MEGA SDK via submodule in sdk/
4. Style: 4 spaces, BSD 2-Clause header on all files
5. Always run unit tests before submitting a PR
6. To add a new command: edit megacmdexecuter.cpp ( executecommand method)
7. To add a new flag: update getUsageStr() in megacmd.cpp and HelpFlags
8. Sanitizers are enabled by default in Debug builds