### Execute Simple Task

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/agent-commands.md

This JavaScript example demonstrates how to start a simple task without any custom agents. Ensure the instance is created, the controller is connected, and the resource is loaded before invoking this command.

```javascript
// Simple task execution without agents
const taskIds = await invoke('maa_start_tasks', {
  instanceId: 'device-1',
  tasks: [
    {
      entry: 'StartTask',
      pipelineOverride: '',
      selectedTaskId: 'task-1'
    }
  ],
  agentConfigs: null,
  cwd: '/home/user/automation',
  tcpCompatMode: false
});
```

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

### MXU API - Getting Started Workflow

Source: https://github.com/misteo/mxu/blob/main/_autodocs/README.md

This snippet demonstrates the basic workflow for interacting with the MXU API using Tauri commands. It covers initialization, instance creation, device discovery, controller connection, resource loading, task execution, and progress monitoring.

```APIDOC
## MXU API - Getting Started Workflow

### Description
This snippet demonstrates the basic workflow for interacting with the MXU API using Tauri commands. It covers initialization, instance creation, device discovery, controller connection, resource loading, task execution, and progress monitoring.

### Method
POST (Tauri `invoke`)

### Endpoint
N/A (Tauri IPC)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
(Implicitly handled by Tauri `invoke` arguments)

### Request Example
```javascript
// 1. Initialize MaaFramework
await invoke('maa_init');
await invoke('maa_set_resource_dir', { resourceDir: '/path/to/resources' });

// 2. Create Instance
await invoke('maa_create_instance', { instanceId: 'device-1' });

// 3. Find Devices
const devices = await invoke('maa_find_adb_devices');

// 4. Connect Controller
await invoke('maa_connect_controller', {
  instanceId: 'device-1',
  controllerConfig: {
    type: 'Adb',
    adbPath: '/path/to/adb',
    address: devices[0].address,
    // ... other fields
  }
});

// 5. Load Resource
await invoke('maa_load_resource', { instanceId: 'device-1' });

// 6. Run Tasks
const taskIds = await invoke('maa_start_tasks', {
  instanceId: 'device-1',
  tasks: [{ entry: 'StartTask', pipelineOverride: '', selectedTaskId: 'task-1' }],
  agentConfigs: null,
  cwd: '/home/user',
  tcpCompatMode: false
});

// 7. Monitor Progress
const state = await invoke('maa_get_instance_state', { instanceId: 'device-1' });
console.log(state.task_run_state.statuses); // Per-task status
```

### Response
#### Success Response
(Varies by command; typically returns status or data related to the operation)

#### Response Example
```json
// Example for maa_find_adb_devices:
[
  {
    "address": "192.168.1.100:5555",
    "state": "device",
    "serial": "emulator-5554"
  }
]

// Example for maa_get_instance_state:
{
  "instance_id": "device-1",
  "task_run_state": {
    "statuses": [
      {
        "task_id": "task-1",
        "status": "running",
        "progress": 0.5
      }
    ]
  }
}
```

## Event Listening

### Description
MXU utilizes Tauri events for real-time updates and callbacks from the backend. This section details how to listen for these events.

### Method
`listen` from `@tauri-apps/api/event`

### Endpoint
N/A (Tauri Events)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { listen } from '@tauri-apps/api/event';

// Task execution callbacks
await listen('maa-callback-event', (event) => {
  const { message, details } = event.payload;
  console.log(`Task callback: ${message}`);
});

// Agent output
await listen('maa-agent-output', (event) => {
  const { instance_id, stream, line } = event.payload;
  console.log(`[${stream}] ${line}`);
});

// State changes
await listen('state-changed', (event) => {
  const { instance_id, kind } = event.payload;
  console.log(`${instance_id} state changed: ${kind}`);
});
```

### Response
N/A (Event listeners do not return a direct response; they receive event payloads.)
```

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

### Execute Task with Custom Agent

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/agent-commands.md

This JavaScript example shows how to start a task and launch a custom agent process. The agent is specified with its executable path, arguments, an identifier, and a connection timeout. Environment variables like PI_LOG_LEVEL can be passed to the agent.

```javascript
// With custom agent
const taskIds = await invoke('maa_start_tasks', {
  instanceId: 'device-1',
  tasks: [
    {
      entry: 'RecognitionTask',
      pipelineOverride: '',
      selectedTaskId: 'task-1'
    }
  ],
  agentConfigs: [
    {
      childExec: '/path/to/agent.py',
      childArgs: ['--config', 'settings.json'],
      identifier: 'custom-agent',
      timeout: 30000
    }
  ],
  cwd: '/home/user/automation',
  tcpCompatMode: false,
  piEnvs: {
    'PI_LOG_LEVEL': 'debug'
  }
});
```

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

### Start Tasks

Source: https://github.com/misteo/mxu/blob/main/_autodocs/QUICK-REFERENCE.md

Starts one or more tasks for a Misteo MXU instance. Allows for task configuration and agent settings.

```javascript
const taskIds = await invoke('maa_start_tasks', {
  instanceId,
  tasks: [{ entry: 'TaskName', pipelineOverride: '' }],
  agentConfigs: null,
  cwd: '.',
  tcpCompatMode: false
});
```

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

### Starting Tasks and Tracking Status

Source: https://github.com/misteo/mxu/blob/main/_autodocs/README.md

Shows how to start multiple tasks using `invoke('maa_start_tasks', ...)` and assign unique `selectedTaskId` for frontend tracking. It also demonstrates querying the state of a specific task instance later.

```javascript
const taskIds = await invoke('maa_start_tasks', {
  // ...
  tasks: [
    { entry: 'Task1', pipelineOverride: '', selectedTaskId: 'frontend-id-1' },
    { entry: 'Task2', pipelineOverride: '', selectedTaskId: 'frontend-id-2' }
  ]
});

// Later, query per-task status
const state = await invoke('maa_get_instance_state', { instanceId });
const status = state.task_run_state.statuses['frontend-id-1']; // "pending", "running", "succeeded", "failed"
```

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

### Initialize and Configure MaaFramework

Source: https://github.com/misteo/mxu/blob/main/_autodocs/README.md

Initializes the MaaFramework library and sets the resource directory. Ensure the resource directory path is correct for your setup.

```javascript
await invoke('maa_init'); // Load library
await invoke('maa_set_resource_dir', { resourceDir: '/path/to/resources' });
```

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

### Enable Application Autostart

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Enables application autostart on system boot. This command handles platform-specific setup for Windows, macOS, and Linux.

```rust
#[tauri::command]
pub fn autostart_enable() -> Result<(), String>
```

```javascript
await invoke('autostart_enable');
console.log('Autostart enabled');
```

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

### Load Resource for Instance

Source: https://github.com/misteo/mxu/blob/main/_autodocs/README.md

Loads the necessary resources for a given instance. This step is required before starting tasks.

```javascript
await invoke('maa_load_resource', { instanceId: 'device-1' });
```

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

### Start Tasks

Source: https://github.com/misteo/mxu/blob/main/_autodocs/README.md

Initiates task execution within an instance. Specify tasks, agent configurations, and working directory. TCP compatibility mode can also be set.

```javascript
const taskIds = await invoke('maa_start_tasks', {
  instanceId: 'device-1',
  tasks: [{ entry: 'StartTask', pipelineOverride: '', selectedTaskId: 'task-1' }],
  agentConfigs: null,
  cwd: '/home/user',
  tcpCompatMode: false
});
```

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

### Start Tasks with Optional Agents

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/agent-commands.md

Execute one or more tasks, optionally launching custom agent processes beforehand. Agents can be configured with executables, arguments, identifiers, and timeouts. Environment variables starting with PI_ are injected into agent processes. Agents are launched in the specified working directory, with their stdout/stderr captured and emitted as events.

```rust
#[tauri::command]
pub async fn maa_start_tasks(
    app: tauri::AppHandle,
    state: State<'_, Arc<MaaState>>,
    instance_id: String,
    tasks: Vec<TaskConfig>,
    agent_configs: Option<Vec<AgentConfig>>,
    cwd: String,
    tcp_compat_mode: bool,
    pi_envs: Option<HashMap<String, String>>,
) -> Result<Vec<i64>, String>
```

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

### Example settings.json Structure

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/tray-and-config.md

Illustrates the structure of the user-specific settings.json file, including general application settings, instance states, task history, and scheduled task configurations.

```json
{
  "settings": {
    "theme": "dark",
    "language": "en",
    "allowLanAccess": true,
    "webServerPort": 9999,
    "minimizeToTray": true
  },
  "instances": {
    "device-1": {
      "lastController": { "type": "Adb", "address": "127.0.0.1:5555" }
    }
  }
}
```

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

### autostart_enable

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Enables application autostart on system boot. This command creates platform-specific configurations to ensure the application starts automatically when the system boots up.

```APIDOC
## autostart_enable

### Description
Enable application autostart on system boot.

### Method
invoke

### Parameters
None

### Returns
`Result<(), String>` — Unit on success

### Platform-specific:
- **Windows** — Creates scheduled task in Task Scheduler
- **macOS** — Creates LaunchAgent plist
- **Linux** — Creates systemd user service

### Request Example
```javascript
await invoke('autostart_enable');
console.log('Autostart enabled');
```
```

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

### Run Executable and Wait for Completion (JavaScript)

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Invoke the `run_and_wait` command to execute an external program and get its exit code. This is helpful for automating tasks or running setup scripts.

```javascript
const exitCode = await invoke('run_and_wait', { 
  filePath: '/usr/local/bin/setup.sh' 
});
console.log(`Script exited with code: ${exitCode}`);
```

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

### is_autostart

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Determines if the application was started via the autostart mechanism. This is useful for detecting if the application was launched automatically by the system.

```APIDOC
## is_autostart

### Description
Check if the application was started via autostart mechanism.

### Method
invoke

### Parameters
None

### Returns
`bool` — true if started via `--autostart` flag

### Request Example
```javascript
if (await invoke('is_autostart')) {
  console.log('Started automatically, running headless');
}
```
```

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

### Initialize MaaFramework

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/maa-core-commands.md

Initializes MaaFramework by loading the native library. Can auto-load from a default location or a custom path. Use this command to start MaaFramework.

```rust
#[tauri::command]
pub fn maa_init(state: State<Arc<MaaState>>, lib_dir: Option<String>) -> Result<String, String>
```

```javascript
// Auto-load from default location
const version = await invoke('maa_init');

// Load from custom path
const version = await invoke('maa_init', { 
  libDir: '/custom/path/to/maafw' 
 });
```

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

### Restore UI State on App Startup with JavaScript

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/state-and-queries.md

Example of invoking `maa_get_all_states` on application startup in JavaScript. It shows how to iterate through instances to check their running status and populate device selectors with cached results.

```javascript
// On app startup
const allStates = await invoke('maa_get_all_states');

// Restore instance tabs
Object.entries(allStates.instances).forEach(([id, state]) => {
  if (state.is_running) {
    console.log(`Instance ${id} was running, is still running: ${state.is_running}`);
  }
});

// Populate device selector with cached results
console.log(`Cached ADB devices: ${allStates.cached_adb_devices.length}`);
console.log(`Cached Win32 windows: ${allStates.cached_win32_windows.length}`);
```

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

### Get Version

Source: https://github.com/misteo/mxu/blob/main/_autodocs/QUICK-REFERENCE.md

Retrieves the Misteo MXU version information.

```javascript
const version = await invoke('maa_get_version');
```

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

### WebView2DirInfo Structure

Source: https://github.com/misteo/mxu/blob/main/_autodocs/types.md

Provides information about a WebView2 runtime directory on Windows. Includes the installation path and whether it's system-installed.

```rust
pub struct WebView2DirInfo {
    pub path: String,
    pub system: bool,
}
```

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

### Get Autostart Instance Name

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Retrieves the instance name configured for autostart, either from command-line arguments or settings. Returns an Option<String>.

```rust
#[tauri::command]
pub fn get_start_instance() -> Option<String>
```

```javascript
const instance = await invoke('get_start_instance');
if (instance) {
  console.log(`Will autostart instance: ${instance}`);
  // Automatically select and run this instance
}
```

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

### Example of Stopping Agents

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/agent-commands.md

This JavaScript example invokes the `maa_stop_agent` command to stop all agents for a given instance. The command returns immediately, and the stopping process occurs asynchronously in the background.

```javascript
await invoke('maa_stop_agent', { instanceId: 'device-1' });
console.log('Agents stopping (background)');
```

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

### autostart_is_enabled

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Checks if autostart is currently enabled for the application. Returns a boolean indicating whether the application is configured to start automatically on system boot.

```APIDOC
## autostart_is_enabled

### Description
Check if autostart is currently enabled.

### Method
invoke

### Parameters
None

### Returns
`Result<bool, String>` — true if autostart enabled

### Request Example
```javascript
const enabled = await invoke('autostart_is_enabled');
console.log(`Autostart: ${enabled ? 'enabled' : 'disabled'}`);
```
```

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

### User Configuration Example

Source: https://github.com/misteo/mxu/blob/main/_autodocs/README.md

This JSON object shows the structure of the user configuration file, located at {data_dir}/config/settings.json. It includes settings for theme, language, network access, web server port, and tray minimization.

```json
{
  "settings": {
    "theme": "dark",
    "language": "en",
    "allowLanAccess": false,
    "webServerPort": 9999,
    "minimizeToTray": true
  }
}
```

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

### Get All Instance States

Source: https://github.com/misteo/mxu/blob/main/_autodocs/QUICK-REFERENCE.md

Retrieves the current states of all Misteo MXU instances.

```javascript
const allStates = await invoke('maa_get_all_states');
```

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

### Check if Started via Autostart

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Determines if the application was launched using the autostart mechanism. Useful for detecting headless or automated startup.

```rust
#[tauri::command]
pub fn is_autostart() -> bool
```

```javascript
if (await invoke('is_autostart')) {
  console.log('Started automatically, running headless');
}
```

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

### Get Executable Directory

Source: https://github.com/misteo/mxu/blob/main/_autodocs/QUICK-REFERENCE.md

Retrieves the directory where the Misteo MXU executable is located.

```javascript
const exeDir = await invoke('get_exe_dir');
```

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

### autostart_disable

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Disables application autostart. This command removes any existing configurations that cause the application to start automatically on system boot.

```APIDOC
## autostart_disable

### Description
Disable application autostart.

### Method
invoke

### Parameters
None

### Returns
`Result<(), String>` — Unit on success

### Request Example
```javascript
await invoke('autostart_disable');
console.log('Autostart disabled');
```
```

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

### Get System Info

Source: https://github.com/misteo/mxu/blob/main/_autodocs/QUICK-REFERENCE.md

Retrieves system information relevant to Misteo MXU operations.

```javascript
const info = await invoke('get_system_info');
```

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

### Query Instance State in JavaScript

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/state-and-queries.md

Example of how to invoke the `maa_get_instance_state` command from JavaScript and log the results. It demonstrates accessing connection status, running state, and overall task status.

```javascript
const state = await invoke('maa_get_instance_state', { 
  instanceId: 'device-1' 
});

console.log(`Connected: ${state.connected}`);
console.log(`Running: ${state.is_running}`);
console.log(`Overall status: ${state.task_run_state.overall_status}`);

// Check specific task status
if (state.task_run_state.statuses.task1 === 'running') {
  console.log('Task 1 is running');
}
```

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

### Get WebView2 Runtime Directory (Windows)

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Retrieves information about the WebView2 runtime directory on Windows. Returns the path and whether it's system-installed or bundled.

```rust
#[tauri::command]
pub fn get_webview2_dir() -> Result<Option<WebView2DirInfo>, String>
```

```javascript
const dir = await invoke('get_webview2_dir');
if (dir) {
  console.log(`WebView2 at: ${dir.path} (system: ${dir.system})`);
}
```

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

### Get System Information (JavaScript)

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Call the `get_system_info` command in JavaScript to fetch details about the operating system, architecture, and Tauri version. This information can be used for logging or conditional logic.

```javascript
const info = await invoke('get_system_info');
console.log(`Running on ${info.os} ${info.os_version} (${info.arch})`);
console.log(`Tauri version: ${info.tauri_version}`);
```

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

### Get System Information (Rust)

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

This Rust command retrieves comprehensive system and application version information, including OS name, version, architecture, and Tauri version. It returns a `SystemInfo` struct.

```rust
#[tauri::command]
pub fn get_system_info() -> SystemInfo
```

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

### Download and Update Commands

Source: https://github.com/misteo/mxu/blob/main/_autodocs/MANIFEST.txt

Documentation for commands related to the download and update process, including GitHub API interaction, file downloads, and update installation with rollback support.

```APIDOC
## Download and Update Commands

This section details the commands for managing the download and update workflow. It includes interactions with the GitHub API, handling downloads, and installing updates with rollback capabilities.

### Commands
- `github_api`: Interacts with the GitHub API for release information.
- `download`: Downloads files from specified URLs.
- `install_update`: Installs downloaded updates.

### Features
- Complete update workflow.
- Rollback support for updates.

### Parameters and Return Types
Refer to `api-reference/download-and-update.md` for detailed command signatures, parameter descriptions, and return types.
```

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

### Get All Instance States

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/state-and-queries.md

Retrieves state snapshots for all instances and cached device lists. This is useful for frontend startup to restore UI state and device lists without rescanning.

```rust
#[tauri::command]
pub fn maa_get_all_states(
    state: State<Arc<MaaState>>,
) -> Result<AllInstanceStates, String>
```

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

### Open File with System Default Application (Rust)

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

This asynchronous Rust command opens a specified file using the system's default application. It handles platform-specific commands like `start`, `open`, and `xdg-open`.

```rust
#[tauri::command]
pub async fn open_file(file_path: String) -> Result<(), String>
```

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

### Log Cached Win32 Windows in JavaScript

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/state-and-queries.md

Example of invoking `maa_get_cached_win32_windows` in JavaScript and logging the handle and name of each window. This shows how to retrieve and display cached Win32 window information.

```javascript
const windows = await invoke('maa_get_cached_win32_windows');
windows.forEach(w => console.log(`${w.handle}: ${w.window_name}`));
```

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

### Get Application Directory Paths

Source: https://github.com/misteo/mxu/blob/main/_autodocs/QUICK-REFERENCE.md

Retrieve the executable directory, data directory, and current working directory using helper invoke functions. These paths are essential for accessing configuration and log files.

```javascript
const exeDir = await invoke('get_exe_dir');
const dataDir = await invoke('get_data_dir');
const cwd = await invoke('get_cwd');
```

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

### Get CPU Architecture (JavaScript)

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Use the `get_arch` command in JavaScript to retrieve the system's CPU architecture. This can be helpful for compatibility checks or performance optimizations.

```javascript
const arch = await invoke('get_arch');
console.log(`Architecture: ${arch}`);
```

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

### Get GitHub Release by Version

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/download-and-update.md

Fetches GitHub Release information for a specific version tag. Useful for checking available releases and their assets before downloading.

```rust
#[tauri::command]
pub async fn get_github_release_by_version(
    owner: String,
    repo: String,
    target_version: String,
    github_pat: Option<String>,
    proxy_url: Option<String>,
) -> Result<Option<GitHubRelease>, String>
```

```javascript
const release = await invoke('get_github_release_by_version', {
  owner: 'MistEO',
  repo: 'MXU',
  targetVersion: '0.5.0',
  githubPat: null,
  proxyUrl: 'http://proxy.company.com:8080'
});

if (release) {
  console.log(`Found release: ${release.tag_name}`);
  release.assets.forEach(asset => {
    console.log(`  ${asset.name} (${asset.size} bytes)`);
  });
}
```

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

### retry_load_maa_library

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Allows retrying the loading of the MaaFramework library, typically after a user has installed necessary dependencies like VC++ redistributables or copied the maafw/ directory.

```APIDOC
## retry_load_maa_library

### Description
Retry loading MaaFramework library after user installs dependencies.

### Method
invoke

### Parameters
None

### Returns
`Result<String, String>` — Version string on success

### Use after:
User installs VC++ redistributables or copies maafw/

### Request Example
```javascript
const version = await invoke('retry_load_maa_library');
console.log(`MaaFramework loaded: ${version}`);
```
```

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

### Check MXU Version Compatibility

Source: https://github.com/misteo/mxu/blob/main/_autodocs/QUICK-REFERENCE.md

Invoke the `maa_check_version` command to get compatibility information. Log an error if the current version is not compatible with the minimum required version.

```javascript
const check = await invoke('maa_check_version');
if (!check.is_compatible) {
  console.error(`Incompatible version: ${check.current} < ${check.minimum}`);
}
```

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

### Log Cached ADB Devices in JavaScript

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/state-and-queries.md

Example of invoking `maa_get_cached_adb_devices` in JavaScript and logging the addresses of the found devices. This demonstrates how to access the cached ADB device list.

```javascript
const devices = await invoke('maa_get_cached_adb_devices');
devices.forEach(d => console.log(d.address));
```

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

### Tray and Configuration Commands

Source: https://github.com/misteo/mxu/blob/main/_autodocs/MANIFEST.txt

This section covers commands for managing the tray icon, web server, environment variables, and configuration files, along with notification capabilities.

```APIDOC
## Tray and Configuration Commands

This section documents commands related to the system tray icon, web server, environment variables, and configuration files. It also includes details on notification functionality.

### Commands
- `tray_icon`: Manages the system tray icon.
- `web_server`: Controls the integrated web server.
- `environment_variables`: Manages environment variables.
- `config_files`: Handles configuration files.
- `notification`: Sends system notifications.

### Configuration Details
Includes details on configuration files and environment variables.

### Parameters and Return Types
Refer to `api-reference/tray-and-config.md` for detailed command signatures, parameter descriptions, and return types.
```

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

### Get Data Directory

Source: https://github.com/misteo/mxu/blob/main/_autodocs/QUICK-REFERENCE.md

Retrieves the data directory used by Misteo MXU.

```javascript
const dataDir = await invoke('get_data_dir');
```

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

### get_start_instance

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Retrieves the instance name that the application is set to autostart with. This name can be specified via command-line arguments or application settings.

```APIDOC
## get_start_instance

### Description
Get the instance name to autostart (from command-line args or settings).

### Method
invoke

### Parameters
None

### Returns
`Option<String>` — Instance name or None

### Used with:
--instance / -i command-line flag

### Request Example
```javascript
const instance = await invoke('get_start_instance');
if (instance) {
  console.log(`Will autostart instance: ${instance}`);
  // Automatically select and run this instance
}
```
```

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

### Get Cached Image

Source: https://github.com/misteo/mxu/blob/main/_autodocs/QUICK-REFERENCE.md

Retrieves the most recently cached image from a Misteo MXU instance.

```javascript
const img = await invoke('maa_get_cached_image', { instanceId });
```

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

### Get Instance State

Source: https://github.com/misteo/mxu/blob/main/_autodocs/QUICK-REFERENCE.md

Retrieves the current state of a specific Misteo MXU instance.

```javascript
const state = await invoke('maa_get_instance_state', { instanceId });

console.log(state.is_running);
console.log(state.task_run_state.overall_status);
console.log(state.task_run_state.statuses['task-id']);
```

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

### State and Queries Commands

Source: https://github.com/misteo/mxu/blob/main/_autodocs/MANIFEST.txt

This section covers commands for querying the runtime state of instances, accessing device caches, and retrieving logs.

```APIDOC
## State and Queries Commands

This section provides documentation for commands used to query the runtime state of instances, access cached device lists, and retrieve logs.

### Commands
- `instance_state`: Retrieves the current state of an instance.
- `device_caches`: Accesses cached device information.
- `logging`: Retrieves logs.

### Query Patterns
Supports query patterns for runtime state and cached device lists.

### Parameters and Return Types
Refer to `api-reference/state-and-queries.md` for detailed command signatures, parameter descriptions, and return types.
```

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

### Get Web Server Port

Source: https://github.com/misteo/mxu/blob/main/_autodocs/QUICK-REFERENCE.md

Retrieves the port number for the Misteo MXU web server.

```javascript
const port = await invoke('get_web_server_port');
```

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

### MaaFramework Core Commands

Source: https://github.com/misteo/mxu/blob/main/_autodocs/MANIFEST.txt

This section details the core commands for MaaFramework, including initialization, version checking, device and instance management, controller operations, resource handling, task execution, input simulation, and screenshot capture.

```APIDOC
## MaaFramework Core Commands

This section details the core commands for MaaFramework, including initialization, version checking, device and instance management, controller operations, resource handling, task execution, input simulation, and screenshot capture.

### Commands
- `init`: Initializes the MaaFramework.
- `version`: Retrieves the current version of MaaFramework.
- `devices`: Lists available devices.
- `instances`: Manages independent device contexts (instances).
- `controllers`: Manages controller connections (ADB, Win32, etc.).
- `resources`: Handles resource loading and management.
- `tasks`: Manages task execution pipelines.
- `input`: Simulates user input.
- `screenshots`: Captures screenshots.

### Parameters and Return Types
Refer to `api-reference/maa-core-commands.md` for detailed signatures, parameter descriptions (types, defaults), and return types (Result<T, String>).
```

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

### maa_init

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/maa-core-commands.md

Initializes MaaFramework by loading the native library. It can optionally load from a specified directory or auto-load from the default location.

```APIDOC
## maa_init

### Description
Initialize MaaFramework by loading the native library.

### Method
`POST` (Assumed based on tauri::command and potential state modification)

### Endpoint
`/maa_init`

### Parameters
#### Query Parameters
- **lib_dir** (Option<String>) - Optional - Path to MaaFramework library directory. If not provided, auto-loads from `maafw/` in exe directory. Can be a directory or path to specific DLL/dylib/so file.

### Request Example
```javascript
// Auto-load from default location
const version = await invoke('maa_init');

// Load from custom path
const version = await invoke('maa_init', { 
  libDir: '/custom/path/to/maafw' 
});
```

### Response
#### Success Response (200)
- **version** (String) - MaaFramework version string on success

#### Response Example
```json
"5.5.0"
```

### Error conditions:
- Library directory does not exist
- DLL loading fails
```

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

### cleanup_update_artifacts

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/download-and-update.md

Deletes temporary update files, including extracted directories and download files, after a successful installation.

```APIDOC
## cleanup_update_artifacts

### Description
Delete temporary update files after successful installation.

### Method
TAURI COMMAND

### Endpoint
cleanup_update_artifacts

### Parameters: None

### Returns
#### Success Response
- **Unit** - Unit on success

**Clears:**
- Extracted update directories
- Temporary download files
- Previous cache/old backups

### Request Example
```javascript
await invoke('cleanup_update_artifacts');
console.log('Temporary files cleaned up');
```
```

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

### Create a New Instance

Source: https://github.com/misteo/mxu/blob/main/_autodocs/README.md

Creates a new instance for controlling a specific device. Each instance represents an independent context.

```javascript
await invoke('maa_create_instance', { instanceId: 'device-1' });
```

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

### Get Cached Image

Source: https://github.com/misteo/mxu/blob/main/_autodocs/QUICK-REFERENCE.md

Use `maa_get_cached_image` to retrieve a screenshot from the instance. This is useful for checking if a screenshot is available before proceeding.

```javascript
const img = await invoke('maa_get_cached_image', { instanceId });
if (img) {
  // Use image
} else {
  // No screenshot yet
}
```

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

### Get Resource Hash

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/maa-core-commands.md

Retrieves the hash of the currently loaded resource for a given instance. This can be used for change detection.

```rust
#[tauri::command]
pub fn maa_get_resource_hash(
    state: State<Arc<MaaState>>,
    instance_id: String,
) -> Result<String, String>
```

```javascript
const hash = await invoke('maa_get_resource_hash', { 
  instanceId: 'device-1' 
});
```

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

### Get GitHub Release Info

Source: https://github.com/misteo/mxu/blob/main/_autodocs/QUICK-REFERENCE.md

Fetches information about a specific GitHub release based on owner, repository, and target version.

```javascript
const release = await invoke('get_github_release_by_version', {
  owner,
  repo,
  targetVersion
});
```

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

### Initialize Misteo MXU

Source: https://github.com/misteo/mxu/blob/main/_autodocs/QUICK-REFERENCE.md

Initializes the Misteo MXU environment. Can optionally specify the library directory.

```javascript
await invoke('maa_init'); // or maa_init({ libDir })
```

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

### Get CPU Architecture (Rust)

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

This Rust command returns the CPU architecture of the system as a string (e.g., 'x86_64', 'aarch64').

```rust
#[tauri::command]
pub fn get_arch() -> String
```

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

### Error Handling with Try-Catch

Source: https://github.com/misteo/mxu/blob/main/_autodocs/QUICK-REFERENCE.md

Demonstrates basic error handling for command invocations using a try-catch block, specifically shown for initialization.

```javascript
try {
  await invoke('maa_init');
} catch (err) {
  console.error(`Initialization failed: ${err}`);
}
```

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

### Get Current Working Directory (Rust)

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/file-operations.md

Retrieves the absolute path of the current working directory. This command takes no parameters.

```rust
#[tauri::command]
pub fn get_cwd() -> Result<String, String>
```

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

### System Commands

Source: https://github.com/misteo/mxu/blob/main/_autodocs/MANIFEST.txt

Documentation for system-level commands, including permissions management, system information retrieval, autostart configuration, WebView2 integration, and process control, with platform-specific details.

```APIDOC
## System Commands

This section details system-level commands, covering permissions, system information, autostart configuration, WebView2 integration, and process control. It includes platform-specific implementations for Windows, macOS, and Linux.

### Commands
- `permissions`: Manages system permissions.
- `system_info`: Retrieves system information.
- `autostart`: Configures automatic startup.
- `webview2`: Integrates with WebView2.
- `process_control`: Controls system processes.

### Platform-Specific Features
- Windows: WebView2, elevation, Task Scheduler.
- macOS: LaunchAgent.
- Linux: systemd, XDG standards.

### Parameters and Return Types
Refer to `api-reference/system-commands.md` for detailed command signatures, parameter descriptions, and return types.
```

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

### Get Instance State

Source: https://github.com/misteo/mxu/blob/main/_autodocs/README.md

Retrieves the current state of an instance, including task execution statuses. Useful for monitoring progress.

```javascript
const state = await invoke('maa_get_instance_state', { instanceId: 'device-1' });
console.log(state.task_run_state.statuses); // Per-task status
```

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

### Post Click Action

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/maa-core-commands.md

Use this command to simulate a click action on a specific device instance at given coordinates. Ensure the instance ID and coordinates are valid.

```rust
#[tauri::command]
pub fn maa_post_click(
    state: State<Arc<MaaState>>,
    instance_id: String,
    x: i32,
    y: i32,
) -> Result<(), String>
```

```javascript
await invoke('maa_post_click', {
  instanceId: 'device-1',
  x: 540,
  y: 960
});
```

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

### Get Embedded Web Server Port

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Retrieve the port number on which the embedded HTTP server is currently listening. No parameters are required.

```rust
#[tauri::command]
pub fn get_web_server_port(state: State<Arc<MaaState>>) -> Result<u16, String>
```

```javascript
const port = await invoke('get_web_server_port');
console.log(`Web server on port ${port}`);
```

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

### Get MXU Version

Source: https://github.com/misteo/mxu/blob/main/_autodocs/QUICK-REFERENCE.md

Retrieve the current MXU version using the `maa_get_version` command. This returns a string representing the version number.

```javascript
const version = await invoke('maa_get_version');  // Returns: "5.5.0"
```

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

### Get Current Working Directory (JavaScript)

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/file-operations.md

Invokes the `get_cwd` command to fetch the current working directory. The result is logged to the console.

```javascript
const cwd = await invoke('get_cwd');
console.log(`CWD: ${cwd}`);
```

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

### Load Resource

Source: https://github.com/misteo/mxu/blob/main/_autodocs/QUICK-REFERENCE.md

Loads resources for a Misteo MXU instance.

```javascript
await invoke('maa_load_resource', { instanceId });
```

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

### SystemInfo Structure

Source: https://github.com/misteo/mxu/blob/main/_autodocs/types.md

Provides information about the system and application environment, including OS details, architecture, and the Tauri framework version.

```rust
pub struct SystemInfo {
    pub os: String,
    pub os_version: String,
    pub arch: String,
    pub tauri_version: String,
}
```

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

### Get Operating System Name (Rust)

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

This Rust command returns the name of the operating system as a string ('windows', 'macos', or 'linux').

```rust
#[tauri::command]
pub fn get_os() -> String
```

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

### Get Executable Directory Path

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/file-operations.md

Retrieves the absolute path to the directory containing the MXU executable. Used for locating bundled resources.

```rust
#[tauri::command]
pub fn get_exe_dir() -> Result<String, String>
```

```javascript
const exeDir = await invoke('get_exe_dir');
const maafwPath = `${exeDir}/maafw`;
const configPath = `${exeDir}/interface.json`;
```

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

### Connect Controller

Source: https://github.com/misteo/mxu/blob/main/_autodocs/QUICK-REFERENCE.md

Connects a controller to a Misteo MXU instance. Requires an instance ID and controller configuration.

```javascript
await invoke('maa_connect_controller', { 
  instanceId, 
  controllerConfig: { type: 'Adb', ... } 
});
```

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

### Get MaaFramework Version

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/maa-core-commands.md

Retrieves the current MaaFramework version without requiring initialization. This is useful for checking compatibility before full initialization.

```rust
#[tauri::command]
pub fn maa_get_version() -> Result<String, String>
```

```javascript
const version = await invoke('maa_get_version');
console.log(`MaaFramework version: ${version}`);
```

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

### get_system_info

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Retrieves comprehensive system and application version information, including OS details, architecture, and Tauri framework version.

```APIDOC
## get_system_info

### Description
Get system and application version information.

### Method
`#[tauri::command]`

### Returns
`SystemInfo` struct:
- `os: String` — "windows", "macos", or "linux"
- `os_version: String` — Version string
- `arch: String` — "x86_64", "aarch64", etc.
- `tauri_version: String` — Tauri framework version

### Request Example
```javascript
const info = await invoke('get_system_info');
console.log(`Running on ${info.os} ${info.os_version} (${info.arch})`);
console.log(`Tauri version: ${info.tauri_version}`);
```
```

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

### Open File with System Default Application (JavaScript)

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Use this JavaScript snippet to open a file with its default system application. Provide the full path to the file as an argument to the `open_file` command.

```javascript
await invoke('open_file', { 
  filePath: '/home/user/logs/debug.txt' 
});
```

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

### Get Cached Screenshot Image

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/maa-core-commands.md

Retrieve the most recently cached screenshot. The image is returned as a base64-encoded PNG string or None if no screenshot is available.

```rust
#[tauri::command]
pub fn maa_get_cached_image(
    state: State<Arc<MaaState>>,
    instance_id: String,
) -> Result<Option<String>, String>
```

```javascript
const imgBase64 = await invoke('maa_get_cached_image', { 
  instanceId: 'device-1' 
});
if (imgBase64) {
  document.getElementById('preview').src = `data:image/png;base64,${imgBase64}`;
}
```

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

### Connect ADB Controller

Source: https://github.com/misteo/mxu/blob/main/_autodocs/README.md

Connects a controller to an instance using ADB. Requires the instance ID, controller configuration including ADB path, and device address.

```javascript
await invoke('maa_connect_controller', {
  instanceId: 'device-1',
  controllerConfig: {
    type: 'Adb',
    adbPath: '/path/to/adb',
    address: devices[0].address,
    // ... other fields
  }
});
```

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

### maa_start_tasks

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/agent-commands.md

Executes one or more tasks with optional Agent support for custom recognition and actions. Agents can be launched before tasks begin, with configurable environment variables and execution paths.

```APIDOC
## maa_start_tasks

### Description
Execute one or more tasks with optional Agent support for custom recognition and actions.

### Method
`POST` (inferred from tauri::command)

### Endpoint
`/maa_start_tasks`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **instance_id** (String) - Required - Target instance ID
- **tasks** (Array<Object>) - Required - List of tasks to execute. Each task object should have:
  - **entry** (String) - Required - Task entry name from interface.json
  - **pipeline_override** (String) - Optional - YAML/JSON pipeline override (empty for none)
  - **selected_task_id** (String) - Optional - Frontend task ID for per-task status tracking
- **agent_configs** (Array<Object>) - Optional - Agent processes to launch before tasks. Each agent config object should have:
  - **child_exec** (String) - Required - Executable path or bare command name
  - **child_args** (Array<String>) - Optional - Command arguments (socket ID appended)
  - **identifier** (String) - Optional - Custom agent identifier
  - **timeout** (Number) - Optional - Connection timeout in ms (-1 = unlimited)
- **cwd** (String) - Required - Working directory for agent processes
- **tcp_compat_mode** (Boolean) - Required - Use TCP instead of IPC for agent communication (rarely needed)
- **pi_envs** (Object<String, String>) - Optional - Environment variables starting with `PI_` to inject into agent processes

### Request Example
```json
{
  "instance_id": "device-1",
  "tasks": [
    {
      "entry": "StartTask",
      "pipeline_override": "",
      "selected_task_id": "task-1"
    }
  ],
  "agent_configs": null,
  "cwd": "/home/user/automation",
  "tcp_compat_mode": false
}
```

```json
{
  "instance_id": "device-1",
  "tasks": [
    {
      "entry": "RecognitionTask",
      "pipeline_override": "",
      "selected_task_id": "task-1"
    }
  ],
  "agent_configs": [
    {
      "child_exec": "/path/to/agent.py",
      "child_args": ["--config", "settings.json"],
      "identifier": "custom-agent",
      "timeout": 30000
    }
  ],
  "cwd": "/home/user/automation",
  "tcp_compat_mode": false,
  "pi_envs": {
    "PI_LOG_LEVEL": "debug"
  }
}
```

### Response
#### Success Response (200)
- **tasks** (Array<Number>) - Vector of task IDs for status tracking

#### Response Example
```json
[
  101,
  102
]
```

**Agent Path Resolution:**
- **Bare command** (e.g., `python`) — Uses system PATH
- **Relative path** (e.g., `./agent.py`, `subdir/agent`) — Relative to `cwd`
- **Absolute path** (e.g., `/usr/bin/python`) — Used as-is

**Prerequisites:**
- Instance created via `maa_create_instance()`
- Controller connected via `maa_connect_controller()`
- Resource loaded via `maa_load_resource()`
- TaskRunState initialized (backend manages this)

**Agent Process Handling:**
- Agents launched in specified `cwd`
- Socket ID appended to `child_args` automatically
- Stdout/stderr captured and emitted as events
- PI_* environment variables filtered and injected
- Processes managed and cleaned up on task completion

**Events emitted:**
- `state-changed` — When tasks start
- `maa-callback-event` — Task callback messages
- `maa-agent-output` — Agent stdout/stderr lines
```

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

### Get MAA Task Status

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/maa-core-commands.md

Retrieves the execution status of a specific task within a MAA instance. The task ID is returned from `maa_run_task` or `maa_start_tasks`.

```rust
#[tauri::command]
pub fn maa_get_task_status(
    state: State<Arc<MaaState>>,
    instance_id: String,
    task_id: i64,
) -> Result<TaskStatus, String>
```

```javascript
const status = await invoke('maa_get_task_status', {
  instanceId: 'device-1',
  taskId: 123
});
```

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

### Create Instance

Source: https://github.com/misteo/mxu/blob/main/_autodocs/QUICK-REFERENCE.md

Creates a new Misteo MXU instance identified by an instance ID.

```javascript
await invoke('maa_create_instance', { instanceId });
```

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

### ADB Controller Configuration

Source: https://github.com/misteo/mxu/blob/main/_autodocs/QUICK-REFERENCE.md

Configuration object for connecting via ADB. Specifies ADB path, address, and methods for screenshots and input.

```javascript
{
  type: 'Adb',
  adbPath: '/path/to/adb',
  address: '127.0.0.1:5555',
  screencapMethods: '1',
  inputMethods: '1',
  config: '',
  displayShortSide: 720
}
```

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

### Retry Loading MaaFramework Library

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Attempts to reload the MaaFramework library, typically used after the user has installed necessary dependencies like VC++ redistributables.

```rust
#[tauri::command]
pub fn retry_load_maa_library(state: State<Arc<MaaState>>) -> Result<String, String>
```

```javascript
const version = await invoke('retry_load_maa_library');
console.log(`MaaFramework loaded: ${version}`);
```

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

### run_action

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Executes a pre/post-action script or command. It requires a JSON configuration string to define the action.

```APIDOC
## run_action

### Description
Execute a pre/post-action script or command.

### Method
POST (inferred from tauri::command)

### Endpoint
/run_action

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **action_config** (String) - Yes - JSON config for the action

### Request Example
```javascript
const exitCode = await invoke('run_action', {
  actionConfig: JSON.stringify({
    type: 'shell',
    command: 'python setup.py'
  })
});
```

### Response
#### Success Response (200)
- **exitCode** (i32) - Exit code

#### Response Example
```json
0
```
```

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

### Get Process Path from Window Handle (Windows)

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Retrieve the executable path of a process using its window handle. This command is specific to Windows operating systems.

```rust
#[tauri::command]
pub fn get_process_path_from_hwnd(hwnd: u64) -> Result<Option<String>, String>
```

```javascript
const path = await invoke('get_process_path_from_hwnd', { hwnd: 12345 });
if (path) {
  console.log(`Window is from: ${path}`);
}
```

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

### Execute Action Script or Command

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Execute a pre or post-action script or command. Provide a JSON configuration string detailing the action to be performed.

```rust
#[tauri::command]
pub async fn run_action(action_config: String) -> Result<i32, String>
```

```javascript
const exitCode = await invoke('run_action', {
  actionConfig: JSON.stringify({
    type: 'shell',
    command: 'python setup.py'
  })
});
```

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

### open_file

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Opens a specified file using the system's default application. This command abstracts the platform-specific methods for opening files.

```APIDOC
## open_file

### Description
Open a file with the system default application.

### Method
`#[tauri::command]`

### Parameters:
#### Path Parameters
- **file_path** (String) - Required - Full path to file

### Returns
`Result<(), String>` — Unit on success

### Platform-specific:
- **Windows** — Uses `start` command
- **macOS** — Uses `open` command
- **Linux** — Uses `xdg-open`

### Request Example
```javascript
await invoke('open_file', { 
  filePath: '/home/user/logs/debug.txt' 
});
```
```

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

### Get Operating System Name (JavaScript)

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/system-commands.md

Invoke the `get_os` command to determine the current operating system. This is useful for implementing platform-specific features or UI adjustments.

```javascript
const os = await invoke('get_os');
const isWindows = os === 'windows';
```

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

### Win32 Controller Configuration

Source: https://github.com/misteo/mxu/blob/main/_autodocs/QUICK-REFERENCE.md

Configuration object for connecting via Win32. Specifies window handle and methods for screenshots, mouse, and keyboard input.

```javascript
{
  type: 'Win32',
  handle: 12345,
  screencapMethod: 1,
  mouseMethod: 1,
  keyboardMethod: 1,
  displayShortSide: 1080
}
```

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

### Get Cached Win32 Windows

Source: https://github.com/misteo/mxu/blob/main/_autodocs/api-reference/state-and-queries.md

Retrieves the last cached list of Win32 windows. Use this to populate lists of available windows for automation without rescanning.

```rust
#[tauri::command]
pub fn maa_get_cached_win32_windows(
    state: State<Arc<MaaState>>,
) -> Result<Vec<Win32Window>, String>
```