AIRRELOAD / DOCUMENTATION
CLI reference
Commands, build options, and updates.
Run airreload --help for all commands, or airreload help run for build options.
Run your app
airreload runRun inside a standalone Flutter Android project. Use terminal controls after Flutter attaches.
| Option | Default | Purpose |
|---|---|---|
--project | Current directory | Flutter Android app directory |
--target, -t | lib/main.dart | Entrypoint under lib/ |
--flavor | None | Existing Android product flavor |
--dart-define | None | Repeatable compile-time definition |
--dart-define-from-file | None | Repeatable definitions file, relative to the app directory |
--flutter-version | Automatic | Exact supported Flutter version |
--host | Detected LAN IPv4 | Computer address reachable by the phone |
--wait-timeout | 0 | Seconds per pairing/connection/reconnection wait; 0 waits until stopped |
airreload run --target lib/main_dev.dart --flavor dev
airreload run --dart-define=APP_ENV=staging
airreload run --dart-define-from-file=config/staging.json
airreload run --project /path/to/app --host 192.168.1.42Use your actual computer address for --host. Quote paths containing spaces. Definitions go to both build and attach; values compiled into an APK should not contain server secrets. Restart the session when changing build options.
Airreload provides Flutter 3.47.5, 3.44.9, 3.41.9, and 3.38.10 as preview SDKs pending manual phone acceptance.
It detects FVM configuration first, then a configured VS Code SDK or Flutter on PATH. An unavailable detected version uses the closest compatible supported release; with no detected version, it picks the latest compatible release. The CLI reports its choice.
To choose an exact version with no fallback:
airreload run --flutter-version 3.38.10Your dependency constraints still apply. SDKs download on demand and are shared in the installation's sdks/ cache. Your existing Flutter and FVM configuration stay unchanged.
Check your setup
airreload doctor
airreload versiondoctor checks basic local tools and managed SDK setup. It does not fully validate Android build tools or test the phone connection. version prints your installed CLI version.
Update
Stop running sessions, then use:
airreload update --check # Check without installing
airreload update # Install the available updateAutomatic updates support installer-owned macOS Apple Silicon and Windows x64 installations, preserving SDKs and pairing data. On Windows, wait for the separate updater window to finish before running another command.
Update Airreload Go separately from its releases page.
Windows CLI versions through 0.3.0-beta.4 need the installer directly. Stop sessions first:
& ([scriptblock]::Create((Invoke-WebRequest -UseBasicParsing 'https://raw.githubusercontent.com/Airreload/installer/main/install.ps1').Content)) -Replace -PreserveData -NoPathFor source checkouts, update --check reports releases, but update will not replace the checkout. Rebuild it with git pull, dart pub get, and dart compile exe.
Linux has no native installer, so you build the CLI once from source. You need Git, your project's Android build tools, and Dart 3.13+. Check with dart --version; the Dart included with Flutter works.
1. Build the CLI in its own folder:
mkdir -p ~/airreload && cd ~/airreload
git clone https://github.com/Airreload/cli.git cli
cd cli
dart pub get
dart compile exe bin/airreload.dart -o bin/airreloadKeep the clone named cli inside ~/airreload. Airreload stores its Flutter SDKs in ~/airreload/sdks and its pairing data in ~/airreload/cli/.airreload.
2. Add airreload to your shell. This adds the CLI to PATH and sets AIRRELOAD_WORKSPACE, which a source build needs to find its SDK cache and pairing data from any directory. Pick your shell:
cat > ~/airreload/env <<'EOF'
export AIRRELOAD_WORKSPACE="$HOME/airreload"
case ":$PATH:" in
*":$HOME/airreload/cli/bin:"*) ;;
*) export PATH="$HOME/airreload/cli/bin:$PATH" ;;
esac
EOF
grep -qxF '. "$HOME/airreload/env"' ~/.bashrc || echo '. "$HOME/airreload/env"' >> ~/.bashrc
. ~/airreload/envThese commands apply to your current terminal and future ones. Running them again does not add duplicate entries.
3. Check your setup:
airreload doctorThe Cache: line should point to ~/airreload/sdks. If it shows another directory, AIRRELOAD_WORKSPACE isn't set in that shell; repeat step 2.
4. Run your app from your Flutter project:
cd /path/to/flutter-app
airreload runTo install somewhere other than ~/airreload, replace that path in every step.
Update a source installation by rebuilding it. Stop running sessions first:
cd ~/airreload/cli
git pull
dart pub get
dart compile exe bin/airreload.dart -o bin/airreloadUninstall by deleting ~/airreload and removing the . "$HOME/airreload/env" line from your shell's startup file. In Fish, run set -Ue AIRRELOAD_WORKSPACE and set -U fish_user_paths (string match -v ~/airreload/cli/bin $fish_user_paths).
On Windows, compile to bin/airreload.exe and run .\bin\airreload.exe from the cli folder.
The default location is ~/.airreload on macOS or %USERPROFILE%\.airreload on Windows. Set AIRRELOAD_INSTALL_ROOT to another absolute writable path before installing if needed. A shorter path can resolve Windows SDK cache path-limit errors.
For a custom install, PATH options, or removal, follow the installer instructions. Its uninstall scripts remove the CLI installation, cached SDKs, and state. Remove Go and project apps separately through Android settings.
These commands are for manually managed compatible integrations. Use run for the normal Go workflow; its isolated session is separate from workspace host state.
| Command | Purpose |
|---|---|
airreload host --port 9443 | Start the workspace TLS host; 9443 is the default |
airreload status | Report workspace host/app status; exit 1 if the host is offline |
airreload pair --host 192.168.1.42 | Print host pairing credentials for your LAN IPv4 address |
airreload attach --project /path/to/app | Attach to an already connected compatible app; optionally pass --target |
pair exposes sensitive credentials and is not the Go QR workflow. The app must pin the host certificate. attach requires matching source and does not install or launch the app. Non-default host ports need compatible companion support.