### Complete Automation Example

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

A comprehensive example demonstrating the lifecycle management of a VM, including creation, configuration, starting, app installation, interaction, and cleanup.

```APIDOC
## POST /vm/automate

### Description
Demonstrates a complete automation workflow for a virtual machine, including creation, configuration, app management, and cleanup.

### Method
POST

### Endpoint
/vm/automate

### Parameters
No specific parameters for this example, but it internally uses various VM management APIs.

### Request Example
```json
{
  "description": "Full VM lifecycle automation example"
}
```

### Example Workflow
1. Create a new VM.
2. Configure VM settings (CPU, memory, resolution).
3. Start the VM and wait for it to boot.
4. Get ADB connection details.
5. Install an APK.
6. Start an application.
7. Simulate user input (text, keystrokes).
8. Change GPS location.
9. List installed apps.
10. Stop and delete the VM.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of the automation process completion or status.

#### Response Example
```json
{
  "message": "VM automation completed successfully."
}
```
```

--------------------------------

### Complete VM Lifecycle Automation Example

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

A comprehensive script demonstrating VM creation, configuration, starting, app management, user interaction simulation, and cleanup. Includes error handling for PyMemuc operations.

```python
from pymemuc import PyMemuc, PyMemucError
import time

memuc = PyMemuc(debug=True)

try:
    # Create and configure a new VM
    vm_index = memuc.create_vm(vm_version="96")
    print(f"Created VM at index: {vm_index}")

    # Configure VM settings
    memuc.set_configuration_vm("cpus", "2", vm_index=vm_index)
    memuc.set_configuration_vm("memory", "2048", vm_index=vm_index)
    memuc.set_configuration_vm("is_customed_resolution", "1", vm_index=vm_index)
    memuc.set_configuration_vm("resolution_width", "720", vm_index=vm_index)
    memuc.set_configuration_vm("resolution_height", "1280", vm_index=vm_index)

    # Start the VM
    memuc.start_vm(vm_index=vm_index, timeout=120)
    print("VM started")
    time.sleep(30)  # Wait for Android to fully boot

    # Get ADB connection for external tools
    ip, port = memuc.get_adb_connection(vm_index=vm_index)
    print(f"ADB available at {ip}:{port}")

    # Install and run an app
    memuc.install_apk_vm("C:/Apps/testapp.apk", vm_index=vm_index)
    memuc.start_app_vm("com.example.testapp", vm_index=vm_index)

    # Simulate user interaction
    time.sleep(5)
    memuc.input_text_vm("test@example.com", vm_index=vm_index)
    memuc.trigger_keystroke_vm("back", vm_index=vm_index)

    # Set GPS location for location-based testing
    memuc.change_gps_vm(latitude=37.7749, longitude=-122.4194, vm_index=vm_index)

    # List installed apps
    apps = memuc.get_app_info_list_vm(vm_index=vm_index)
    print(f"Installed apps: {len(apps)}")

    # Cleanup
    memuc.stop_vm(vm_index=vm_index, timeout=60)
    memuc.delete_vm(vm_index=vm_index)
    print("VM cleaned up")

except PyMemucError as e:
    print(f"Error during automation: {e}")
```

--------------------------------

### Start VM

Source: https://github.com/pyclashbot/pymemuc/blob/master/demo/demo.ipynb

Start a virtual machine with a specified timeout. The timeout is in seconds.

```python
memuc.start_vm(vm_index=vm_index, timeout=60)
```

--------------------------------

### Start App on VM using PyMemuc

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Launches an installed application on a running VM. Can specify the VM by index or name.

```python
from pymemuc import PyMemuc

memuc = PyMemuc()

# Start app by package name
memuc.start_app_vm("com.android.chrome", vm_index=0, timeout=30)
print("Chrome started")

# Start app by VM name
memuc.start_app_vm("com.android.settings", vm_name="MyVM")
```

--------------------------------

### Installation

Source: https://github.com/pyclashbot/pymemuc/blob/master/demo/demo.ipynb

Instructions for installing the PyMemuc package from PyPI or locally.

```APIDOC
## Installation

### Install from PyPI

```python
%pip install --force-reinstall --no-cache-dir pymemuc
```

### Install Locally

```python
!poetry install --with dev --without docs
```
```

--------------------------------

### start_vm - Start a Virtual Machine

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Starts a specified VM with optional headless mode and timeout configuration.

```APIDOC
## POST /start_vm

### Description
Starts a specified VM with optional headless mode and timeout configuration.

### Method
`start_vm()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Parameters
- **vm_index** (int) - Optional - The index of the VM to start.
- **vm_name** (str) - Optional - The name of the VM to start.
- **headless** (bool) - Optional - Start the VM in headless mode (no GUI).
- **timeout** (int) - Optional - Timeout in seconds for the operation.
- **non_blocking** (bool) - Optional - Start the VM in non-blocking mode (returns immediately).

### Request Example
```python
from pymemuc import PyMemuc, PyMemucError

memuc = PyMemuc()

# Start VM by index with timeout
try:
    memuc.start_vm(vm_index=0, timeout=60)
    print("VM started successfully")
except PyMemucError as e:
    print(f"Failed to start VM: {e}")

# Start VM by name in headless mode (no GUI)
memuc.start_vm(vm_name="MyTestVM", headless=True, timeout=120)

# Start VM in non-blocking mode (returns immediately)
memuc.start_vm(vm_index=0, non_blocking=True)
```

### Response
#### Success Response (200)
- **message** (str) - Confirmation message.

#### Response Example
```json
{
  "message": "VM started successfully"
}
```
```

--------------------------------

### Install PyMemuc using pip

Source: https://github.com/pyclashbot/pymemuc/blob/master/docs/source/quickstart.rst

Install the PyMemuc library using pip. This is the first step to using the library.

```console
$ pip install pymemuc
```

--------------------------------

### Start VM

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Start a MEmu virtual machine by index or name. Supports headless mode, custom timeouts, and non-blocking execution.

```python
from pymemuc import PyMemuc, PyMemucError

memuc = PyMemuc()

# Start VM by index with timeout
try:
    memuc.start_vm(vm_index=0, timeout=60)
    print("VM started successfully")
except PyMemucError as e:
    print(f"Failed to start VM: {e}")
```

```python
# Start VM by name in headless mode (no GUI)
memuc.start_vm(vm_name="MyTestVM", headless=True, timeout=120)
```

```python
# Start VM in non-blocking mode (returns immediately)
memuc.start_vm(vm_index=0, non_blocking=True)
```

--------------------------------

### Create a New VM

Source: https://github.com/pyclashbot/pymemuc/blob/master/demo/demo.ipynb

Create a new virtual machine and get its index.

```python
vm_index = memuc.create_vm()
```

--------------------------------

### Basic PyMemuc Usage

Source: https://github.com/pyclashbot/pymemuc/blob/master/README.md

Demonstrates initializing PyMemuc, creating a VM, listing VMs, and controlling VM state (start/stop). Ensure MEMUC is installed and accessible.

```python
# import the PyMemuc class
from pymemuc import PyMemuc

# create a PyMemuc instance, doing so will automatically link to the MEMUC executable
memuc = PyMemuc()

# create a new vm, saving the index
index = memuc.create_vm()

# list out all vms
print(memuc.list_vm_info())

# start the vm
memuc.start_vm(index)

# stop the vm
memuc.stop_vm(index)
```

--------------------------------

### Install APK on VM

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Installs an Android application package (APK) onto a virtual machine. Supports installation by VM index or name, and can optionally create a desktop shortcut.

```python
memuc.install_apk_vm("C:/Apps/myapp.apk", vm_index=0)
```

```python
memuc.install_apk_vm("C:/Apps/myapp.apk", vm_index=0, create_shortcut=True)
```

```python
memuc.install_apk_vm("/path/to/app.apk", vm_name="MyVM")
```

--------------------------------

### Install APK on VM

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Installs an Android application package (APK) onto a virtual machine. Supports creating desktop shortcuts.

```APIDOC
## POST /vm/install_apk

### Description
Installs an Android application package (APK) onto a specified virtual machine.

### Method
POST

### Endpoint
/vm/install_apk

### Parameters
#### Request Body
- **apk_path** (string) - Required - The file path to the APK to install.
- **vm_index** (integer) - Optional - The index of the VM where the APK should be installed.
- **vm_name** (string) - Optional - The name of the VM where the APK should be installed.
- **create_shortcut** (boolean) - Optional - If true, a desktop shortcut for the app will be created.

### Request Example
```json
{
  "apk_path": "C:/Apps/myapp.apk",
  "vm_index": 0
}
```

```json
{
  "apk_path": "/path/to/app.apk",
  "vm_name": "MyVM",
  "create_shortcut": true
}
```

### Response
#### Success Response (200)
- **status** (boolean) - Indicates if the APK installation process started successfully.
- **output** (string) - A message detailing the result of the operation.

#### Response Example
```json
{
  "status": true,
  "output": "APK installation initiated."
}
```
```

--------------------------------

### App Management on VM

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Functions to manage applications within a Memu VM, including starting, stopping, and retrieving a list of installed apps.

```APIDOC
## start_app_vm - Start an App on VM

Launches an installed application on a running VM.

### Method
POST

### Endpoint
/api/v1/vm/start_app

### Parameters
#### Query Parameters
- **packageName** (string) - Required - The package name of the app to start.
- **vm_index** (integer) - Optional - The index of the VM to target.
- **vm_name** (string) - Optional - The name of the VM to target.
- **timeout** (integer) - Optional - The timeout in seconds for the operation.

### Request Example
```json
{
  "packageName": "com.android.chrome",
  "vm_index": 0,
  "timeout": 30
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure of the operation.

#### Response Example
```json
{
  "status": "success"
}
```

## stop_app_vm - Stop an App on VM

Stops a running application on a VM.

### Method
POST

### Endpoint
/api/v1/vm/stop_app

### Parameters
#### Query Parameters
- **packageName** (string) - Required - The package name of the app to stop.
- **vm_index** (integer) - Optional - The index of the VM to target.
- **vm_name** (string) - Optional - The name of the VM to target.

### Request Example
```json
{
  "packageName": "com.android.chrome",
  "vm_index": 0
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure of the operation.

#### Response Example
```json
{
  "status": "success"
}
```

## get_app_info_list_vm - Get Installed Apps List

Retrieves a list of all installed applications on a VM.

### Method
GET

### Endpoint
/api/v1/vm/apps

### Parameters
#### Query Parameters
- **vm_index** (integer) - Optional - The index of the VM to target.
- **vm_name** (string) - Optional - The name of the VM to target.
- **timeout** (integer) - Optional - The timeout in seconds for the operation.

### Response
#### Success Response (200)
- **apps** (array) - A list of package names of installed applications.

#### Response Example
```json
{
  "apps": [
    "com.android.chrome",
    "com.android.settings",
    "com.example.myapp"
  ]
}
```
```

--------------------------------

### Get Installed Apps List from VM using PyMemuc

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Retrieves a list of all installed applications on a VM. Can specify the VM by index or name and set a timeout.

```python
from pymemuc import PyMemuc

memuc = PyMemuc()

# Get list of installed apps
apps = memuc.get_app_info_list_vm(vm_index=0, timeout=15)
for app in apps:
    print(f"Package: {app}")
# Output:
# Package: com.android.chrome
# Package: com.android.settings
# Package: com.example.myapp

# Get apps by VM name
apps = memuc.get_app_info_list_vm(vm_name="MyVM")
```

--------------------------------

### Basic PyMemuc VM Operations

Source: https://github.com/pyclashbot/pymemuc/blob/master/docs/source/quickstart.rst

Demonstrates the basic lifecycle of a virtual machine using PyMemuc. Ensure MEMUC is installed and accessible.

```python
# import the PyMemuc class
from pymemuc import PyMemuc

# create a PyMemuc instance, doing so will automatically link to the MEMUC executable
memuc = PyMemuc()

# create a new vm, saving the index
index = memuc.create_vm()

# start the vm
memuc.start_vm(index)

# stop the vm
memuc.stop_vm(index)

# delete the vm
memuc.delete_vm(index)
```

--------------------------------

### Install PyMemuc Locally

Source: https://github.com/pyclashbot/pymemuc/blob/master/demo/demo.ipynb

Install the PyMemuc package locally using Poetry, including development dependencies but excluding documentation build dependencies.

```bash
!poetry install --with dev --without docs
```

--------------------------------

### Install PyMemuc from PyPI

Source: https://github.com/pyclashbot/pymemuc/blob/master/demo/demo.ipynb

Use this command to install or reinstall the PyMemuc package from the Python Package Index.

```bash
%pip install --force-reinstall --no-cache-dir pymemuc
```

--------------------------------

### List Apps on VM

Source: https://github.com/pyclashbot/pymemuc/blob/master/demo/demo.ipynb

Retrieve a list of installed applications on a specified virtual machine.

```python
memuc.get_app_info_list_vm(vm_index=vm_index)
```

--------------------------------

### Install pymemuc

Source: https://github.com/pyclashbot/pymemuc/blob/master/README.md

Install the pymemuc library using pip. This command is used to add the library to your Python environment.

```bash
pip install pymemuc
```

--------------------------------

### Get ADB Connection Info using PyMemuc

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Retrieves the ADB connection IP address and port for a VM. Useful for connecting external ADB clients. Includes an example of using subprocess to connect.

```python
from pymemuc import PyMemuc
import subprocess

memuc = PyMemuc()

# Get ADB connection details
ip, port = memuc.get_adb_connection(vm_index=0, timeout=10)
print(f"ADB connection: {ip}:{port}")  # Output: ADB connection: 127.0.0.1:21503

# Use with external ADB
subprocess.run(["adb", "connect", f"{ip}:{port}"])
```

--------------------------------

### Get VM Configuration

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Retrieves a specific configuration value for a virtual machine.

```APIDOC
## GET /vm/configuration

### Description
Retrieves the value of a specific configuration setting for a virtual machine.

### Method
GET

### Endpoint
/vm/configuration

### Parameters
#### Query Parameters
- **config_key** (string) - Required - The key of the configuration setting to retrieve (e.g., "cpus", "memory", "imei").
- **vm_index** (integer) - Optional - The index of the VM.
- **vm_name** (string) - Optional - The name of the VM.

### Request Example
```
GET /vm/configuration?config_key=cpus&vm_index=0
```

```
GET /vm/configuration?config_key=imei&vm_name=MyVM
```

### Response
#### Success Response (200)
- **value** (string) - The value of the requested configuration setting.

#### Response Example
```json
{
  "value": "2"
}
```
```

--------------------------------

### Get VM CPU Configuration

Source: https://github.com/pyclashbot/pymemuc/blob/master/demo/demo.ipynb

Retrieve the current CPU configuration for a specific virtual machine.

```python
memuc.get_configuration_vm("cpus", vm_index=vm_index)
```

--------------------------------

### Get VM ADB Connection Info

Source: https://github.com/pyclashbot/pymemuc/blob/master/demo/demo.ipynb

Obtain the ADB connection details (IP address and port) for a specified virtual machine using its index.

```python
memuc.get_adb_connection(vm_index)
```

--------------------------------

### Get VM Configuration Value

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Retrieves a specific configuration value for a VM, identified by its index. Supports various keys like 'cpus', 'memory', 'resolution_width', and device identifiers.

```python
cpus = memuc.get_configuration_vm("cpus", vm_index=0)
```

```python
memory = memuc.get_configuration_vm("memory", vm_index=0)
```

```python
width = memuc.get_configuration_vm("resolution_width", vm_index=0)
height = memuc.get_configuration_vm("resolution_height", vm_index=0)
```

```python
imei = memuc.get_configuration_vm("imei", vm_index=0)
```

--------------------------------

### Check if VM is Running

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Checks the running status of a specific VM using its index. This is useful for conditional logic before starting or interacting with a VM.

```python
if memuc.vm_is_running(vm_index=0):
    print("VM is running")
else:
    print("VM is not running")
```

```python
if not memuc.vm_is_running(vm_index=0):
    memuc.start_vm(vm_index=0, timeout=60)
```

--------------------------------

### Uninstall APK from VM

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Removes an installed application from a virtual machine using its package name. Supports targeting by VM index or name.

```APIDOC
## POST /vm/uninstall_apk

### Description
Uninstalls an application from a virtual machine based on its package name.

### Method
POST

### Endpoint
/vm/uninstall_apk

### Parameters
#### Request Body
- **package_name** (string) - Required - The package name of the application to uninstall (e.g., "com.example.myapp").
- **vm_index** (integer) - Optional - The index of the VM from which to uninstall the app.
- **vm_name** (string) - Optional - The name of the VM from which to uninstall the app.

### Request Example
```json
{
  "package_name": "com.example.myapp",
  "vm_index": 0
}
```

```json
{
  "package_name": "com.android.chrome",
  "vm_name": "MyVM"
}
```

### Response
#### Success Response (200)
- **status** (boolean) - Indicates if the APK uninstallation process started successfully.
- **output** (string) - A message detailing the result of the operation.

#### Response Example
```json
{
  "status": true,
  "output": "APK uninstallation initiated."
}
```
```

--------------------------------

### Set VM Display Configuration

Source: https://github.com/pyclashbot/pymemuc/blob/master/demo/demo.ipynb

Configure custom resolution, DPI, and window mode for a virtual machine. Ensure 'is_customed_resolution' is set to '1' to enable custom settings.

```python
memuc.set_configuration_vm("is_customed_resolution", "1", vm_index=vm_index)
memuc.set_configuration_vm("resolution_width", "460", vm_index=vm_index)
memuc.set_configuration_vm("resolution_height", "680", vm_index=vm_index)
memuc.set_configuration_vm("vbox_dpi", "160", vm_index=vm_index)
memuc.set_configuration_vm("start_window_mode", "1", vm_index=vm_index)  # set to remember window location
```

--------------------------------

### Manually Set VM Display Configuration

Source: https://github.com/pyclashbot/pymemuc/blob/master/demo/demo.ipynb

Apply display configuration settings to a virtual machine using the memuc_run command with specific parameters.

```python
memuc.memuc_run(["-i", str(vm_index), "setconfigex", "is_customed_resolution", "1"])
```

--------------------------------

### Create New VM

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Create a new MEmu virtual machine with a specified Android version. The VM index is returned upon successful creation.

```python
from pymemuc import PyMemuc

memuc = PyMemuc()

# Create a new VM with Android 9.0 (default)
vm_index = memuc.create_vm(vm_version="96")
print(f"Created VM with index: {vm_index}")  # Output: Created VM with index: 0
```

```python
# Create a VM with Android 7.1
vm_index_71 = memuc.create_vm(vm_version="76")
print(f"Created Android 7.1 VM with index: {vm_index_71}")
```

--------------------------------

### List All VMs with Disk Info

Source: https://github.com/pyclashbot/pymemuc/blob/master/demo/demo.ipynb

Retrieve a list of all virtual machines, including detailed disk information for each.

```python
memuc.list_vm_info(disk_info=True)
```

--------------------------------

### VM Configuration Keys Table

Source: https://github.com/pyclashbot/pymemuc/blob/master/docs/source/pymemuc.rst

Presents a table of VM configuration keys and their descriptions.

```APIDOC
## VM Configuration Keys

### Description
This table lists the available keys for VM configuration and provides a description for each key.

| Key | Description |
|---|---|
| [Key Name] | [Description of the key] |

*Note: This table is generated from `tables/vm_config_keys.csv`.*
```

--------------------------------

### create_vm - Create a New Virtual Machine

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Creates a new MEmu virtual machine with the specified Android version and returns the VM index.

```APIDOC
## POST /create_vm

### Description
Creates a new MEmu virtual machine with the specified Android version and returns the VM index.

### Method
`create_vm()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Parameters
- **vm_version** (str) - Optional - The Android version for the new VM. Defaults to "96" (Android 9.0).

### Request Example
```python
from pymemuc import PyMemuc

memuc = PyMemuc()

# Create a new VM with Android 9.0 (default)
vm_index = memuc.create_vm(vm_version="96")
print(f"Created VM with index: {vm_index}")

# Create a VM with Android 7.1
vm_index_71 = memuc.create_vm(vm_version="76")
print(f"Created Android 7.1 VM with index: {vm_index_71}")
```

### Response
#### Success Response (200)
- **vm_index** (int) - The index of the newly created VM.

#### Response Example
```json
{
  "vm_index": 0
}
```
```

--------------------------------

### Initialize PyMemuc

Source: https://github.com/pyclashbot/pymemuc/blob/master/demo/demo.ipynb

Instantiate the PyMemuc class. Set debug=True for verbose logging.

```python
from pymemuc import PyMemuc

memuc = PyMemuc(debug=True)
```

--------------------------------

### Input and Interaction Simulation

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Functions to simulate user input and device gestures on a VM.

```APIDOC
## trigger_keystroke_vm - Trigger Keystroke on VM

Simulates hardware key presses on a VM (back, home, menu, volume up/down).

### Method
POST

### Endpoint
/api/v1/vm/keystroke

### Parameters
#### Query Parameters
- **key** (string) - Required - The key to trigger (e.g., 'home', 'back', 'menu', 'volumeup', 'volumedown').
- **vm_index** (integer) - Optional - The index of the VM to target.
- **vm_name** (string) - Optional - The name of the VM to target.

### Request Example
```json
{
  "key": "home",
  "vm_index": 0
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure of the operation.

#### Response Example
```json
{
  "status": "success"
}
```

## input_text_vm - Input Text on VM

Types text into the currently focused input field on a VM.

### Method
POST

### Endpoint
/api/v1/vm/input_text

### Parameters
#### Query Parameters
- **text** (string) - Required - The text to input.
- **vm_index** (integer) - Optional - The index of the VM to target.
- **vm_name** (string) - Optional - The name of the VM to target.

### Request Example
```json
{
  "text": "Hello, World!",
  "vm_index": 0
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure of the operation.

#### Response Example
```json
{
  "status": "success"
}
```

## trigger_shake_vm - Trigger Shake Gesture

Simulates a device shake gesture on a VM.

### Method
POST

### Endpoint
/api/v1/vm/shake

### Parameters
#### Query Parameters
- **vm_index** (integer) - Optional - The index of the VM to target.
- **vm_name** (string) - Optional - The name of the VM to target.

### Request Example
```json
{
  "vm_index": 0
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure of the operation.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Import VM

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Imports a virtual machine from an OVA file. Supports non-blocking import for large files.

```APIDOC
## POST /vm/import

### Description
Imports a virtual machine from a specified OVA file.

### Method
POST

### Endpoint
/vm/import

### Parameters
#### Request Body
- **file_name** (string) - Required - The path to the OVA file to import.
- **non_blocking** (boolean) - Optional - If true, the import operation runs in the background.

### Request Example
```json
{
  "file_name": "backup.ova"
}
```

```json
{
  "file_name": "large_backup.ova",
  "non_blocking": true
}
```

### Response
#### Success Response (200)
- **status** (boolean) - Indicates if the import process started successfully.
- **output** (string) - A message detailing the result of the operation.

#### Response Example
```json
{
  "status": true,
  "output": "VM import initiated."
}
```
```

--------------------------------

### Trigger Keystroke on VM using PyMemuc

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Simulates hardware key presses on a VM, such as 'home', 'back', 'menu', 'volumeup', and 'volumedown'. Specify the VM by index or name.

```python
from pymemuc import PyMemuc
import time

memuc = PyMemuc()

# Press home button
memuc.trigger_keystroke_vm("home", vm_index=0)

# Press back button
memuc.trigger_keystroke_vm("back", vm_index=0)

# Press menu button
memuc.trigger_keystroke_vm("menu", vm_index=0)

# Adjust volume
memuc.trigger_keystroke_vm("volumeup", vm_index=0)
time.sleep(0.5)
memuc.trigger_keystroke_vm("volumedown", vm_index=0)
```

--------------------------------

### list_vm_info - List Virtual Machines Information

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Lists information about all VMs or a specific VM including index, title, running status, PID, and optional disk usage.

```APIDOC
## GET /list_vm_info

### Description
Lists information about all VMs or a specific VM including index, title, running status, PID, and optional disk usage.

### Method
`list_vm_info()`

### Parameters
#### Query Parameters
- **disk_info** (bool) - Optional - Include disk usage information.
- **running** (bool) - Optional - Filter VMs by running status.
- **vm_index** (int) - Optional - The index of the specific VM to get info for.
- **vm_name** (str) - Optional - The name of the specific VM to get info for.

### Request Example
```python
from pymemuc import PyMemuc

memuc = PyMemuc()

# List all VMs with disk info
vms = memuc.list_vm_info(disk_info=True)
for vm in vms:
    print(f"Index: {vm['index']}, Name: {vm['title']}, Running: {vm['running']}, "
          f"PID: {vm['pid']}, Disk: {vm['disk_usage']} bytes")

# List only running VMs
running_vms = memuc.list_vm_info(running=True)

# Get info for a specific VM by index
specific_vm = memuc.list_vm_info(vm_index=0)

# Get info for a specific VM by name
named_vm = memuc.list_vm_info(vm_name="MyVM")
```

### Response
#### Success Response (200)
- **vms** (list) - A list of VM information objects. Each object contains:
  - **index** (int) - The VM index.
  - **title** (str) - The VM name.
  - **running** (bool) - Whether the VM is running.
  - **pid** (int) - The process ID of the VM.
  - **disk_usage** (int) - The disk usage in bytes (if `disk_info` is True).

#### Response Example
```json
[
  {
    "index": 0,
    "title": "MEmu",
    "running": true,
    "pid": 1234,
    "disk_usage": 5368709120
  }
]
```
```

--------------------------------

### Trigger Shake Gesture on VM using PyMemuc

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Simulates a device shake gesture on a VM. Specify the VM by index or name.

```python
from pymemuc import PyMemuc

memuc = PyMemuc()

# Trigger shake gesture
memuc.trigger_shake_vm(vm_index=0)
print("Shake triggered")

# Trigger by VM name
memuc.trigger_shake_vm(vm_name="MyVM")
```

--------------------------------

### clone_vm - Clone a Virtual Machine

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Creates a copy of an existing VM with an optional new name.

```APIDOC
## POST /clone_vm

### Description
Creates a copy of an existing VM with an optional new name.

### Method
`clone_vm()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Parameters
- **vm_index** (int) - Optional - The index of the VM to clone.
- **vm_name** (str) - Optional - The name of the VM to clone.
- **new_name** (str) - Optional - The name for the cloned VM.
- **non_blocking** (bool) - Optional - Clone the VM in non-blocking mode (returns immediately).

### Request Example
```python
from pymemuc import PyMemuc

memuc = PyMemuc()

# Clone VM by index with a new name
memuc.clone_vm(vm_index=0, new_name="ClonedVM")
print("VM cloned successfully")

# Clone VM by name
memuc.clone_vm(vm_name="OriginalVM", new_name="ClonedVM")

# Clone in non-blocking mode for large VMs
memuc.clone_vm(vm_index=0, new_name="ClonedVM", non_blocking=True)
```

### Response
#### Success Response (200)
- **message** (str) - Confirmation message.

#### Response Example
```json
{
  "message": "VM cloned successfully"
}
```
```

--------------------------------

### Arrange VM Windows

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

This function automatically arranges all open virtual machine windows into an organized layout on your screen.

```python
from pymemuc import PyMemuc

memuc = PyMemuc()

# Sort all VM windows
memuc.sort_out_all_vm()
print("All VM windows arranged")
```

--------------------------------

### List VM Information

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Retrieve information about MEmu virtual machines. Options include listing all VMs with disk usage, only running VMs, or details for a specific VM by index or name.

```python
from pymemuc import PyMemuc

memuc = PyMemuc()

# List all VMs with disk info
vms = memuc.list_vm_info(disk_info=True)
for vm in vms:
    print(f"Index: {vm['index']}, Name: {vm['title']}, Running: {vm['running']}, "
          f"PID: {vm['pid']}, Disk: {vm['disk_usage']} bytes")
# Output: Index: 0, Name: MEmu, Running: True, PID: 1234, Disk: 5368709120 bytes
```

```python
# List only running VMs
running_vms = memuc.list_vm_info(running=True)
```

```python
# Get info for a specific VM by index
specific_vm = memuc.list_vm_info(vm_index=0)
```

```python
# Get info for a specific VM by name
named_vm = memuc.list_vm_info(vm_name="MyVM")
```

--------------------------------

### Arrange VM Windows API

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

API to arrange all open VM windows in an organized layout on the screen.

```APIDOC
## POST /vm/arrange

### Description
Arranges all open VM windows in an organized layout on the screen.

### Method
POST

### Endpoint
/vm/arrange

### Parameters
No parameters required.

### Request Example
```json
{}
```
```

--------------------------------

### Clone VM

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Create a copy of an existing MEmu virtual machine. Allows specifying a new name for the cloned VM and supports non-blocking cloning.

```python
from pymemuc import PyMemuc

memuc = PyMemuc()

# Clone VM by index with a new name
memuc.clone_vm(vm_index=0, new_name="ClonedVM")
print("VM cloned successfully")
```

```python
# Clone VM by name
memuc.clone_vm(vm_name="OriginalVM", new_name="ClonedVM")
```

```python
# Clone in non-blocking mode for large VMs
memuc.clone_vm(vm_index=0, new_name="ClonedVM", non_blocking=True)
```

--------------------------------

### PyMemuc Class Initialization

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Initialize the PyMemuc class to interact with MEmu emulators. It can auto-detect the memuc.exe path on Windows, accept a custom path, or enable debug logging.

```APIDOC
## PyMemuc Class Initialization

### Description
The main entry point for interacting with MEmu emulators. Automatically detects memuc.exe on Windows or accepts a manual path.

### Method
`PyMemuc()`

### Parameters
#### Optional Parameters
- **debug** (bool) - Optional - Enable debug logging.
- **memuc_path** (str) - Optional - Specify custom path to memuc.exe.

### Request Example
```python
from pymemuc import PyMemuc

# Auto-detect memuc.exe path (Windows only)
memuc = PyMemuc()

# Enable debug logging
memuc = PyMemuc(debug=True)

# Specify custom path to memuc.exe
memuc = PyMemuc(memuc_path="C:/Program Files/Microvirt/MEmu/memuc.exe")
```
```

--------------------------------

### Initialize PyMemuc

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Initialize the PyMemuc class to interact with MEmu emulators. It can auto-detect the path, use a custom path, or enable debug logging.

```python
from pymemuc import PyMemuc

# Auto-detect memuc.exe path (Windows only)
memuc = PyMemuc()
```

```python
# Enable debug logging
memuc = PyMemuc(debug=True)
```

```python
# Specify custom path to memuc.exe
memuc = PyMemuc(memuc_path="C:/Program Files/Microvirt/MEmu/memuc.exe")
```

--------------------------------

### ADB and Shell Commands

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Functions for sending ADB commands and executing shell commands directly on a VM.

```APIDOC
## send_adb_command_vm - Send ADB Command

Sends an ADB (Android Debug Bridge) command to a VM and returns the output.

### Method
POST

### Endpoint
/api/v1/vm/adb_command

### Parameters
#### Query Parameters
- **command** (string or array) - Required - The ADB command to send. Can be a string or an array of strings.
- **vm_index** (integer) - Optional - The index of the VM to target.
- **vm_name** (string) - Optional - The name of the VM to target.
- **timeout** (integer) - Optional - The timeout in seconds for the operation.

### Request Example
```json
{
  "command": "shell ls /sdcard",
  "vm_index": 0,
  "timeout": 10
}
```

### Response
#### Success Response (200)
- **output** (string) - The output from the ADB command.

#### Response Example
```json
{
  "output": "file1.txt\nfile2.txt"
}
```

## get_adb_connection - Get ADB Connection Info

Retrieves the ADB connection IP address and port for a VM.

### Method
GET

### Endpoint
/api/v1/vm/adb_connection

### Parameters
#### Query Parameters
- **vm_index** (integer) - Optional - The index of the VM to target.
- **vm_name** (string) - Optional - The name of the VM to target.
- **timeout** (integer) - Optional - The timeout in seconds for the operation.

### Response
#### Success Response (200)
- **ip** (string) - The IP address for ADB connection.
- **port** (integer) - The port for ADB connection.

#### Response Example
```json
{
  "ip": "127.0.0.1",
  "port": 21503
}
```

## execute_command_vm - Execute Shell Command on VM

Executes a shell command directly on a VM.

### Method
POST

### Endpoint
/api/v1/vm/execute_command

### Parameters
#### Query Parameters
- **command** (string) - Required - The shell command to execute.
- **vm_index** (integer) - Optional - The index of the VM to target.
- **vm_name** (string) - Optional - The name of the VM to target.

### Request Example
```json
{
  "command": "ls -la /sdcard",
  "vm_index": 0
}
```

### Response
#### Success Response (200)
- **status** (integer) - The exit status of the command.
- **output** (string) - The output of the command.

#### Response Example
```json
{
  "status": 0,
  "output": "-rw-rw-rw- 1 root sdcard_rw 1024 Jan 1 12:00 file.txt"
}
```
```

--------------------------------

### Execute Shell Command on VM using PyMemuc

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Executes a shell command directly on a VM and returns the status and output. Can specify the VM by index or name.

```python
from pymemuc import PyMemuc

memuc = PyMemuc()

# Execute command on VM
status, output = memuc.execute_command_vm("ls -la /sdcard", vm_index=0)
print(f"Status: {status}, Output:\n{output}")

# Execute by VM name
status, output = memuc.execute_command_vm("cat /proc/cpuinfo", vm_name="MyVM")
```

--------------------------------

### Input Text on VM using PyMemuc

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Types text into the currently focused input field on a VM. Specify the VM by index or name.

```python
from pymemuc import PyMemuc

memuc = PyMemuc()

# Input text into focused field
memuc.input_text_vm("Hello, World!", vm_index=0)
print("Text entered")

# Input by VM name
memuc.input_text_vm("username@example.com", vm_name="MyVM")
```

--------------------------------

### Import VM from OVA

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Imports a virtual machine from an OVA file. Supports non-blocking mode for large import files.

```python
memuc.import_vm(file_name="backup.ova")
```

```python
memuc.import_vm(file_name="large_backup.ova", non_blocking=True)
```

--------------------------------

### stop_all_vm - Stop All Virtual Machines

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Stops all running MEmu virtual machines at once.

```APIDOC
## POST /stop_all_vm

### Description
Stops all running MEmu virtual machines at once.

### Method
`stop_all_vm()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Parameters
- **timeout** (int) - Optional - Timeout in seconds for the operation.
- **non_blocking** (bool) - Optional - Stop all VMs in non-blocking mode (returns immediately).

### Request Example
```python
from pymemuc import PyMemuc

memuc = PyMemuc()

# Stop all running VMs with timeout
memuc.stop_all_vm(timeout=120)
print("All VMs stopped successfully")

# Stop all VMs in non-blocking mode
memuc.stop_all_vm(non_blocking=True)
```

### Response
#### Success Response (200)
- **message** (str) - Confirmation message.

#### Response Example
```json
{
  "message": "All VMs stopped successfully"
}
```
```

--------------------------------

### VM Display and Location Settings

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Functions to control the VM window rotation, zoom level, and GPS location.

```APIDOC
## change_gps_vm - Change GPS Location

Sets the GPS coordinates for a VM to simulate a specific geographic location.

### Method
POST

### Endpoint
/api/v1/vm/gps

### Parameters
#### Query Parameters
- **latitude** (number) - Required - The latitude coordinate.
- **longitude** (number) - Required - The longitude coordinate.
- **vm_index** (integer) - Optional - The index of the VM to target.
- **vm_name** (string) - Optional - The name of the VM to target.

### Request Example
```json
{
  "latitude": 40.7128,
  "longitude": -74.0060,
  "vm_index": 0
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure of the operation.

#### Response Example
```json
{
  "status": "success"
}
```

## rotate_window_vm - Rotate VM Window

Rotates the VM window orientation between portrait and landscape modes.

### Method
POST

### Endpoint
/api/v1/vm/rotate

### Parameters
#### Query Parameters
- **vm_index** (integer) - Optional - The index of the VM to target.
- **vm_name** (string) - Optional - The name of the VM to target.

### Request Example
```json
{
  "vm_index": 0
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure of the operation.

#### Response Example
```json
{
  "status": "success"
}
```

## zoom_in_vm - Zoom In

Zooms in the VM display.

### Method
POST

### Endpoint
/api/v1/vm/zoom_in

### Parameters
#### Query Parameters
- **vm_index** (integer) - Optional - The index of the VM to target.
- **vm_name** (string) - Optional - The name of the VM to target.

### Request Example
```json
{
  "vm_index": 0
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure of the operation.

#### Response Example
```json
{
  "status": "success"
}
```

## zoom_out_vm - Zoom Out

Zooms out the VM display.

### Method
POST

### Endpoint
/api/v1/vm/zoom_out

### Parameters
#### Query Parameters
- **vm_index** (integer) - Optional - The index of the VM to target.
- **vm_name** (string) - Optional - The name of the VM to target.

### Request Example
```json
{
  "vm_index": 0
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success or failure of the operation.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### PyMemuc Exception Handling

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Demonstrates how to catch specific exceptions raised by PyMemuc for various error conditions, such as index errors, timeouts, and general failures.

```python
from pymemuc import (
    PyMemuc,
    PyMemucError,
    PyMemucException,
    PyMemucIndexError,
    PyMemucTimeoutExpired,
)

memuc = PyMemuc()

try:
    # This will raise PyMemucIndexError if neither index nor name specified
    memuc.start_vm()
except PyMemucIndexError as e:
    print(f"Index error: {e}")

try:
    # This may raise PyMemucTimeoutExpired if VM doesn't start in time
    memuc.start_vm(vm_index=0, timeout=5)
except PyMemucTimeoutExpired as e:
    print(f"Timeout: {e}")

try:
    # This may raise PyMemucError for general failures
    memuc.delete_vm(vm_index=999)
except PyMemucError as e:
    print(f"Error: {e}")
```

--------------------------------

### Execute Raw MEMUC Commands

Source: https://context7.com/pyclashbot/pymemuc/llms.txt

Provides direct access to all MEMUC functionalities by executing raw commands. Supports standard execution, timeouts, and non-blocking operations.

```python
from pymemuc import PyMemuc

memuc = PyMemuc()

# Run raw MEMUC command
status, output = memuc.memuc_run(["-i", "0", "setconfigex", "cpus", "4"])
print(f"Status: {status}, Output: {output}")

# Run with timeout
status, output = memuc.memuc_run(["-i", "0", "start"], timeout=120)

# Run in non-blocking mode (returns task ID)
status, output = memuc.memuc_run(["-i", "0", "start"], non_blocking=True)
print(f"Task started: {output}")
```