### Device Configuration Example

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/README.md

This JSON snippet shows an example of a device configuration for the flutterpi_tool. It specifies details like device ID, SSH remote access, installation path, display size, and filesystem layout.

```json
{
  "devices": [
    {
      "id": "pi5",
      "sshRemote": "pi@192.168.1.100",
      "remoteInstallPath": "/tmp/",
      "displaySizeMillimeters": [285, 190],
      "filesystemLayout": "flutter-pi"
    }
  ]
}
```

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

### Example Configuration File

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/configuration.md

This JSON structure defines the configuration for multiple devices, including SSH details, installation paths, and display properties. It shows how to specify different filesystem layouts for different device types.

```json
{
  "devices": [
    {
      "id": "pi5",
      "sshExecutable": null,
      "sshRemote": "pi@pi5.local",
      "remoteInstallPath": "/tmp/",
      "displaySizeMillimeters": [285, 190],
      "devicePixelRatio": null,
      "useDummyDisplay": false,
      "dummyDisplaySize": null,
      "filesystemLayout": "flutter-pi",
      "rotation": null
    },
    {
      "id": "yocto-device",
      "sshExecutable": "/usr/bin/ssh",
      "sshRemote": "root@yocto.internal",
      "remoteInstallPath": "/root/apps",
      "filesystemLayout": "meta-flutter"
    }
  ]
}
```

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

### Example: Get Device SDK Name and Version

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/execution-and-logging.md

Demonstrates how to fetch and print the device's SDK name and version. The output will indicate that the target OS is Linux.

```dart
final sdk = await device.sdkNameAndVersion;
print('Target OS: $sdk');  // Output: Target OS: Linux
```

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

### Install and Use flutterpi_tool

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/README.md

Install the tool globally, add a device with a specific ID, build a release version for a target architecture, and run the application on the configured device.

```bash
# Install
flutter pub global activate flutterpi_tool

# Add device
flutterpi_tool devices add pi@192.168.1.100 --id pi5

# Build for target
flutterpi_tool build --release --arch arm64 --cpu pi4

# Run on device
flutterpi_tool run -d pi5
```

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

### Complete App Lifecycle Example

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/execution-and-logging.md

Demonstrates the full lifecycle of building, deploying, running, and logging a Flutter app on a remote device. This snippet covers device creation, app building, starting the app, monitoring logs, and stopping the app.

```dart
// 1. Create device from config
final device = FlutterpiSshDevice(
  id: 'pi5',
  name: 'pi5',
  sshUtils: sshUtils,
  remoteInstallPath: '/tmp/',
  logger: logger,
  os: os,
);

// 2. Build app
final appBuilder = AppBuilder(
  operatingSystemUtils: os,
  buildSystem: buildSystem,
);

final app = await appBuilder.buildApp(
  buildableBundle: BuildableFlutterpiAppBundle(
    id: 'hello_world',
    name: 'hello_world',
    displayName: 'Hello World',
  ),
  targetPlatform: TargetPlatform.linux_arm,
  buildInfo: BuildInfo(BuildMode.debug, null),
);

// 3. Start app on device
final result = await device.startApp(
  app,
  mainPath: 'lib/main.dart',
  debuggingOptions: DebuggingOptions.enabled(
    BuildInfo(BuildMode.debug, null),
  ),
);

if (result.started) {
  // 4. Monitor logs
  final logReader = await device.getLogReader(app: app);
  logReader.logLines.listen((line) {
    print('[App] $line');
  });

  // 5. Connect debugger if needed
  if (result.vmServiceUri != null) {
    print('VM Service: ${result.vmServiceUri}');
    // Connect with debugger tools
  }

  // 6. Wait for app to finish
  await result.runningApp.onExit;

  // 7. Stop app
  await device.stopApp(app);
}

// 8. Clean up device
await device.dispose();

```

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

### Example Output of Run Command

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/commands.md

This shows the typical output when the flutterpi_tool run command is executed successfully, including build, installation, and connection messages.

```text
Launching lib/main.dart on pi5 in debug mode...
Building Flutter-Pi bundle...
Installing app on device...
Starting app on device...
Connected to service protocol...
[Service] Listening on http://127.0.0.1:54321/...
```

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

### installApp

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/devices.md

Installs an application bundle to the device by copying it via SCP and making binaries executable.

```APIDOC
## installApp(FlutterpiAppBundle app, {String? userIdentifier})

### Description
Installs an application bundle to the device by copying it via SCP and making binaries executable. The process includes uninstalling any existing version of the app before copying the new one.

### Parameters
- **app** (FlutterpiAppBundle) - Required - The prebuilt application bundle to install.
- **userIdentifier** (String?) - Optional - Unused parameter for compatibility with the Device interface.

### Returns
Future<bool> - Returns true upon successful installation.

### Throws
- ToolExit - If the provided app is not a PrebuiltFlutterpiAppBundle.
- SshException - If the SCP or chmod operations fail during installation.

### Process
1. Remove existing app (uninstallApp).
2. Copy the entire app directory to the remote device using SCP.
3. Make all binaries within the app directory executable using `chmod +x`.

### Example
```dart
final success = await device.installApp(appBundle);
if (success) {
  print('App installed at ${device.remoteInstallPath}/${app.id}');
}
```
```

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

### Log Output Example

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/execution-and-logging.md

Example of application log output, showing different log levels and messages.

```text
Connected to service protocol at http://127.0.0.1:54321/
I/flutter: [INFO] Application initialized
I/flutter: [DEBUG] Building widget tree
I/flutter: [VERBOSE] Memory usage: 45 MB
```

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

### Example: Get Target Platform Architecture

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/execution-and-logging.md

Shows how to access the `flutterpiTargetPlatform` property and print the detected architecture triple. This example assumes the property has been accessed and its value is available.

```dart
final target = await device.flutterpiTargetPlatform;
print('Architecture: ${target.triple}');  // arm-linux-gnueabihf
```

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

### Start Application

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/execution-and-logging.md

Launches a Flutter application on the flutter-pi device. It handles building the app if necessary, installing it, and executing it via SSH, providing a reference to the running application and its VM service URI if debugging is enabled.

```APIDOC
## Start Application

### Description
Launch Flutter application on flutter-pi device.

### Method Signature
```dart
Future<LaunchResult> startApp(
  FlutterpiAppBundle app,
  {
  required String? mainPath,
  required DebuggingOptions debuggingOptions,
  String? route,
  String? entrypoint,
  String? deviceUser,
}
)```

### Parameters
- `app` (FlutterpiAppBundle): Built application bundle (PrebuiltFlutterpiAppBundle).
- `mainPath` (String?): Entry point file (e.g., 'lib/main.dart').
- `debuggingOptions` (DebuggingOptions): Debug configuration from flutter_tools.
- `route` (String?): Initial route (ignored by flutter-pi).
- `entrypoint` (String?): Entry point function (ignored).
- `deviceUser` (String?): SSH user override (ignored).

### Returns
LaunchResult with success status and connection details.

### Execution Flow
1. Build app if needed (BuildableFlutterpiAppBundle)
2. Install app bundle to remote via SCP
3. Create log reader for output capture
4. Execute flutter-pi via SSH with allocated PTY
5. Connect log reader to process output
6. Return LaunchResult with running app reference

### Example
```dart
final result = await device.startApp(
  bundle,
  mainPath: 'lib/main.dart',
  debuggingOptions: DebuggingOptions.enabled(buildInfo),
);

if (result.started) {
  print('App started: ${result.vmServiceUri}');
  // Connect to VM service for debugging
} else {
  print('Failed to start app');
}
```
```

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

### Install Flutterpi App

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/devices.md

Installs a prebuilt Flutter app bundle to the device using SCP and makes binaries executable. Returns true on success. Throws ToolExit or SshException on failure.

```dart
Future<bool> installApp(
  FlutterpiAppBundle app, {
  String? userIdentifier,
})
```

```dart
// 1. Remove existing app (uninstallApp)
// 2. SCP entire app directory to remote
// 3. Make all binaries in app executable with chmod +x
```

```dart
final success = await device.installApp(appBundle);
if (success) {
  print('App installed at ${device.remoteInstallPath}/${app.id}');
}
```

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

### Example Usage of buildApp

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/build-system.md

Demonstrates how to use the appBuilder.buildApp method to create a release build for the Linux ARM platform. Ensure you have a BuildableFlutterpiAppBundle configured.

```dart
final bundle = await appBuilder.buildApp(
  buildableBundle: BuildableFlutterpiAppBundle(
    id: 'myapp',
    name: 'myapp',
    displayName: 'My App',
  ),
  targetPlatform: TargetPlatform.linux_arm,
  buildInfo: BuildInfo(BuildMode.release, null),
  mainPath: 'lib/main.dart',
  outputDir: '/tmp/build',
);

print('Built: ${bundle.directory.path}');
```

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

### Instantiate BuildableFlutterpiAppBundle

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/build-system.md

Example of creating an instance of BuildableFlutterpiAppBundle with required parameters.

```dart
final buildable = BuildableFlutterpiAppBundle(
  id: 'hello_world',
  name: 'hello_world',
  displayName: 'Hello World',
);
```

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

### Basic Run Command Usage

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/commands.md

This example shows the basic syntax for running a Flutter app on a specific device using its ID.

```bash
flutterpi_tool run [OPTIONS] -d DEVICE_ID
```

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

### JSON Output Example

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/commands.md

Example of JSON output when the --machine flag is used with the 'devices list' subcommand.

```json
[
  {
    "name": "pi5",
    "id": "pi5",
    "isConnected": true,
    "targetPlatform": "linux-arm64",
    "emulatorId": null,
    "type": "FlutterpiSshDevice"
  }
]
```

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

### startApp

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/devices.md

Starts a Flutter application on the device via SSH.

```APIDOC
## startApp(FlutterpiAppBundle app, {required String? mainPath, required DebuggingOptions debuggingOptions, String? route, String? entrypoint, String? deviceUser})

### Description
Starts a Flutter application on the device via SSH. This method handles building the app if necessary, installing it, and then executing it with proper PTY allocation for signal handling and log streaming.

### Parameters
- **app** (FlutterpiAppBundle) - Required - The application to launch.
- **mainPath** (String?) - Required - The entry point file of the application (e.g., 'lib/main.dart').
- **debuggingOptions** (DebuggingOptions) - Required - Settings for debugging, such as breakpoints and VM service.
- **route** (String?) - Optional - The initial route to navigate to (currently unused).
- **entrypoint** (String?) - Optional - The entry point function (currently unused).
- **deviceUser** (String?) - Optional - An override for the SSH user (currently unused).

### Returns
Future<LaunchResult> - An object containing the success status and error details of the launch.

### Process
1. Build the app if it's a `BuildableFlutterpiAppBundle`.
2. Install the app to the device.
3. Execute the app via SSH, allocating a PTY for signal handling.
4. Stream stdout and stderr to a log reader.
5. Return a `LaunchResult` with process details.

```

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

### Command Line Usage Examples

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/exported-api-summary.md

These bash commands demonstrate how to activate, and use the flutterpi_tool from the command line for common operations like building, running, and listing devices.

```bash
flutter pub global activate flutterpi_tool
```

```bash
flutterpi_tool --help
```

```bash
flutterpi_tool build --release
```

```bash
flutterpi_tool run -d pi5
```

```bash
flutterpi_tool devices list
```

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

### Example Usage of getArtifactDirectory

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/cache-and-github.md

Demonstrates how to get the cache directory for 'flutter-pi' artifacts.

```dart
final flutterpiDir = cache.getArtifactDirectory('flutter-pi');
// Returns: ~/.flutter/flutter-pi-cache/artifacts/flutter-pi/
```

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

### Start Flutterpi App Execution

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/devices.md

Starts a Flutter app on the device via SSH. Handles app building if necessary, installation, and execution with PTY allocation for signal handling. Streams logs and returns LaunchResult.

```dart
Future<LaunchResult> startApp(
  FlutterpiAppBundle app,
  {
  required String? mainPath,
  required DebuggingOptions debuggingOptions,
  String? route,
  String? entrypoint,
  String? deviceUser,
})
```

```dart
// 1. Build app if needed (BuildableFlutterpiAppBundle)
// 2. Install app to device
// 3. Execute via SSH with allocated PTY (for signal handling)
// 4. Stream stdout/stderr to log reader
// 5. Return LaunchResult with process details
```

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

### Start Flutter Application

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/execution-and-logging.md

Launches a Flutter application on a flutter-pi device. Requires the application bundle, main path, and debugging options. It handles building, installing, and executing the app remotely.

```dart
Future<LaunchResult> startApp(
  FlutterpiAppBundle app,
  {
    required String? mainPath,
    required DebuggingOptions debuggingOptions,
    String? route,
    String? entrypoint,
    String? deviceUser,
  }
)
```

```dart
final result = await device.startApp(
  bundle,
  mainPath: 'lib/main.dart',
  debuggingOptions: DebuggingOptions.enabled(buildInfo),
);

if (result.started) {
  print('App started: ${result.vmServiceUri}');
  // Connect to VM service for debugging
} else {
  print('Failed to start app');
}
```

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

### FlutterPI Tool CLI Commands

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/exported-api-summary.md

Examples of common commands for building, running, and managing devices with the flutterpi_tool. These commands are intended for end-users and are the primary way to interact with the tool.

```bash
flutterpi_tool build --release --arch arm64 --cpu pi4
```

```bash
flutterpi_tool run -d pi5
```

```bash
flutterpi_tool devices add pi@hostname --display-size=285x190
```

```bash
flutterpi_tool devices list
```

```bash
flutterpi_tool precache
```

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

### Instantiate and Use GithubArtifact

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/cache-and-github.md

Example of creating a GithubArtifact instance and initiating a download using its archive download URL. Ensure an HTTP client is available for making requests.

```dart
final artifact = GithubArtifact(
  name: 'flutter-pi-arm-linux-gnueabihf-release',
  archiveDownloadUrl: Uri.parse('https://api.github.com/repos/...'),
);

// Download
final response = await httpClient.get(artifact.archiveDownloadUrl);
final bytes = response.bodyBytes;
```

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

### Example Usage of updateAll

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/cache-and-github.md

Shows how to use the updateAll method to download universal artifacts for a specific host platform, target platform, and engine flavor, including debug symbols.

```dart
await cache.updateAll(
  const {DevelopmentArtifact.universal},
  host: FlutterpiHostPlatform.linuxX64,
  flutterpiPlatforms: {FlutterpiTargetPlatform.genericArmV7},
  engineFlavors: {EngineFlavor.release},
  includeDebugSymbols: true,
);
```

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

### MyGithub Caching Example

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/cache-and-github.md

Demonstrates how to create an authenticated and cached GitHub client using the MyGithub factory. This is useful for reducing API rate limits.

```dart
final github = MyGithub.caching(
  httpClient: httpClient,
  auth: gh.Authentication.bearerToken(token),
);
```

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

### Add Device with Custom Display Size and Rotation

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/configuration.md

Configure both custom display dimensions and rotation. This example sets a portrait orientation with a specific physical size.

```bash
# Portrait with custom rotation
flutterpi_tool devices add pi@pi5 --display-size=285x190 --rotation=0
```

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

### PrebuiltFlutterpiAppBundle

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/build-system.md

Represents a compiled app that is ready for installation. This is an output from AppBuilder.buildApp() and an input to Device.installApp().

```APIDOC
## Class: PrebuiltFlutterpiAppBundle

### Description
Compiled app ready for installation.

### Constructor
```dart
PrebuiltFlutterpiAppBundle({
  required String id,
  required String name,
  required String displayName,
  required Directory directory,
  required List<File> binaries,
  bool includesFlutterpiBinary = true,
});
```

### Properties
- **id** (String) - Required - Unique app identifier
- **name** (String) - Required - App package name
- **displayName** (String) - Required - Human-readable app name
- **directory** (Directory) - Required - Root directory of built bundle
- **binaries** (List<File>) - Required - Executable binaries in bundle
- **includesFlutterpiBinary** (bool) - Optional - Whether flutter-pi binary is bundled

### Usage
Output from AppBuilder.buildApp(), input to Device.installApp().

### Directory Structure
```
{directory}/
├── lib/
│   ├── libapp.so
│   ├── libflutter_engine.so
│   └── ... (other native libraries)
├── app/
│   ├── kernel_blob.bin
│   └── isolate_snapshot_data
└── flutter-pi (executable, optional)
```
```

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

### MyGithub getLatestRelease Example

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/cache-and-github.md

Fetches the most recent release from a specified GitHub repository and prints its tag name. Requires a repository slug.

```dart
final release = await github.getLatestRelease(
  gh.RepositorySlug('ardera', 'flutter-pi')
);
print('Latest: ${release.tagName}');
```

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

### Command-Line Argument Precedence Example

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/configuration.md

Demonstrates how command-line arguments override configuration file settings. In this case, the --remote-install-path specified on the command line takes precedence over the one in the configuration file.

```bash
# Configuration has: remoteInstallPath=/tmp/
# Command-line adds: --remote-install-path=/home/pi/apps
# Result: /home/pi/apps is used
flutterpi_tool run -d pi5 --remote-install-path=/home/pi/apps
```

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

### Method Signature Example

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/INDEX.md

Illustrates the standard format for method signatures in Dart, including return type, method name, and parameter types.

```dart
ReturnType methodName(ParameterType parameter) => implementation;
```

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

### FlutterpiArgs Usage Example

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/devices.md

Instantiates FlutterpiArgs with specific display and layout settings, then uses these arguments when creating a FlutterpiSshDevice.

```dart
final args = FlutterpiArgs(
  explicitDisplaySizeMillimeters: (285, 190),
  filesystemLayout: FilesystemLayout.metaFlutter,
  rotation: 90,
);

final device = FlutterpiSshDevice(
  id: 'pi5',
  // ... other parameters
  args: args,
);
```

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

### Example Usage of FlutterpiBinary

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/artifacts.md

Demonstrates how to create a FlutterpiBinary artifact instance and retrieve its corresponding file path from the cache. This is useful for locating the prebuilt flutter-pi executable.

```dart
final artifact = FlutterpiBinary(
  target: FlutterpiTargetPlatform.genericArmV7,
  mode: BuildMode.release,
);

final file = artifacts.getFlutterpiArtifact(artifact);
// Returns: ~/.flutter/flutter-pi-cache/artifacts/flutter-pi/arm-linux-gnueabihf/release/flutter-pi
```

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

### Example Usage of FlutterpiCache.fromWorkflow

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/cache-and-github.md

Demonstrates how to create a FlutterpiCache instance using the fromWorkflow factory method, specifying the GitHub Actions run ID and an available engine version.

```dart
final cache = FlutterpiCache.fromWorkflow(
  // ... standard parameters ...
  runId: 12345678,
  availableEngineVersion: 'abc123def456',
  github: createGithub(),
);
```

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

### Example Usage of Engine Artifact

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/artifacts.md

Demonstrates how to create an Engine artifact instance and retrieve its corresponding file path. This is useful for locating the compiled Flutter engine library.

```dart
final artifact = Engine(
  target: FlutterpiTargetPlatform.genericAArch64,
  flavor: EngineFlavor.release,
);

final file = artifacts.getFlutterpiArtifact(artifact);
```

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

### Run on Device Matching Prefix

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/commands.md

Targets a device whose ID starts with a specified prefix, useful when device IDs are similar or when selecting from a group of devices.

```bash
# Run on device matching prefix
flutterpi_tool run -d pi
```

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

### Get Target Platform

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/commands.md

Converts --arch and --cpu options into a FlutterpiTargetPlatform object.

```dart
FlutterpiTargetPlatform getTargetPlatform()
```

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

### Add Device with Standard flutter-pi Filesystem Layout

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/configuration.md

Configure the tool to use the default flutter-pi filesystem layout. This is typically used for standard Raspberry Pi setups.

```bash
flutterpi_tool devices add pi@pi5 --fs-layout=flutter-pi
```

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

### Connect Debugger via Command Line

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/execution-and-logging.md

Steps to connect a diagnostic client to an app started with the `--start-paused` flag. This allows for attaching debuggers after the application has begun execution.

```bash
# Start app paused
flutterpi_tool run -d pi5 --start-paused

# Connect with diagnostic client
dart devtools
```

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

### Dart Define JSON Configuration File

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/configuration.md

Example JSON file format for passing multiple Dart define constants. Ensure the values are correctly formatted strings.

```json
{
  "API_URL": "https://api.example.com",
  "APP_VERSION": "1.0.0",
  "DEBUG": "false"
}
```

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

### Add Device with Display Rotation

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/configuration.md

Set the display rotation in degrees (0, 90, 180, 270). This example shows setting a landscape orientation.

```bash
# Landscape orientation (90 degree rotation)
flutterpi_tool devices add pi@pi5 --rotation=90
```

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

### FlutterpiSshDevice Constructor

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/devices.md

Initializes a FlutterpiSshDevice instance. Requires essential parameters like device ID, name, SSH utilities, and logger. The remote install path defaults to '/tmp/'.

```dart
FlutterpiSshDevice({
  required String id,
  required String name,
  required SshUtils sshUtils,
  required String? remoteInstallPath,
  required Logger logger,
  required MoreOperatingSystemUtils os,
  FlutterpiArgs args = const FlutterpiArgs(),
})
```

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

### Add a Device to flutterpi_tool

Source: https://github.com/ardera/flutterpi_tool/blob/main/README.md

Add a new device to flutterpi_tool for targeting. This example adds a device named 'pi5' accessible via 'pi@pi5'.

```console
$ flutterpi_tool devices add pi@pi5
Device "pi5" has been added successfully.
```

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

### Run with VM Service for Debugging

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/commands.md

Starts the Flutter app with the VM service enabled, allowing for debugging. Use the --start-paused flag to begin execution in a paused state.

```bash
# Run with VM service for debugging
flutterpi_tool run -d pi5 --start-paused
```

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

### Pubspec.yaml Configuration for Flutter-pi

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/configuration.md

Example pubspec.yaml file structure. Ensure SDK constraints are compatible with flutter-pi and remove incompatible plugins for headless systems.

```yaml
name: my_flutter_app
version: 1.0.0
description: Flutter app for flutter-pi

environment:
  sdk: ">=3.0.0 <4.0.0"
  flutter: ">=3.41.0"

dependencies:
  flutter:
    sdk: flutter
  # ... other dependencies

dev_dependencies:
  flutter_test:
    sdk: flutter
  # ... dev dependencies

flutter:
  uses-material-design: true

```

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

### Activate flutterpi_tool Globally

Source: https://github.com/ardera/flutterpi_tool/blob/main/README.md

Install the flutterpi_tool globally using the flutter pub global activate command. Ensure your Flutter SDK is up-to-date to avoid version conflicts.

```shell
flutter pub global activate flutterpi_tool
```

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

### List All Commands

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/INDEX.md

Use this command to see all available subcommands and their options.

```bash
flutterpi_tool --help
```

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

### Build Application for Target

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/INDEX.md

Builds the application in release mode for a specified architecture and CPU.

```bash
flutterpi_tool build --release --arch arm64 --cpu pi4
```

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

### Select Target Architecture and CPU Tuning in Build Command

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/platforms-and-architectures.md

Demonstrates how to specify the target architecture and CPU tuning when building a Flutter application using the flutterpi_tool. Options include generic architectures and specific CPU tunings like 'pi3' and 'pi4'.

```bash
# Generic 32-bit ARM (default)
flutterpi_tool build
```

```bash
# Raspberry Pi 4 specific (64-bit optimized)
flutterpi_tool build --arch arm64 --cpu pi4
```

```bash
# x86-64 generic
flutterpi_tool build --arch x64
```

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

### Define PrebuiltFlutterpiAppBundle

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/build-system.md

Represents a compiled Flutter application ready for installation. It includes the directory and binaries of the built bundle.

```dart
class PrebuiltFlutterpiAppBundle extends FlutterpiAppBundle {
  PrebuiltFlutterpiAppBundle({
    required String id,
    required String name,
    required String displayName,
    required Directory directory,
    required List<File> binaries,
    bool includesFlutterpiBinary = true,
  });

  final Directory directory;
  final List<File> binaries;
}
```

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

### Build with Standard flutter-pi Filesystem Layout

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/configuration.md

Build the project using the standard flutter-pi filesystem layout.

```bash
flutterpi_tool build --fs-layout=flutter-pi
```

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

### Get Include Debug Symbols Flag

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/commands.md

Checks the --debug-symbols flag to determine if debug symbols should be included.

```dart
bool getIncludeDebugSymbols()
```

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

### Get Artifact Directory

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/cache-and-github.md

Retrieves or creates the cache directory for a given artifact type. Returns the path to the directory.

```dart
Directory getArtifactDirectory(String type)
```

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

### Troubleshoot Build Fails

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/README.md

Follow these steps when build processes fail. This involves checking the device architecture, clearing the local cache, and precaching necessary artifacts.

```bash
# Check device architecture
ssh pi@hostname uname -m
```

```bash
# Clear cache
rm -rf ~/.flutter/flutter-pi-cache
```

```bash
# Precache artifacts
flutterpi_tool precache --verbose
```

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

### Get Devices from Configuration

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/devices.md

Retrieves a list of device configurations from FlutterPiToolConfig. This is typically used to load pre-configured devices.

```dart
final config = FlutterPiToolConfig(...);
final devices = config.getDevices();
// Returns: [DeviceConfigEntry, ...]
```

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

### Get Local Flutterpi Executable Path

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/commands.md

Retrieves the custom flutter-pi binary path specified by the --flutterpi-binary option.

```dart
File? getLocalFlutterpiExecutable()
```

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

### Troubleshoot Build Failures

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/INDEX.md

Offers commands to check the device architecture, clear the build cache, and precache necessary artifacts when build failures occur.

```bash
ssh pi@hostname uname -m
```

```bash
rm -rf ~/.flutter/flutter-pi-cache
```

```bash
flutterpi_tool precache
```

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

### List Connected Devices

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/INDEX.md

Displays a list of all configured and connected devices.

```bash
flutterpi_tool devices list
```

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

### Get Engine Flavor

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/commands.md

Parses flags like --debug, --profile, --release, and --debug-unoptimized to return the EngineFlavor.

```dart
EngineFlavor getEngineFlavor()
```

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

### Get Device SDK Name and Version

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/execution-and-logging.md

Retrieve the operating system name and version of the device. For flutter-pi devices, this will always return 'Linux'.

```dart
Future<String> get sdkNameAndVersion
```

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

### Execution and Logging

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/SUMMARY.txt

Information on how to execute applications on devices and handle logging output.

```APIDOC
## Execution and Logging

This section details how to execute Flutter applications on target devices using flutterpi_tool and how to manage the logging output generated during execution.

### Application Execution

Once an application is built and deployed, it can be executed on the target device. This typically involves starting the compiled application process on the device.

### Logging

The tool provides mechanisms for capturing and displaying logs from the running application and the tool itself. Log levels can be configured to control the verbosity of the output.

### Commands

- **run**: Executes the application on a specified device, often streaming logs in real-time.

#### Example: Running an Application and Viewing Logs

```bash
flutterpi_tool run --device-ip 192.168.1.100 --verbose
```

### Log Levels

Configurable log levels include `debug`, `info`, `warning`, and `error`. These can be set via the configuration file or command-line options.
```

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

### Test Display Configuration

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/configuration.md

Access the device's help information via SSH to check supported display configurations. This is useful for 'Display Configuration Issues'.

```bash
ssh pi@<hostname> flutter-pi --help
```

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

### Instantiate CachedFlutterpiArtifacts

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/artifacts.md

Example of how to create an instance of CachedFlutterpiArtifacts, providing the necessary inner artifacts and cache objects. It then demonstrates retrieving a specific flutter-pi binary artifact.

```dart
final artifacts = CachedFlutterpiArtifacts(
  inner: standardArtifacts,
  cache: flutterpiCache,
);

final binary = artifacts.getFlutterpiArtifact(
  FlutterpiBinary(
    target: FlutterpiTargetPlatform.pi4_64,
    mode: BuildMode.release,
  ),
);
```

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

### Run Application on Device

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/INDEX.md

Executes the application on a specified target device.

```bash
flutterpi_tool run -d pi5
```

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

### Connect Debugger via VS Code

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/execution-and-logging.md

Configuration for attaching a debugger to a Flutter-Pi device using VS Code. Ensure the `deviceId` and `vmServiceUri` are correct for your setup.

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Flutter-Pi Device",
      "type": "dart",
      "request": "attach",
      "deviceId": "pi5",
      "vmServiceUri": "http://127.0.0.1:54321/"
    }
  ]
}
```

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

### Global Options for flutterpi_tool

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/exported-api-summary.md

These options apply to all commands. Use --device-id to target a specific device and --verbose for detailed output.

```bash
Global Options:
  -d, --device-id        Target device
  --verbose              Verbose output
  -h, --help             Show help
```

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

### SshUtils Constructor

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/devices.md

Initialize SshUtils with process utilities and a default remote host.

```APIDOC
## SshUtils

Wrapper for SSH/SCP operations to remote devices.

### Constructor

```dart
SshUtils({
  required ProcessUtils processUtils,
  required String defaultRemote,
})
```
```

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

### Platform Selection in Build Command

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/platforms-and-architectures.md

How to select the target architecture and CPU tuning when using the `flutterpi_tool build` command.

```APIDOC
### Platform Selection in Build Command

The `build` command allows selecting target architecture and CPU tuning:

```bash
# Architecture options: arm, arm64, x64, riscv64
# CPU tuning: generic (default), pi3, pi4

# Generic 32-bit ARM (default)
flutterpi_tool build

# Raspberry Pi 4 specific (64-bit optimized)
flutterpi_tool build --arch arm64 --cpu pi4

# x86-64 generic
flutterpi_tool build --arch x64
```
```

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

### Commands for flutterpi_tool

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/exported-api-summary.md

These are the main commands available. Refer to api-reference/commands.md for detailed command options.

```bash
Commands:
  build                  Compile app for target
  run                    Build and run on device
  devices                Manage devices
    add                  Add new device
    remove               Remove device
    list                 List devices
  precache               Download artifacts
  test                   Run tests on device
```

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

### Add New SSH Device

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/commands.md

Adds a new SSH device to the flutter-pi configuration. You can specify custom IDs, installation paths, display settings, and SSH executables.

```bash
flutterpi_tool devices add [USER@]HOSTNAME [OPTIONS]
```

```bash
# Add device with defaults
flutterpi_tool devices add pi@pi5
```

```bash
# Add with custom ID and display size
flutterpi_tool devices add pi@pi5 --id my-pi --display-size=285x190
```

```bash
# Add meta-flutter device
flutterpi_tool devices add root@yocto-device --fs-layout=meta-flutter
```

```bash
# Add with dummy display
flutterpi_tool devices add pi@pi5 --dummy-display
```

```bash
# Specify installation directory
flutterpi_tool devices add pi@pi5 --remote-install-path=/home/pi/apps
```

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

### Display flutterpi_tool Help Information

Source: https://github.com/ardera/flutterpi_tool/blob/main/README.md

View the main help message for flutterpi_tool to understand its usage, global options, and available commands.

```console
$ flutterpi_tool --help
A tool to make development & distribution of flutter-pi apps easier.

Usage: flutterpi_tool <command> [arguments]

Global options:
-h, --help         Print this usage information.
-d, --device-id    Target device id or name (prefixes allowed).

Other options
    --verbose      Enable verbose logging.

Available commands:

Flutter-Pi Tool
  precache   Populate the flutterpi_tool's cache of binary artifacts.

Project
  build      Builds a flutter-pi asset bundle.
  run        Run your Flutter app on an attached device.

Tools & Devices
  devices    List & manage flutterpi_tool devices.

Run "flutterpi_tool help <command>" for more information about a command.
```

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

### Get Flutterpi Target Platform

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/devices.md

Queries the target device architecture via SSH. Returns a FlutterpiTargetPlatform enum value. Throws an SshException if the SSH command fails.

```dart
Future<FlutterpiTargetPlatform> getFlutterpiTargetPlatform()
```

```dart
// Executes: ssh device "uname -m"
// Parses output: armv7l → genericArmV7, aarch64 → genericAArch64, etc.
```

```dart
final target = await device.flutterpiTargetPlatform;
print('Device is ${target.triple}');
```

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

### Troubleshoot Device Not Found

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/README.md

Use these commands to diagnose and resolve 'Device not found' errors. Ensure SSH access is functional before adding the device.

```bash
# Check SSH access
ssh pi@hostname
```

```bash
# Add device
flutterpi_tool devices add pi@hostname --id pi5
```

```bash
# List to verify
flutterpi_tool devices list
```

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

### Get Device Log Reader

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/execution-and-logging.md

Retrieve a log reader for either global device logs or application-specific logs. The reader supports listening to real-time log lines.

```dart
FutureOr<DeviceLogReader> getLogReader({
  ApplicationPackage? app,
  bool includePastLogs = false,
})
```

```dart
// Global device logs
final globalReader = await device.getLogReader();
globalReader.logLines.listen((line) {
  print('[Device] $line');
});

// App-specific logs
final appReader = await device.getLogReader(app: myApp);
appReader.logLines.listen((line) {
  print('[App] $line');
});
```

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

### GitHub Authentication

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/cache-and-github.md

Information on how to authenticate with the GitHub API to access artifacts, including different token sources, setup instructions, and rate limits for anonymous and authenticated requests.

```APIDOC
## Authentication

### Token Sources (Priority Order)

1. `--github-artifacts-auth-token` command-line option
2. `GITHUB_TOKEN` environment variable
3. Anonymous (public repositories only)

### Token Setup

**Create Token:**
```bash
# GitHub Settings > Developer settings > Personal access tokens > Tokens (classic)
# Required scopes: repo (for private repos)
# Public repos can use anonymous access
```

**Set Environment:**
```bash
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

**Use in Command:**
```bash
flutterpi_tool build --release \
  --github-artifacts-auth-token=$GITHUB_TOKEN
```

### Rate Limiting

- **Anonymous:** 60 requests/hour per IP
- **Authenticated:** 5,000 requests/hour per user

Check rate limit:
```bash
curl -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/rate_limit
```
```

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

### Add Device with Default Virtual Display

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/configuration.md

Configure the tool to use a default virtual display (1280x720) when no physical display is available (headless systems).

```bash
# Use default virtual display (1280x720)
flutterpi_tool devices add pi@pi5 --dummy-display
```

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

### Build with Meta-Flutter Filesystem Layout

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/configuration.md

Build the project using the meta-flutter filesystem layout, intended for Yocto-based embedded systems with meta-flutter integration.

```bash
flutterpi_tool build --fs-layout=meta-flutter
```

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

### MyGithub getWorkflowRunArtifacts Example

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/cache-and-github.md

Retrieves a list of artifacts from a specific GitHub Actions workflow run, with an optional filter for artifact names. It then prints the name and download URL of each artifact.

```dart
final artifacts = await github.getWorkflowRunArtifacts(
  repo: gh.RepositorySlug('google', 'engine'),
  runId: 12345678,
  nameFilter: 'flutter_pi',
);

for (final artifact in artifacts) {
  print('${artifact.name}: ${artifact.archiveDownloadUrl}');
}
```

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

### Create FlutterpiSshDevice Instance

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/execution-and-logging.md

Instantiates a `FlutterpiSshDevice` with specific configuration details including ID, name, SSH utilities, remote path, logger, OS, and arguments like display size and filesystem layout.

```dart
final device = FlutterpiSshDevice(
  id: 'pi5',
  name: 'Raspberry Pi 5',
  sshUtils: sshUtils,
  remoteInstallPath: '/tmp/',
  logger: logger,
  os: os,
  args: FlutterpiArgs(
    displaySizeMillimeters: (285, 190),
    filesystemLayout: FilesystemLayout.flutterPi,
  ),
);
```

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

### Add Device with Meta-Flutter Filesystem Layout

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/configuration.md

Configure the tool to use the meta-flutter filesystem layout, suitable for Yocto-based distributions.

```bash
flutterpi_tool devices add root@yocto --fs-layout=meta-flutter
```

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

### FlutterPi Tool File Organization

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/README.md

Overview of the project's directory structure, highlighting key markdown files for documentation and reference.

```tree
output/
├── INDEX.md                         ← Start here
├── README.md                        ← This file
├── overview.md                      ← Project overview
├── types.md                         ← Type reference
├── configuration.md                 ← Configuration guide
├── exported-api-summary.md          ← API exports
└── api-reference/
    ├── config.md                    ← Device config
    ├── devices.md                   ← Device management
    ├── platforms-and-architectures.md
    ├── artifacts.md                 ← Artifact types
    ├── cache-and-github.md          ← Caching
    ├── build-system.md              ← Building
    ├── commands.md                  ← CLI reference
    └── execution-and-logging.md     ← Runtime
```

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

### Get Flutterpi Device Log Reader

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/devices.md

Retrieves a log reader for either the entire device or a specific application. Caches readers per app. The `includePastLogs` parameter is currently unused.

```dart
FutureOr<DeviceLogReader> getLogReader({
  ApplicationPackage? app,
  bool includePastLogs = false,
})
```

```dart
// Global device logs
final globalReader = await device.getLogReader();

// App-specific logs
final appReader = await device.getLogReader(app: myApp);
```

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

### Verify Device Architecture

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/configuration.md

Check the architecture of the target device by logging in via SSH and running the 'uname -m' command. This helps diagnose 'Wrong Architecture Selected' issues.

```bash
ssh pi@<hostname> uname -m
```

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

### Get Generic Variant of Platform

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/platforms-and-architectures.md

Retrieves the generic (non-tuned) variant of a FlutterpiTargetPlatform. If the platform is already generic, it returns itself. Non-generic platforms are automatically converted to their generic variants for debug builds.

```dart
final pi4Platform = FlutterpiTargetPlatform.pi4;
final generic = pi4Platform.genericVariant;
// Returns FlutterpiTargetPlatform.genericArmV7

final alreadyGeneric = FlutterpiTargetPlatform.genericArmV7;
// .genericVariant returns itself
```

```dart
if (buildMode == BuildMode.debug && !targetPlatform.isGeneric) {
  targetPlatform = targetPlatform.genericVariant;
}
```

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

### Flutterpi Tool Command Structure

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/overview.md

This tree structure outlines the available commands and their subcommands within the flutterpi_tool. Use these commands to manage builds, run applications, and handle devices.

```bash
flutterpi_tool
├── build           # Build flutter-pi asset bundles
├── run             # Run app on connected device
├── devices         # Manage devices
│   ├── add         # Add new device
│   ├── remove      # Remove device
│   └── list        # List connected devices
├── precache        # Download and cache artifacts
└── test            # Run tests
```

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

### Get Flutterpi Target Platform

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/execution-and-logging.md

Lazily determines the target platform's architecture using `uname -m`. This property runs on first access, caches the result, and may throw an SshException if SSH communication fails.

```dart
late final Future<FlutterpiTargetPlatform> flutterpiTargetPlatform
```

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

### Verify Build Target Architecture

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/configuration.md

Explicitly set the build architecture using the --arch flag and enable verbose output to help diagnose 'Wrong Architecture Selected' issues.

```bash
flutterpi_tool build --arch arm64 --verbose
```

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

### Build System

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/SUMMARY.txt

Details regarding the application building process, including how Flutter applications are compiled and assets are bundled for deployment.

```APIDOC
## Build System

This section outlines the build system integration within flutterpi_tool, explaining how Flutter applications are compiled and prepared for deployment on target devices.

### Process

The build process involves:
1.  **Compilation**: Compiling the Dart code into a native executable.
2.  **Asset Bundling**: Packaging all necessary assets (images, fonts, etc.) required by the application.
3.  **Platform Specifics**: Applying any necessary platform-specific configurations or optimizations.

### Commands

The primary command for initiating the build process is `flutterpi_tool build`.

#### Example: Building a Release Version

```bash
flutterpi_tool build --release --output-dir ./build
```

### Artifacts

The build system utilizes artifact types and caching strategies to optimize build times and manage dependencies. Refer to the 'Artifacts' section for more details.
```

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

### Troubleshoot Device Not Found

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/INDEX.md

Provides commands to re-add and list devices when a device is not found by the tool.

```bash
flutterpi_tool devices add pi@<hostname>
```

```bash
flutterpi_tool devices list
```

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

### List Devices Programmatically

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/configuration.md

Retrieve a list of all configured devices programmatically using the `getDevices` method.

```dart
final devices = config.getDevices();
```

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

### FlutterPI Tool Source Directory Structure

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/exported-api-summary.md

Overview of the `lib/src/` module tree, providing a reference for contributors to understand the organization of the tool's internal components.

```tree
lib/src/
├── executable.dart           # CLI entry point
├── config.dart              # Device configuration
├── context.dart             # Application setup
├── cache.dart               # Artifact caching
├── artifacts.dart           # Artifact types
├── common.dart              # Platform types
├── github.dart              # GitHub API
├── more_os_utils.dart       # OS utilities
├── cli/                     # Command structure
├── devices/                 # Device management
├── build_system/            # Building
└── archive/                 # Decompression
```

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

### Build for CPU-Tuned Platforms (Raspberry Pi)

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/README.md

Build your Flutter application with optimizations specific to Raspberry Pi models. This ensures better performance on the target hardware.

```bash
# CPU-tuned platforms (Raspberry Pi)
flutterpi_tool build --arch arm64 --cpu pi4    # Pi 4 optimized
flutterpi_tool build --arch arm --cpu pi3      # Pi 3 optimized
```

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

### Configure Executable in pubspec.yaml

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/exported-api-summary.md

This YAML snippet shows how to register the tool as an executable in the `pubspec.yaml` file, allowing it to be invoked from the command line.

```yaml
executables:
  flutterpi_tool: flutterpi_tool
```

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

### Standard Asset Bundle Structure

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/build-system.md

Illustrates the default directory structure for an asset bundle, including compiled code, engine libraries, and packaged assets.

```text
{app_id}/
├── lib/
│   ├── libapp.so                    # Compiled Dart code
│   ├── libflutter_engine.so         # Flutter engine
│   └── ... (other native libraries)
├── app/
│   ├── kernel_blob.bin              # Dart kernel (debug only)
│   ├── isolate_snapshot_data        # VM data (profile/release)
│   └── isolate_snapshot_instr       # VM instructions (profile/release)
├── assets/
│   └── ... (image, font, data files)
├── data/
│   └── flutter_assets/              # Packaged assets
└── icudtl.dat                       # ICU data for text rendering

```

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

### FlutterpiSshDevice Constructor

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/devices.md

Initializes a new instance of the FlutterpiSshDevice class.

```APIDOC
## FlutterpiSshDevice Constructor

### Description
Initializes a new instance of the FlutterpiSshDevice class.

### Parameters
- **id** (String) - Required - Unique device identifier
- **name** (String) - Required - Human-readable device name
- **sshUtils** (SshUtils) - Required - SSH communication wrapper
- **remoteInstallPath** (String?) - Optional - Directory for app installation; defaults to `/tmp/`
- **logger** (Logger) - Required - Logger instance for diagnostic output
- **os** (MoreOperatingSystemUtils) - Required - Operating system utilities
- **args** (FlutterpiArgs) - Optional - Display configuration and runtime parameters
```

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

### Build for Meta-flutter target

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/api-reference/commands.md

Builds a Flutter app using the `meta-flutter` filesystem layout.

```bash
# Meta-flutter target
flutterpi_tool build --release --fs-layout meta-flutter
```

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

### Precache Artifacts

Source: https://github.com/ardera/flutterpi_tool/blob/main/_autodocs/INDEX.md

Downloads necessary build artifacts to the local machine for faster subsequent builds.

```bash
flutterpi_tool precache
```