🛠️ Morphe Desktop Documentation

This is the complete documentation for Morphe Desktop. Morphe desktop offers both a GUI and a CLI. The GUI is how most people will use it, with a powerful CLI underneath for power users and automation. This documentation covers both, plus common workflows. If you’re brand new, start with the first-run guide, then come back here.

Now that you've done your first run, let's dig deeper into how the magic happens and how to make it even better.

📖 Table of contents

• Prerequisites
• Where Morphe stores its files
• GUI
  • The two modes
  • The TopBar
  • Quick mode
  • Expert mode
  • Custom app icons (Icon Studio)
  • Link handling ("open with")
  • Your apps
  • Settings
  • Tools
  • Installing to a device
• CLI
  • General flags
  • patch
  • list-patches
  • list-versions
  • options-create
  • utility
    • install
    • uninstall
    • clear-cache
  • Value Types Reference
• Building

🤝 Prerequisites

1. Java Runtime Environment 21 or above (Azul Zulu JRE, Temurin or OpenJDK).
2. Morphe Desktop jar file (morphe-desktop-*-all.jar). Download the latest from here.
3. If using CLI: Patches mpp file (patches-*.mpp). Download the latest Morphe official patch files from here.
4. If using CLI: Desired app file (app.apk or app.apkm). Download your apk from APK Mirror.
5. [Optional] Android Debug Bridge (ADB) If you want to install the patched APK file to your device directly from your computer.

📂 Where Morphe stores its files

Morphe keeps its runtime data: cached patch files, logs, scratch space for patching, and the default signing keystore in a single morphe-data/ folder. By default, this folder is created next to the JAR you run, so it survives upgrades and is easy to find. If that location isn't writable (e.g. running from an IDE, or from a read-only install path), Morphe falls back to ~/morphe/. The startup logs print which one is in use (look for Morphe data root: ...).

morphe-data/
  patches/         # cached .mpp patch bundles
  logs/            # application logs
  tmp/             # per-run patching scratch (the default --temporary-files-path location)
  morphe.keystore  # shared default signing key (see --keystore)
  config.json      # preferences + configured sources

Both the GUI and the CLI use this folder. In the GUI you can open it from Tools → Open App Data. On the CLI, --temporary-files-path defaults to tmp/ (override it to send scratch elsewhere) and --keystore defaults to morphe.keystore here.

GUI

The GUI is the window you get when you double-click the jar and for most people, it's the way to use Morphe. No flags to memorize, no quoting mistakes, no terminal history full of 47 almost-right commands. Point, click and patch.

In your first run you used the GUI's Quick mode, the beginner-friendly path. Below we go deeper, focusing on Expert mode, where you can do much more.

The two modes

The GUI can run in one of two modes:

On first launch you're in Quick mode. Switch anytime in Settings → Expert mode → Toggle ON. [Morphe will remember that.]

Quick mode

Quick mode is the beginner path, covered step-by-step in the first-run guide: drop an APK, click Patch, watch it run, then install the patched app. Morphe chooses the patch source and the default patch set for you (by default). You can add additional sources here too. The rest of this section however focuses on Expert mode. That's where the GUI matches (and visualizes) everything the CLI can do.

Expert mode

Expert mode is a five-screen pipeline (for now): Home → Patch source → Patch selection → Patching → Result. Each screen below lists its controls (and the CLI flag it maps to, where there is one), then explains the details.

The TopBar

The home screen has a top bar (on the top):

The sources pill sits in the center of the bar. It shows the loaded patches version and a N SOURCES count, with one small colored LED per source for the release channel it resolved to:

In Expert mode, click the pill to open the source manager – add, remove, refresh, or reorder sources (see Managing patch sources). In Quick mode it's informational. The same LED colors appear on each row inside the source manager.

The rest of the bar is the device indicator on the right (your ADB install target – more under Installing to a device), and the two icon buttons next to it: Tools (the wrench – logs, app data, clear cache, licenses; see Tools) and Settings (the gear – theme, modes, signing, strip libs, and more; see Settings).

1. Pick your APK

Drop an APK anywhere on the window (the zone reads DROP APK HERE → RELEASE TO DROP) or use BROWSE FILES. Split-APK bundles (.apkm / .xapk / .apks) are merged into a single APK automatically.

The SUPPORTED APPS list shows what the loaded patches can target, each with a version tag: STABLE LATEST, EXPERIMENTAL LATEST, ALSO STABLE, EXPERIMENTAL - so you know which APK version to download. Search it if it's long. A second tab, YOUR APPS, tracks everything you've already patched, see Your apps.

Once an APK is dropped, Morphe reads its metadata (ANALYZING / "Reading app metadata…") and shows an info card with the app name, package, and version, plus CHANGE APK and CONTINUE.

2. Choose a patch source & version

Morphe fetches the available releases from your configured source and tags them: LATEST, STABLE, DEV (pre-release), and CACHED (already downloaded). Pick one and DOWNLOAD / SELECT it. Expand PATCH NOTES to read the changelog first. Already have a .mpp? LOCAL PATCH FILE → BROWSE points straight at it.

Managing patch sources

The sources Morphe fetches from are configurable: add community sources (GitHub / GitLab repos, or morphe.software/add-source links), remove them, or refresh them. Adding more than one source is the GUI counterpart to passing several -p URLs on the CLI: their patches show up together, grouped by bundle, on the next screen.

Reordering. Drag a source by its handle to change its position in the list. Order is load priority – sources higher in the list are loaded first. This usually doesn't matter, but it can: if two sources ship a class with the same name (common when both are forks of the same patches project), the one loaded first wins. Keeping your primary source on top is the safe default.

Channel badge. Each enabled source shows a small badge for the release it resolved to, color-coded by release channel, the same colors (and meanings) as the sources-pill LEDs in The TopBar.

3. Select patches

The full patch list from your selected bundle(s), with a running "N of M selected" count.

• Toggling & search: Flip patches on/off. Search filters the list (you'll see No patches match your search). If you added multiple sources, patches are grouped per bundle (No matches in this bundle when a filter empties one).

• Options: Patches with configurable options show an options count. Click on this to expand and edit. Values are typed, see the Value Types Reference for how strings / booleans / lists are formatted. PATCH DEFAULTS means untouched. YOUR DEFAULTS means you've customized it. A few options are richer than a text box, notably custom icon option, which opens the Icon Studio instead.

• Strip libs: A summary chip shows whether native libs will be stripped (STRIPPING NATIVE LIBS / NO STRIPPING NEEDED / NO NATIVE LIBS). Change the kept architectures under Settings → Strip Libs.
• Continue patching even if a patch fails: By default a failed patch aborts the whole run. Enable this to skip the failure and apply the rest. The GUI's equivalent of the CLI's --continue-on-error.
• Command preview: The exact CLI invocation your choices produce. COPY it to reproduce this run in a terminal or drop it into a script. EXPAND / COMPACT toggles full vs condensed.

Custom app icons (Icon Studio)

Some patches can replace the app's launcher icon. When a patch exposes a custom icon option (for example the Custom branding patch on the official Morphe patches), its row in the options editor shows action buttons instead of a plain text field:

The patch expects a specific icon folder on disk, but you never have to build that by hand. The Icon Studio generates it and sets the option to its path. The row reads Custom icon ready once set, No custom icon set otherwise.

Foreground vs. background. Android adaptive icons are two layers: an opaque background and a foreground on top (the foreground may be transparent). The launcher masks the combined result into whatever shape the device uses. The Icon Studio mirrors this with two panels:

• FOREGROUND: Your logo/mark, built from stacked layers. Each layer is an IMAGE, TEXT, or a SHAPE (circle, square, rounded, triangle, and more). Per layer you get TRANSFORM (move / scale / rotate, with RESET POSITION), color, and effects like SHADOW, GLOW, STROKE. Text layers add BOLD / ITALIC / UNDERLINE / STRIKE; DUPLICATE copies a layer.
• BACKGROUND: A SOLID color, a GRADIENT (LINEAR / RADIAL / CONIC), or an IMAGE.

Colors come from a picker with saveable swatches, TEMPLATES give you starting points, and UNDO / REDO cover mistakes. Your work autosaves (the header shows SAVED), so EDIT ICON reopens exactly where you left off.

Live previews. The right side shows how the icon renders in three real contexts:

• ADAPTIVE – the normal launcher icon (foreground over background).
• MONOCHROME – the themed/monochrome icon (Android 13+): a tinted silhouette of the foreground.
• NOTIFICATION / STATUS BAR – the small white silhouette used in the status bar and notifications, again derived from the foreground.

Because the monochrome and notification icons come from the foreground's shape and transparency, a background-only icon shows nothing in those two previews. That's expected, and the Studio points it out.

Hit SAVE ICON to export the folder and wire it into the option (CANCEL discards the current session), then patch as usual – the new icon is applied during patching.

4. Patching

Morphe runs the pipeline and streams the same log lines the CLI prints, with a patched/total counter. The log is also saved to disk (morphe-data/logs/, reachable via Tools → Open Logs). On failure you'll see PATCHING FAILED with the error in the log; on success, PATCHING COMPLETED – LOADING RESULT… advances to the result screen. CANCEL stops mid-run.

5. Result

• OUTPUT FILE / OPEN FOLDER → – the finished APK and a button to reveal it in your file manager.
• ADB INSTALL – with a device connected and ADB enabled, install directly. Pick a device (SELECT A DEVICE), wait for READY, install; you'll see INSTALLED ON <device> on success or RETRY on failure. Device states include UNAUTH (accept the USB-debugging prompt on the phone) and UNKNOWN. If ADB is off you'll see ENABLE ADB (turn on Auto-start ADB in Settings).
• PATCH ANOTHER restarts the flow; TEMPORARY FILES → CLEAN UP frees this run's scratch space (it shows how much).

Link handling ("open with")

After installing to a device, Morphe can make the patched app handle its supported web links, so those links open in the patched app instead of your browser or the stock app. It's ADB-only and fully reversible.

The LINK HANDLING section appears on the Result screen once the patched app is installed and a device is connected. On success, you'll see Links routed to patched app (or …, stock disabled); the change is reversible, restoring default link handling. To run it automatically after every ADB install, turn on Route links to patched app in Settings.

Your apps

The home screen has two tabs: SUPPORTED APPS (what your patches can target) and YOUR APPS, a history of everything you've patched with Morphe. The "Your apps" tab carries a count badge, and when newer patches are available a banner ("N patched apps have updates available") jumps you there.

Each entry is a card showing the app, the patched version, and when you patched it. Tap one for the full breakdown and actions:

The detail view also lists the app and Morphe versions and a per-source version breakdown, and flags when a newer patch may bump the app version.

Uninstall vs. Forget. Uninstall removes the app from your phone. Its dialog has an "Also remove from Your apps" checkbox to clear the history entry at the same time. Forget only drops the history entry and leaves the installed app untouched.

Settings

The gear icon opens Settings – Morphe's persistent preferences. Think of it as the GUI's equivalent of the CLI flag set: most settings map directly to a patch flag.

A couple of toggles worth expanding on:

• Auto-start ADB - when off, Morphe never starts the ADB server and all install/push features are disabled. Turn it on to install patched APKs to your phone from Morphe.
• Update channel - Dev surfaces pre-releases; Stable only stable ones. If you've never chosen, Morphe defaults smartly (Dev when you're running a dev build).
• Route links to patched app - when on, every ADB install is followed by routing the app's supported web links to the patched app (the Link handling step, run automatically). A nested Disable stock app's links option also stops the original app from opening those links – only relevant when a rename patch was used and the stock app is still installed. Both are reversible and need a connected device.

Signing

This is the GUI face of the --keystore* flags. Morphe signs every patched APK so it's installable; by default it uses a single shared keystore in its data folder (see Where Morphe stores its files) and reuses it across runs – Android only lets you update an installed app with an APK signed by the same key, so a stable keystore keeps re-patches installable over old builds.

Strip Libs

Choose which native-library architectures to keep in the patched APK; everything else is stripped, shrinking the file. This sets the default the Patch selection screen reports, and maps to the CLI's --striplibs.

Patched app runtime logs

A debugging aid: capture logcat from a connected device after a patched app crashes or misbehaves, to attach to a bug report. CLEAR DEVICE LOGS wipes logcat before you reproduce the issue; SAVE DEVICE LOGS then pulls the filtered output to a file. Both require a connected, ADB-authorized device.

Tools

The wrench icon opens Tools – one-off actions and reference info, kept out of Settings so a destructive action doesn't sit next to your preferences.

VIEW LICENSES opens a searchable browser of the open-source licenses for every third-party library Morphe bundles. Use the search box to filter by name – handy for license compliance, or just to see what's under the hood.

Installing to a device (ADB)

Morphe can push patched APKs straight to your phone over ADB:

1. Enable Auto-start ADB in Settings (off by default).
2. Connect your phone via USB with USB debugging enabled, and accept the authorization prompt on the device.
3. The device indicator in the top bar shows it; click to pick a device if several are connected.
4. After patching, use ADB INSTALL on the Result screen.

Device states you may see: READY (good to go), UNAUTH (accept the USB-debugging prompt on the phone), UNKNOWN (reconnect / check the cable), and No devices connected.

CLI

Prefer the terminal, or automating Morphe in a script or CI? The CLI exposes everything the GUI does – if you just want to patch an app, the GUI above is the easier path.

The CLI suite is an extremely powerful tool. It has some general flags but is mainly divided into 5 main sub-commands (and they all lived in harmony, until the fire nation attacked. Caught that reference?):

General flags

-h, --help:

Shows all the general flags and sub commands available.

java -jar morphe-desktop-*-all.jar --help

-V, --version:

Shows the current version of the morphe-desktop.jar

java -jar morphe-desktop-*-all.jar --version

Subcommand 1: patch

This is the most fundamental sub-command. Add the patch keyword to run this sub-command.

java -jar morphe-desktop-*-all.jar patch [flag/s]

Here is a quick lookup for all the flags under this subcommand:

java -jar morphe-desktop-*-all.jar patch -p patches.mpp -o your_app_patched.apk --striplibs arm64-v8a --force --continue-on-error -d "change package name" -d "spoof signature" "your_app.apk"

-p, --patches:

Required: Yes

Default: -

This flag specifies the patch file(s) to apply to your APK. You can pass local .mpp file paths or a GitHub or GitLab repository URL, and you can repeat -p to combine several bundles in one run (see Using multiple patch bundles below). When a URL is provided, Morphe automatically downloads the .mpp file from the latest release and caches it for future runs.

java -jar morphe-desktop-*-all.jar patch --patches patches-*.mpp your_app.apk

You can also pass a GitHub or GitLab repo URL:

java -jar morphe-desktop-*-all.jar patch --patches https://github.com/MorpheApp/morphe-patches your_app.apk
java -jar morphe-desktop-*-all.jar patch --patches https://gitlab.com/MorpheApp/morphe-patches your_app.apk

Or a specific release URL:

java -jar morphe-desktop-*-all.jar patch --patches https://github.com/MorpheApp/morphe-patches/releases/tag/v1.0.0 your_app.apk

Using multiple patch bundles

-p can be repeated to combine several .mpp bundles in a single run:

java -jar morphe-desktop-*-all.jar patch -p patches-a.mpp -p patches-b.mpp your_app.apk

The name-based selection flags (-e, -d, -O) apply to the bundle they follow. Each -p starts a new bundle, and the selections after it belong to that bundle until the next -p:

java -jar morphe-desktop-*-all.jar patch -p patches-a.mpp -e "A patch from bundle A" -p patches-b.mpp -d "A patch from bundle B" your_app.apk

Index-based selections (--ei/--di) are the exception. Their numbers refer to the combined list across all supplied bundles, not a single one. Run list-patches with the same set of -p files to see the combined numbering:

java -jar morphe-desktop-*-all.jar list-patches -p patches-a.mpp -p patches-b.mpp

Then enable/disable by those combined indices. The index points to a patch no matter which bundle it came from, so its position relative to each -p doesn't matter:

java -jar morphe-desktop-*-all.jar patch -p patches-a.mpp -p patches-b.mpp --ei 57 --di 12 your_app.apk

--prerelease:

Required: No

Default: false

When using a GitHub or GitLab repo URL with --patches, fetch the latest dev pre-release instead of the latest stable release.

java -jar morphe-desktop-*-all.jar patch --patches https://github.com/MorpheApp/morphe-patches --prerelease your_app.apk

Positional argument (APK file):

Required: Yes

Default: -

The APK file you want to patch. This is passed directly without a flag name, at the end of the command.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp your_app.apk

-o, --out:

Required: No

Default: a subfolder named after the app, created next to the input APK – <app>/<app>-Morphe-<appVersion>-patches-<patchesVersion>.apk

Specify a custom output path for the patched APK.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp -o /path/to/output.apk your_app.apk

-e, --enable:

Required: No

Default: -

Enable a specific patch by its exact name. Can be used multiple times to enable several patches.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp -e "Patch name" -e "Another patch" your_app.apk

--ei:

Required: No

Default: -

Enable a specific patch by its index number. Can be used multiple times. Use list-patches to find the index of each patch.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp --ei 1 --ei 5 your_app.apk

-d, --disable:

Required: No

Default: -

Disable a specific patch by its exact name. Can be used multiple times.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp -d "Patch name" your_app.apk

--di:

Required: No

Default: -

Disable a specific patch by its index number. Can be used multiple times. Use list-patches to find the index of each patch.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp --di 456 your_app.apk

java -jar morphe-desktop-*-all.jar patch -p patches.mpp --exclusive -e "Patch name" --ei 123 your_app.apk

-O, --options:

Required: No

Default: -

Set option values for patches. Options are key-value pairs passed alongside patch enable flags. To set a value to null, omit the value.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp -e "Patch name" -Okey1=value1 -Okey2=value2 your_app.apk

To set an option to null:

java -jar morphe-desktop-*-all.jar patch -p patches.mpp -e "Patch name" -Okey1 your_app.apk

--exclusive:

Required: No

Default: false

Disable all patches except the ones you explicitly enable with -e or --ei. Useful when you only want a specific set of patches applied.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp --exclusive -e "Patch name" your_app.apk

-f, --force:

Required: No

Default: false

Skip the APK version compatibility check. By default, Morphe will warn you and skip patches that aren't compatible with your APK's version. This flag forces all compatible patches to run regardless.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp --force your_app.apk

-i, --install:

Required: No

Default: -

Automatically install the patched APK to a connected ADB device after patching.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp -i your_app.apk

If no serial is provided, it installs to the first connected device. You can optionally specify a device serial.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp -i SERIAL123 your_app.apk

adb shell exit

--mount:

Required: No

Default: false

Install the patched APK by mounting it on top of the original app. Requires root access and the original app to be installed on the device.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp -i --mount your_app.apk

adb shell su -c exit

--keystore:

Required: No

Default: the shared morphe-data/morphe.keystore (see Where Morphe stores its files)

Path to a keystore file containing a private key and certificate pair to sign the patched APK with. If not specified, Morphe uses a single shared keystore in its data folder – auto-creating it on the first run and reusing it afterwards. Reusing one keystore is intentional: Android only lets you update an installed app with an APK signed by the same key, so a stable keystore means you can re-patch and reinstall over a previous build.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp --keystore /path/to/keystore.bks your_app.apk

--keystore-password:

Required: No

Default: empty (no password)

Password to open the keystore file itself. Different from the key entry password (--keystore-entry-password). Morphe's auto-generated default keystore has an empty store password, so you typically only need this flag when supplying your own keystore that was created with one.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp --keystore keystore.jks --keystore-password "mypassword" your_app.apk

--keystore-entry-alias:

Required: No

Default: "Morphe"

The alias of the private key entry inside the keystore.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp --keystore keystore.jks --keystore-entry-alias "my-alias" your_app.apk

--keystore-entry-password:

Required: No

Default: "Morphe"

Password for the specific keystore entry.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp --keystore keystore.jks --keystore-entry-password "mypassword" your_app.apk

--signer:

Required: No

Default: "Morphe"

The name of the signer embedded in the APK signature.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp --signer "My Signer" your_app.apk

--unsigned:

Required: No

Default: false

Skip signing the patched APK entirely. The output APK will not be signed and cannot be installed directly on a device without signing it separately.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp --unsigned your_app.apk

-t, --temporary-files-path:

Required: No

Default: morphe-data/tmp/ next to the JAR (falls back to ~/morphe/tmp/)

Path to a directory where Morphe stores temporary files during patching.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp -t /tmp/morphe-temp your_app.apk

--disable-purge:

Required: No

Default: false

By default, this run's scratch files are deleted once patching finishes. Pass this flag to keep them instead — useful for debugging a failed patch. Does not affect cached patches, other sessions, or config.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp --disable-purge your_app.apk

--striplibs:

Required: No

Default: -

Comma-separated list of native library architectures to keep. All other architectures will be stripped from the APK, reducing file size.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp --striplibs arm64-v8a,armeabi-v7a your_app.apk

--bytecode-mode:

Required: No

Default: STRIP_FAST

Controls how Morphe processes the APK's bytecode (DEX) during patching. Trade-off between speed, output size, and safety.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp --bytecode-mode FULL your_app.apk

--verify-with-sdk:

Required: No

Default: - (verification is skipped)

Verify the patched DEX and APK files using a local Android SDK after patching. Helpful for catching corrupt output before installing on a device. Pass a path to your SDK install directory, or pass the flag with no value to let Morphe auto-discover one.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp --verify-with-sdk /path/to/android-sdk your_app.apk
java -jar morphe-desktop-*-all.jar patch -p patches.mpp --verify-with-sdk your_app.apk

--continue-on-error:

Required: No

Default: false

By default, patching stops on the first patch failure. This flag lets Morphe continue applying the remaining patches even if one fails.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp --continue-on-error your_app.apk

--options-file:

Required: No

Default: -

Path to a JSON file that controls which patches are enabled/disabled and their option values. Generate one using the options-create subcommand.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp --options-file options.json your_app.apk

--options-update:

Required: No

Default: false

Automatically update the options JSON file after patching to reflect the current patches. Without this flag, the file is left unchanged. New patches get added, removed patches get cleaned up.

java -jar morphe-desktop-*-all.jar patch -p patches.mpp --options-file options.json --options-update your_app.apk

-r, --result-file:

Required: No

Default: -

Path to save a JSON file containing the patching result. The file records:

• the package name and version of the patched app
• whether patching succeeded overall
• the result of each patching step
• the list of applied patches
• the list of failed patches, with their error details

java -jar morphe-desktop-*-all.jar patch -p patches.mpp -r result.json your_app.apk

Subcommand 2: list-patches

Lists all available patches from the supplied MPP files. Useful for finding patch names, indices, compatible packages, and options before patching.

java -jar morphe-desktop-*-all.jar list-patches --patches patches.mpp [flag/s]

Here is a quick lookup for all the flags under this subcommand:

--patches:

Required: Yes

Default: -

One or more paths to .mpp patch files or GitHub or GitLab repository URLs to list patches from. When a URL is provided, Morphe downloads the .mpp file and caches it for future runs.

java -jar morphe-desktop-*-all.jar list-patches --patches patches.mpp
java -jar morphe-desktop-*-all.jar list-patches --patches https://github.com/MorpheApp/morphe-patches

--prerelease:

Required: No

Default: false

When using a GitHub or GitLab repo URL with --patches, fetch the latest dev pre-release instead of the latest stable release.

java -jar morphe-desktop-*-all.jar list-patches --patches https://github.com/MorpheApp/morphe-patches --prerelease

--out:

Required: No

Default: -

Write the patch list to a file instead of printing to stdout. Useful in environments where > redirection is not available.

java -jar morphe-desktop-*-all.jar list-patches --patches patches.mpp --out patches-list.txt

-d, --with-descriptions:

Required: No

Default: true

Show the description of each patch. Enabled by default - use --with-descriptions=false to hide them.

java -jar morphe-desktop-*-all.jar list-patches --patches patches.mpp --with-descriptions=false

-p, --with-packages:

Required: No

Default: false

Show the packages each patch is compatible with.

java -jar morphe-desktop-*-all.jar list-patches --patches patches.mpp --with-packages

-v, --with-versions:

Required: No

Default: false

Show the compatible app versions for each patch. Requires --with-packages to be useful.

java -jar morphe-desktop-*-all.jar list-patches --patches patches.mpp --with-packages --with-versions

-o, --with-options:

Required: No

Default: false

Show the configurable options for each patch, including their keys, types, default values, and possible values.

java -jar morphe-desktop-*-all.jar list-patches --patches patches.mpp --with-options

-u, --with-universal-patches:

Required: No

Default: true

Include patches that are compatible with any app (universal patches). Use --with-universal-patches=false to only show patches targeting specific packages.

java -jar morphe-desktop-*-all.jar list-patches --patches patches.mpp --with-universal-patches=false

-i, --index:

Required: No

Default: true

Show the index of each patch. The index can be used with --ei and --di in the patch subcommand.

java -jar morphe-desktop-*-all.jar list-patches --patches patches.mpp

-f, --filter-package-name:

Required: No

Default: -

Only show patches that are compatible with the specified package name.

java -jar morphe-desktop-*-all.jar list-patches --patches patches.mpp --filter-package-name com.google.android.youtube

-x, --include-experimental:

Required: No

Default: false

By default, only stable app versions are listed. Pass this flag to also include experimental versions.

java -jar morphe-desktop-*-all.jar list-patches --patches patches.mpp --include-experimental

Subcommand 3: list-versions

Lists the most common compatible app versions for the patches in the supplied MPP files. Useful for knowing which APK version to download before patching.

java -jar morphe-desktop-*-all.jar list-versions --patches patches.mpp [flag/s]

Here is a quick lookup for all the flags under this subcommand:

--patches:

Required: Yes

Default: -

One or more paths to .mpp patch files or GitHub or GitLab repository URLs. When a URL is provided, Morphe downloads the .mpp file and caches it for future runs.

java -jar morphe-desktop-*-all.jar list-versions --patches patches.mpp
java -jar morphe-desktop-*-all.jar list-versions --patches https://github.com/MorpheApp/morphe-patches

--prerelease:

Required: No

Default: false

When using a GitHub or GitLab repo URL with --patches, fetch the latest dev pre-release instead of the latest stable release.

java -jar morphe-desktop-*-all.jar list-versions --patches https://github.com/MorpheApp/morphe-patches --prerelease

-f, --filter-package-names:

Required: No

Default: -

Only show versions for the specified package names. Can be used to check versions for a specific app.

java -jar morphe-desktop-*-all.jar list-versions --patches patches.mpp -f com.google.android.youtube

-u, --count-unused-patches:

Required: No

Default: false

Include patches that are not enabled by default when calculating the most common compatible versions. By default, only patches that are enabled are counted.

java -jar morphe-desktop-*-all.jar list-versions --patches patches.mpp --count-unused-patches

-x, --include-experimental:

Required: No

Default: false

By default, only stable app versions are counted and shown. Pass this flag to also include experimental versions.

java -jar morphe-desktop-*-all.jar list-versions --patches patches.mpp --include-experimental

Subcommand 4: options-create

Creates or updates an options JSON file for controlling which patches are enabled/disabled and their option values. The generated file can be passed to the patch subcommand with --options-file.

java -jar morphe-desktop-*-all.jar options-create [flag/s]

Here is a quick lookup for all the flags under this subcommand:

-p, --patches:

Required: Yes

Default: -

One or more paths to .mpp patch files or GitHub or GitLab repository URLs to generate options from. When a URL is provided, Morphe downloads the .mpp file and caches it for future runs.

java -jar morphe-desktop-*-all.jar options-create -p patches.mpp -o options.json
java -jar morphe-desktop-*-all.jar options-create -p https://github.com/MorpheApp/morphe-patches -o options.json

--prerelease:

Required: No

Default: false

When using a GitHub or GitLab repo URL with --patches, fetch the latest dev pre-release instead of the latest stable release.

java -jar morphe-desktop-*-all.jar options-create -p https://github.com/MorpheApp/morphe-patches --prerelease -o options.json

-o, --out:

Required: Yes

Default: -

Path to the output JSON file. If the file already exists, Morphe will merge the current patches into it - preserving your existing settings, adding new patches, and removing patches that no longer exist.

java -jar morphe-desktop-*-all.jar options-create -p patches.mpp -o options.json

-f, --filter-package-name:

Required: No

Default: -

Only include patches compatible with the specified package name in the generated options file.

java -jar morphe-desktop-*-all.jar options-create -p patches.mpp -o options.json -f com.google.android.youtube

Options JSON Workflow

The options JSON file lets you save your patch preferences and reuse them across multiple patching sessions. Here's the typical workflow:

Step 1: Generate the options file

Use options-create to generate a JSON file with all available patches and their default settings:

java -jar morphe-desktop-*-all.jar options-create -p patches.mpp -o options.json

Step 2: Edit the file

Open options.json in any text editor. You can enable/disable patches and set option values. The file contains a list of patch bundles, each with patch entries that look like:

{
  "patchName": {
    "enabled": true,
    "options": {
      "optionKey": "optionValue"
    }
  }
}

Set "enabled": false to disable a patch, or change option values as needed.

Step 3: Patch using the options file

Pass your customized options file to the patch command:

java -jar morphe-desktop-*-all.jar patch -p patches.mpp --options-file options.json your_app.apk

Step 4: Keep the file in sync (optional)

When you update your .mpp file to a newer version, patches may be added or removed. You have two ways to sync:

• Re-run options-create - this merges new patches in while preserving your existing settings:

  java -jar morphe-desktop-*-all.jar options-create -p patches.mpp -o options.json
  

• Use --options-update during patching - this auto-updates the file after patching:

  java -jar morphe-desktop-*-all.jar patch -p patches.mpp --options-file options.json --options-update your_app.apk
  

Subcommand 5: utility

Parent command for utility operations. It allows for things like manually installing or uninstalling apps via ADB, clearing the cache directory, etc. Has three sub-subcommands: install, uninstall, and clear-cache.

utility install

Manually install an APK file to one or more ADB-connected devices.

java -jar morphe-desktop-*-all.jar utility install [flag/s] [device-serial...]

-a, --apk:

Required: Yes

Default: -

Path to the APK file you want to install.

java -jar morphe-desktop-*-all.jar utility install -a patched_app.apk

-m, --mount:

Required: No

Default: -

Mount the APK on top of an existing app instead of a regular install. Pass the package name of the app to mount over. Requires root access.

java -jar morphe-desktop-*-all.jar utility install -a patched_app.apk -m com.google.android.youtube

--route-links:

Required: No

Default: -

After installing, route the app's supported web links to it ("open with"), so they open in the patched app instead of the browser or the stock app. The package name is read from the APK, so no value is needed.

java -jar morphe-desktop-*-all.jar utility install -a patched_app.apk --route-links

--disable-stock:

Required: No

Default: -

Use with --route-links. Also stops the named stock package from handling those links – needed when a rename patch was applied and the original app is still installed.

java -jar morphe-desktop-*-all.jar utility install -a patched_youtube.apk --route-links --disable-stock com.google.android.youtube

Positional argument (device serials):

Required: No

Default: First connected device

One or more ADB device serials to install to. If not provided, installs to the first connected device.

java -jar morphe-desktop-*-all.jar utility install -a patched_app.apk SERIAL1 SERIAL2

utility uninstall

Manually uninstall a patched app from one or more ADB-connected devices.

java -jar morphe-desktop-*-all.jar utility uninstall [flag/s] [device-serial...]

-p, --package-name:

Required: Yes

Default: -

The package name of the app to uninstall.

java -jar morphe-desktop-*-all.jar utility uninstall -p com.google.android.youtube

-u, --unmount:

Required: No

Default: false

If the app was installed by mounting (using --mount), use this flag to unmount it instead of a regular uninstall.

java -jar morphe-desktop-*-all.jar utility uninstall -p com.google.android.youtube --unmount

Positional argument (device serials):

Required: No

Default: First connected device

One or more ADB device serials to uninstall from. If not provided, uninstalls from the first connected device.

java -jar morphe-desktop-*-all.jar utility uninstall -p com.google.android.youtube SERIAL1 SERIAL2

utility clear-cache

Delete Morphe's cached data: downloaded patch files, logs, and temporary files. By default it prints a short confirmation message.

java -jar morphe-desktop-*-all.jar utility clear-cache [flag/s]

--info:

Required: No

Default: false

Show how much was cleared from each location (patches, logs, temp) with file counts and the total space freed, instead of just a confirmation line.

java -jar morphe-desktop-*-all.jar utility clear-cache --info

Value Types Reference

When setting patch options with -O or in an options JSON file, values are typed. Using the wrong type can cause a patch to fail. Here are the supported types and how to format them:

Escaping:

Quotes and commas inside strings need to be escaped with \:

• \" - escaped double quote
• \' - escaped single quote
• \, - escaped comma (treated as part of the string, not a list separator)

List items are parsed recursively, so escaping works inside lists too:

Example command:

java -jar morphe-desktop-*-all.jar patch -p patches.mpp -e "Patch name" -OstringKey=\'1\' your_app.apk

This sets stringKey to the string "1" instead of the integer 1.

🔨️ Building

Want to build Morphe Desktop from source instead of grabbing a release? Here's how.

Requirements: Java Development Kit 17 (e.g. Azul Zulu or OpenJDK).

1. Clone the repository:

   git clone git@github.com:MorpheApp/morphe-desktop.git
   cd morphe-desktop
   

2. Build it:

   ./gradlew build
   

gpr.user = your-github-username
gpr.key = your-token

When the build finishes, the runnable JAR is at build/libs/morphe-desktop-<version>-all.jar.