Experimental integration of CLI support

[JingMatrix]

This commit is initially squashed from the repo https://github.com/AnatolyJacobs/LSPosed_CLI.

Further work are required to improve / polish it.

Refer to https://github.com/mywalkb/LSPosed_mod/wiki/CLI for current CLI interface.

[JingMatrix]

LSPosed Command Line Interface (CLI)

The LSPosed Command Line Interface (CLI) is a powerful, professional tool designed for developers, power users, and automation experts. It provides direct shell access to manage the LSPosed framework, making it ideal for scripting, bulk operations, and advanced management tasks.

The CLI binary is located at /data/adb/lspd/bin/cli.

Prerequisites

Before using the CLI, please ensure the following conditions are met.

1. Root Access

The CLI communicates with the privileged LSPosed daemon and requires root access to function. Commands must be run as the superuser, typically via su -c.

2. Enabling the CLI Feature

For security, the CLI is disabled by default. You must enable it first from the LSPosed Manager application:

1. Open the LSPosed Manager app.
2. Navigate to Settings.
3. Locate the Command line interface section.
4. Turn on the Enable CLI feature switch.

First Steps: Authentication and Session Setup

The best way to begin is by using the login command, which verifies your connection and helps you set up a seamless shell session.

Step 1: Get Your PIN
After enabling the CLI feature in the Manager, a secure, random PIN will be displayed directly below the switch. You will need this for your first command.

Step 2: Create a Shell Alias (Highly Recommended)
The full path to the CLI is cumbersome. Creating a shell alias will make using the tool much easier.

# In your ADB shell:
alias lsposed-cli='su -c /data/adb/lspd/bin/cli'

Now you can simply use lsposed-cli for all subsequent commands.

Step 3: Log In and Set Your Session Variable
Run the login command, providing your PIN.

lsposed-cli --pin <your-pin-from-the-app> login

The command will verify your PIN and give you an export command.

Example Output:

✅ Authentication successful.

To avoid typing the PIN for every command in this shell session, run:

    export LSPOSED_CLI_PIN="<your-pin-from-the-app>"

You can then run commands like 'lsposed-cli status' without the --pin argument.

Step 4: Run the Export Command
Copy the export ... command and run it in your shell. For the rest of your session, you will be authenticated and will not need to use the --pin argument again.

Authentication Model

The CLI is protected by a secure PIN to prevent unauthorized access.

Key Characteristics of the PIN:

• Generated on Enable: A new, cryptographically secure PIN is generated every time you toggle the CLI feature on.
• Volatile Storage: The PIN is stored only in the daemon's memory. It is never written to disk.
• Lost on Reboot: Because the PIN is in-memory, it is permanently lost when the device reboots or the lspd process restarts. You must re-enable the CLI in the Manager to generate a new PIN.

Debug Builds

For developer convenience, debug builds of LSPosed have the CLI enabled by default and do not require PIN authentication.

Global Options

These options are available for most commands.

JSON Output for Scripting (--json)

This flag formats the command's output as structured JSON, which is ideal for parsing in scripts.

Interactive Output (Default):

$ lsposed-cli status
API Version: 93
Injection Interface: Zygisk
...

Scriptable Output (--json):

$ lsposed-cli status --json
{
  "xposedApiVersion": 93,
  "injectionInterface": "Zygisk",
  ...
}

Getting Help (--help)

Every command and subcommand supports the --help flag to display its specific usage, options, and descriptions.

---

Command Reference

status

Displays the current status and version of the LSPosed framework and the device.

Usage: lsposed-cli status [options]

Example:

$ lsposed-cli status
API Version: 93
Injection Interface: Zygisk
Framework Version: 1.8.6 (6915)
System Version: 13 (API 33)
Device: Google Pixel 7 Pro
System ABI: arm64-v8a

login

Verifies the authentication PIN and provides a session variable for convenience.

Usage: lsposed-cli login [options]

modules

Manages Xposed modules. This is a parent command.

Subcommands:

• ls: Lists installed modules.
• set: Enables or disables modules.

modules ls

Usage: lsposed-cli modules ls [--enabled | --disabled]

Example:

$ lsposed-cli modules ls --enabled
PACKAGE                                       UID        STATUS
com.tsng.hidemyapplist                        10306      enabled
org.matrix.chromext                           10307      enabled

modules set

Usage: lsposed-cli modules set [--enable | --disable] <module_name...>

Example:

$ lsposed-cli modules set --enable com.example.mymodule
com.example.mymodule: Module successfully enabled.

$ lsposed-cli modules set --disable com.example.mymodule
com.example.mymodule: Module successfully disabled.

scope

Manages the application scope for a specific module.

Subcommands:

• ls: Displays a module's scope.
• set: Modifies a module's scope.

scope ls

Usage: lsposed-cli scope ls <module_name>

Example:

$ lsposed-cli scope ls com.tsng.hidemyapplist
com.tsng.hidemyapplist/0
system/0

scope set

Usage: lsposed-cli scope set [-s | -a | -d] <module_name> <package/user...>
Applications must be specified in the format package_name/user_id.

Options:

• -s, --set: Overwrites the entire scope with the provided list.
• -a, --append: Adds the provided applications to the existing scope.
• -d, --remove: Removes the provided applications from the existing scope.

Example:

# Replace the entire scope for 'mymodule' with just the Settings app for user 0
$ lsposed-cli scope set -s com.example.mymodule com.android.settings/0
Successfully updated scope for com.example.mymodule.

log

Streams and manages the framework logs. This command does not support --json output.

Usage: lsposed-cli log [options]

Options:

• -f, --follow: Continuously stream new log entries.
• -v, --verbose: Show the verbose framework logs instead of module logs.
• -c, --clear: Clear the log file before printing.

Example:

# Follow the verbose logs, clearing them first
$ lsposed-cli log -v -c -f

backup

Creates a compressed backup of module settings (enabled/disabled status, scope, etc.).

Usage: lsposed-cli backup [options] [module_name...]

Example:

# Back up all modules to a timestamped file in the current directory
$ lsposed-cli backup
Backup created successfully at: LSPosed_2025-08-22T10:00:00.lsp.gz

# Back up a specific module to a custom file
$ lsposed-cli backup --file my_modules.bak com.example.mymodule

restore

Restores module settings and scopes from a backup file.

Usage: lsposed-cli restore --file <path> [module_name...]

Example:

# Restore all modules from the backup file
$ lsposed-cli restore --file my_modules.bak
Restoring settings for: com.example.mymodule
...
Restore completed successfully.

# Restore only a specific module from the backup
$ lsposed-cli restore --file my_modules.bak com.example.mymodule

revoke-pin

Immediately invalidates the current CLI PIN, disabling all further CLI access.

Usage: lsposed-cli revoke-pin

Example:

$ lsposed-cli revoke-pin
✅ PIN has been revoked. You must re-enable the CLI from the Manager app to generate a new one.

[Auties00]

Hi, is there any plan to ship this?
If yes what's missing?
Also might I add that I don't think the CLI should require a code or be enabled manually from the Manager GUI, I think that a better mechanism would be to have it enabled by default, but to require root access to use it like Magisk's CLI does so the authorization mechanism is streamlined and automations are possible when using an avd

[JingMatrix]

For debug build of this feature, there is no need to input authorization code (for the sake of dev convenience).

As for the release build, I plan to allow users invoke the commandline with merely shell access permission.
It is for this feature, that I am going to implement (maybe soon), that the pr is not merged yet.