CLI Reference

Waydroid is primarily controlled through the waydroid command-line tool. This page documents all available commands and their options.

Global Options

These options can be used with any command:

  • -V, --version: Display the Waydroid version.
  • -l <path>, --log <path>: Specify a custom path for the log file.
  • --details-to-stdout: Print detailed output (like build logs) to standard output instead of the log file.
  • -v, --verbose: Enable verbose logging for more detailed debug information.
  • -q, --quiet: Suppress all log output.
  • -w, --wait: Wait for the init process to complete before running a command.

waydroid init

Initializes the Waydroid environment. This includes downloading system/vendor images and setting up configuration files. Requires root privileges.

  • -i, --images_path <path>: Specify a custom path for Waydroid images.
  • -f, --force: Force re-initialization, overwriting existing configs and images.
  • -c, --system_channel <url>: URL for a custom system OTA update channel.
  • -v, --vendor_channel <url>: URL for a custom vendor OTA update channel.
  • -r, --rom_type <type>: ROM type (e.g., lineage, bliss).
  • -s, --system_type <type>: System image type (e.g., VANILLA, GAPPS).

waydroid status

Displays the current status of the Waydroid session and container.

waydroid upgrade

Upgrades the Waydroid system and vendor images to the latest versions from the configured OTA channels.

  • -o, --offline: Only update configuration files without downloading new images.

waydroid log

Follows the Waydroid log file (/var/lib/waydroid/waydroid.log).

  • -n, --lines <count>: Number of initial lines to display (default: 60).
  • -c, --clear: Clear the log file before displaying it.

waydroid session

Manages the user-level Waydroid session.

  • waydroid session start: Starts the session services. The container is launched on-demand.
  • waydroid session stop: Stops the session and the container.

waydroid container

Directly controls the Waydroid LXC container. Requires root privileges.

  • waydroid container start: Starts the container service.
  • waydroid container stop: Stops the container.
  • waydroid container restart: Restarts the container.
  • waydroid container freeze: Pauses the container processes.
  • waydroid container unfreeze: Resumes a frozen container.

waydroid app

Manages Android applications within the container.

  • waydroid app install <PACKAGE>: Installs an app from an APK file.
  • waydroid app remove <PACKAGE>: Uninstalls an app using its package name.
  • waydroid app launch <PACKAGE>: Launches an installed app by its package name.
  • waydroid app intent <ACTION> <URI>: Launches an Android intent.
  • waydroid app list: Lists all installed user applications.

waydroid prop

Gets or sets Android system properties.

  • waydroid prop get <key>: Retrieves the value of a property.
  • waydroid prop set <key> <value>: Sets the value of a property.

waydroid show-full-ui

Launches the default Android launcher, showing the full Android user interface in a window.

waydroid first-launch

Provides a graphical interface to initialize Waydroid and then starts it.

waydroid shell

Executes a command inside the Waydroid container. If no command is given, it opens an interactive shell. Requires root privileges.

  • [COMMAND]: The command to execute. If omitted, /system/bin/sh is run.
  • -u, --uid <UID>: Run the command as the specified user ID.
  • -g, --gid <GID>: Run the command as the specified group ID.
  • -s, --context <CONTEXT>: Transition to a specific SELinux or AppArmor security context.
  • -L, --nolsm: Disables mandatory access control transitions (SELinux/AppArmor). Warning: This is a dangerous option.
  • -C, --allcaps: Prevents LXC from dropping capabilities. Warning: This is a dangerous option.
  • -G, --nocgroup: Prevents LXC from switching to the container's cgroup. Warning: This is a dangerous option.

waydroid logcat

A shortcut to view the Android logcat output. Equivalent to waydroid shell logcat.

waydroid adb

Manages the Android Debug Bridge (ADB) connection to the container.

  • waydroid adb connect: Connects the host's ADB to the Waydroid container.
  • waydroid adb disconnect: Disconnects ADB from the container.