AlphaWaveSystems · pbertsch · Apr 2, 2026 · Apr 2, 2026 · Apr 2, 2026
@@ -59,7 +59,16 @@ The **ProbeAgent** is a Dart package you add to your Flutter app as a dev depend
 
 ## Installation
 
-### Option A — Download pre-built binary (recommended for CI/CD)
+### Option A — Homebrew (macOS + Linux, recommended)
+
+```bash
+brew tap AlphaWaveSystems/tap
+brew install probe
+```
+
+Upgrades are handled automatically with `brew upgrade probe`.
+
+### Option B — Download pre-built binary (recommended for CI/CD)
 
 Pre-built binaries for Linux, macOS (Intel + Apple Silicon), and Windows are attached to every [GitHub Release](https://github.com/AlphaWaveSystems/flutter-probe/releases).
 
@@ -77,7 +86,7 @@ curl -Lo probe https://github.com/AlphaWaveSystems/flutter-probe/releases/latest
 chmod +x probe && sudo mv probe /usr/local/bin/
 ```
 
-### Option B — Build from source
+### Option C — Build from source
 
 ```bash
 git clone https://github.com/AlphaWaveSystems/flutter-probe.git

@@ -26,10 +26,14 @@ Both are required. The agent alone does nothing without the CLI to drive it.
 The `probe` CLI is a Go binary. Install via one of:
 
 ```bash
-# Option A: Go install
+# Option A: Homebrew (macOS + Linux)
+brew tap AlphaWaveSystems/tap
+brew install probe
+
+# Option B: Go install
 go install github.com/AlphaWaveSystems/flutter-probe/cmd/probe@latest
 
-# Option B: Download from GitHub Releases
+# Option C: Download from GitHub Releases
 # https://github.com/AlphaWaveSystems/flutter-probe/releases/latest
 ```
 

@@ -35,16 +35,20 @@ Three primary options exist for Flutter E2E testing:
 Install the FlutterProbe CLI:
 
 ```bash
-curl -sSL https://flutterprobe.dev/install | sh
+# macOS + Linux (recommended)
+brew tap AlphaWaveSystems/tap
+brew install probe
+
+# Or via go install (good for CI)
+go install github.com/AlphaWaveSystems/flutter-probe/cmd/probe@latest
 ```
 
 Add the FlutterProbe Dart agent to your app's dev dependencies:
 
 ```yaml
 # pubspec.yaml
 dev_dependencies:
-  flutter_probe_agent:
-    ^0.5.1
+  flutter_probe_agent: ^0.5.3
 ```
 
 Initialize the agent in your app's main function:
@@ -192,7 +196,7 @@ The `wait for` command polls the widget tree until the condition is met or the t
 Configure FlutterProbe to take screenshots and capture device logs on test failure. This transforms CI failures from "test X failed" into actionable reports with visual context:
 
 ```bash
-flutterprobe run --suite tests/ --screenshot-on-failure --capture-logs
+probe test tests/ --screenshot-on-failure --capture-logs
 ```
 
 ## Common Pitfalls

@@ -51,12 +51,11 @@ jobs:
         with:
           flutter-version: '3.27.0'
       - name: Install FlutterProbe
-        run: |
-          curl -sSL https://flutterprobe.dev/install | sh
+        run: go install github.com/AlphaWaveSystems/flutter-probe/cmd/probe@latest
       - name: Build and test
         run: |
-          flutter build apk --debug
-          flutterprobe run --target android --suite tests/
+          flutter build apk --debug --dart-define=PROBE_AGENT=true
+          probe test tests/ -y
 ```
 
 The key steps are: check out the code, set up Flutter, install FlutterProbe, build the app, and run the test suite. For iOS, replace the build step with `flutter build ios --simulator --debug` and adjust the target flag.
@@ -73,10 +72,10 @@ FlutterProbe supports parallel execution via the `--shard` flag:
 
 ```bash
 # Split the suite across 4 parallel shards
-flutterprobe run --suite tests/ --shard 1/4 &
-flutterprobe run --suite tests/ --shard 2/4 &
-flutterprobe run --suite tests/ --shard 3/4 &
-flutterprobe run --suite tests/ --shard 4/4 &
+probe test tests/ --shard 1/4 &
+probe test tests/ --shard 2/4 &
+probe test tests/ --shard 3/4 &
+probe test tests/ --shard 4/4 &
 wait
 ```
 
@@ -89,7 +88,7 @@ jobs:
       matrix:
         shard: [1/4, 2/4, 3/4, 4/4]
     steps:
-      - run: flutterprobe run --suite tests/ --shard ${{ matrix.shard }}
+      - run: probe test tests/ --shard ${{ matrix.shard }}
 ```
 
 Four shards typically reduce a 12-minute suite to roughly 3 minutes of wall-clock time. The speedup is linear because E2E tests are independent by design — each test starts from a known app state.
@@ -137,7 +136,7 @@ Automated tests are only useful if failures are actionable. FlutterProbe generat
 Reports can be output as JUnit XML for CI integration or as HTML for human review. JUnit XML integrates directly with GitHub Actions, GitLab CI, and most CI dashboards to surface test results in pull request checks.
 
 ```bash
-flutterprobe run --suite tests/ --report junit --output results.xml
+probe test tests/ --report junit --output results.xml
 ```
 
 When a test fails in CI, the combination of the failure screenshot, the step-level log, and the device log usually provides enough context to diagnose the issue without reproducing it locally.

@@ -1,47 +1,59 @@
 ---
 title: Installation
-description: Build FlutterProbe from source and integrate the Dart agent into your Flutter app.
+description: Install the probe CLI and integrate the Dart agent into your Flutter app.
 ---
 
-## Prerequisites
+## Step 1: Install the CLI
+
+### Option A — Homebrew (macOS + Linux, recommended)
+
+```bash
+brew tap AlphaWaveSystems/tap
+brew install probe
+```
+
+### Option B — Pre-built binary (all platforms, good for CI)
 
-- **Go 1.26+** — for building the probe CLI
-- **Dart 3.3+ / Flutter 3.19+** — for the probe_agent package (tested up to Flutter 3.41 / Dart 3.11)
-- **Android**: ADB + Android SDK (for Android emulator testing)
-- **iOS Simulator**: Xcode + `xcrun simctl` (for iOS simulator testing)
-- **iOS Physical Device**: All of the above, plus `iproxy` from `libimobiledevice` for USB port forwarding (`brew install libimobiledevice`)
+Download the binary for your platform from [GitHub Releases](https://github.com/AlphaWaveSystems/flutter-probe/releases/latest):
 
-## Build the CLI
+| Platform | Binary |
+|---|---|
+| macOS (Apple Silicon) | `probe-darwin-arm64` |
+| macOS (Intel) | `probe-darwin-amd64` |
+| Linux (x86-64) | `probe-linux-amd64` |
+| Windows (x86-64) | `probe-windows-amd64.exe` |
 
-Clone the repository and build the `probe` binary:
+Make the binary executable and place it on your `PATH`:
 
 ```bash
-git clone https://github.com/AlphaWaveSystems/flutter-probe.git
-cd FlutterProbe
-make build          # outputs bin/probe
+chmod +x probe-darwin-arm64
+mv probe-darwin-arm64 /usr/local/bin/probe
 ```
 
-To install to your `$GOPATH/bin` (so `probe` is available globally):
+### Option C — `go install` (requires Go 1.26+)
 
 ```bash
-make install
+go install github.com/AlphaWaveSystems/flutter-probe/cmd/probe@latest
 ```
 
-## Add ProbeAgent to Your Flutter App
+This is a good option for CI environments that already have Go set up.
 
-The Dart agent runs inside your Flutter app and provides the WebSocket server that the CLI connects to.
+Verify:
+
+```bash
+probe version
+```
 
-### 1. Add the dependency
+## Step 2: Add the Agent to Your App
 
-In your Flutter app's `pubspec.yaml`:
+Add `flutter_probe_agent` to your Flutter app's `pubspec.yaml`:
 
 ```yaml
 dev_dependencies:
-  flutter_probe_agent:
-    path: /path/to/FlutterProbe/probe_agent
+  flutter_probe_agent: ^0.5.3
 ```
 
-### 2. Initialize in main.dart
+Initialize in your `main.dart`:
 
 ```dart
 import 'package:flutter_probe_agent/flutter_probe_agent.dart';
@@ -58,16 +70,16 @@ Future<void> main() async {
 }
 ```
 
-The `PROBE_AGENT` flag is compiled into the binary via `--dart-define`. It must be set at build time — it cannot be toggled at runtime.
+The `bool.fromEnvironment` check ensures the agent is only active when built with `--dart-define=PROBE_AGENT=true`. It adds zero overhead to your production app.
 
-### 3. Build with the flag enabled
+## Step 3: Build and Run
 
 **iOS Simulator:**
 
 ```bash
-flutter build ios --debug --simulator --dart-define=PROBE_AGENT=true
-xcrun simctl install <UDID> build/ios/iphonesimulator/YourApp.app
-xcrun simctl launch <UDID> com.example.myapp
+flutter run --dart-define=PROBE_AGENT=true
+# In another terminal:
+probe test tests/login.probe --device <your-device> -v
 ```
 
 **Android Emulator:**
@@ -76,6 +88,17 @@ xcrun simctl launch <UDID> com.example.myapp
 flutter build apk --debug --dart-define=PROBE_AGENT=true
 adb install -r build/app/outputs/flutter-apk/app-debug.apk
 adb shell am start -n com.example.myapp/.MainActivity
+probe test tests/login.probe --device emulator-5554 -v
+```
+
+**Physical iOS (WiFi mode — recommended):**
+
+```bash
+flutter build ios --profile --dart-define=PROBE_AGENT=true --dart-define=PROBE_WIFI=true
+xcrun devicectl device install app --device <UDID> build/ios/iphoneos/Runner.app
+xcrun devicectl device process launch --device <UDID> <bundle-id>
+# Find PROBE_TOKEN in app console, then:
+probe test tests/ --host <device-ip> --token <probe-token> -v
 ```
 
 ## Initialize Your Project
@@ -90,12 +113,18 @@ This creates:
 - `probe.yaml` — project configuration
 - `tests/` — directory for `.probe` test files with samples
 
-## Build the Test Converter (Optional)
+## Prerequisites
 
-If you want to migrate tests from other frameworks:
+| Requirement | When needed |
+|---|---|
+| Dart 3.3+ / Flutter 3.19+ | Always (for the agent) |
+| Android SDK + ADB | Android emulator/device testing |
+| Xcode + `xcrun simctl` | iOS simulator testing |
+| `libimobiledevice` (`brew install libimobiledevice`) | Physical iOS device testing via USB |
 
-```bash
-make build-convert    # outputs bin/probe-convert
-```
+## Next Steps
 
-See [probe-convert](/tools/probe-convert/) for details.
+- [Write your first test](/probescript/syntax/)
+- [ProbeScript Dictionary](/probescript/dictionary/) — all commands and modifiers
+- [iOS Integration Guide](/platform/ios/) — physical device setup
+- [CI/CD with GitHub Actions](/ci-cd/github-actions/)