Crate waterui_cli

Expand description

§waterui-cli

Cross-platform build orchestration and development tooling for WaterUI applications.

§Overview

waterui-cli is the command-line interface that powers the water binary, the primary tool for building, running, and managing WaterUI applications across iOS, macOS, and Android. It abstracts platform-specific build systems (Xcode for Apple, Gradle for Android) and provides a unified developer experience with device management, project scaffolding, and instant view previews.

The crate is split into two components:

Library (src/lib.rs): Core abstractions for platforms, devices, builds, and project management
Terminal (src/terminal/): User-facing CLI with argument parsing and formatted output

This separation ensures all business logic lives in the library, while the terminal layer handles only user interaction.

§Installation

Install the CLI from a clone of this repository:

cargo install --path .

Or build for development (not added to PATH):

cargo build

§Quick Start

Create a new WaterUI project and run it on iOS Simulator:

# Create a new project
water create my-app --backends apple,android

# Run on iOS Simulator
cd my-app
water run --platform ios

# Run on Android
water run --platform android

Create a playground for quick experimentation (auto-managed backends):

water create my-experiment --mode playground
cd my-experiment
water run --platform ios

§Preview Views

Preview individual view functions without running the full app:

# Preview a view function and save as PNG
water preview my_view --platform macos --path ./app --output preview.png

# With custom frame size
water preview dashboard --platform macos --frame 800x600 --output dashboard.png

§Drive the App over MCP

Serve the app to an agent over MCP — the accessibility tree, actions, and screenshots become tools:

# In the project root (or pass --path)
water mcp

# Custom viewport and scale factor
water mcp --viewport 800x600 --scale 1.0

water create writes a .mcp.json that registers the server for MCP clients launched in the project root. The CLI fronts the generated app process, so initialize and tools/list answer immediately even while a cold build is still compiling; restart rebuilds from the current sources. The preview tool renders a #[preview] function or expr expression and returns the PNG image content directly — the same render water preview produces, without a shell round trip.

Mark functions with #[preview] to make them previewable:

use waterui::prelude::*;

#[preview]
fn my_card() -> impl View {
    vstack((
        text!("Hello Preview!"),
        text!("This renders instantly"),
    ))
    .padding()
    .background(Color::srgb(100, 150, 200))
}

The preview system generates symbols with the format waterui_preview_{crate_name}_{fn_name} to avoid conflicts between crates.

§Core Concepts

§Platform Abstraction

A build target is a TargetPlatform — an enum of the concrete targets (MacOS, IOS, IOSSimulator, TvOS, Android, …) paired with a TargetBackend naming which backend renders it (Apple, Android, Gtk4, Hydrolysis, …). It replaced an earlier Platform trait: the set of targets is fixed and known, so an enum says so, and the per-target work — scanning for devices, building for the triple, packaging into a .app or .apk, cleaning — lives in the module for that platform rather than behind an associated type.

pub enum TargetPlatform {
    MacOS,
    IOS,
    IOSSimulator,
    TvOS,
    TvOSSimulator,
    Android,
    // …
}

§Device Management

The Device trait represents something that can run an app (simulator, emulator, or physical device). Each device has a two-phase lifecycle:

Launch: Boot the emulator/simulator (no-op for physical devices)
Run: Install and execute the artifact, returning a Running stream

Example from src/workflows/device.rs:

pub trait Device: Sized + Send {
    fn name(&self) -> &str;

    fn launch(&self) -> impl Future<Output = eyre::Result<()>> + Send;
    fn run(&self, artifact: Artifact, options: RunOptions) -> impl Future<Output = Result<Running, FailToRun>> + Send;
    fn platform(&self) -> Self::Platform;
}

Implementations: AppleSimulator, MacOS, AndroidDevice, AndroidEmulator

§Project Management

The Project type manages the Water.toml manifest and coordinates builds across platforms. Key methods:

Project::open(): Open existing project
Project::create(): Scaffold new project
Project::run(): Build, package, and run on a device

§Rust Build

The RustBuild type wraps cargo build with platform-specific configuration:

Target triple selection (e.g., aarch64-apple-ios-sim)
Simulator-specific clang args for bindgen
Optional sccache integration for faster builds

§Toolchain Management

The Toolchain trait checks for required dependencies and provides installation plans:

pub trait Toolchain: Send + Sync {
    type Installation: Installation;
    fn check(&self) -> impl Future<Output = Result<(), ToolchainError<Self::Installation>>> + Send;
}

pub trait Installation: Send + Sync {
    type Error: Into<eyre::Report> + Send;
    fn install(&self) -> impl Future<Output = Result<(), Self::Error>> + Send;
}

Example: AppleToolchain checks for Xcode, simulators, and rust targets. AndroidToolchain checks for Android SDK, NDK, and JDK.

§Examples

§Run with Device Logs

water run --platform ios --logs debug

This streams device logs at debug level or above to the terminal.

§Run on Specific Device

# List available devices
water devices --platform ios

# Run on specific device by ID
water run --platform ios --device "iPhone 15 Pro"

§Create Project with Local `WaterUI` Development

water create my-app --waterui-path /path/to/waterui --backends apple,android

This creates a project that uses the local WaterUI repository.

§Build Without Running

water build --platform ios --release

§Clean Build Artifacts

water clean --platform ios
water clean --all  # Clean all platforms

§Check Development Environment

water doctor --platform ios
water doctor --platform android

This validates toolchain dependencies (Xcode, Android SDK, Rust targets).

§API Overview

§Library (`src/lib.rs`)

platform: Platform trait and implementations (Apple, Android)
device: Device trait, device types, run options, and events
project: Project management, manifest parsing, create/open
build: Rust build orchestration with cargo
debug: Crash handling and diagnostics
toolchain: Toolchain checking and installation
backend: Backend configuration and scaffolding
templates: Project scaffolding templates
apple: Apple platform, devices, and backend
android: Android platform, devices, and backend
brew: Homebrew package management utilities
water_dir: Global WaterUI directory management
utils: Command execution helpers

§Terminal (`src/terminal/`)

main.rs: CLI entry point, argument parsing
shell.rs: Output formatting, spinners, colors
commands/create.rs: Project scaffolding command
commands/run.rs: Build and run command
commands/build.rs: Build-only command
commands/package.rs: Packaging command
commands/clean.rs: Cleanup command
commands/doctor.rs: Toolchain validation command
commands/devices.rs: Device listing command
commands/mcp.rs: MCP server command (drives the app headless for agents)

§Features

The CLI supports:

Multi-platform: iOS, macOS, Android with unified workflow
Instant previews: Render individual views to PNG without running the full app
Device management: Automatic device discovery and simulator launching
Interactive creation: Guided project setup with prompts
Playground mode: Auto-managed backends for quick prototyping
Parallel builds: Device launch overlaps with compilation
Log streaming: Real-time device logs with level filtering
JSON output: Machine-readable output with --json flag
Graceful cancellation: Ctrl+C cleanup without errors WaterUI CLI library for managing cross-platform builds and development workflows.

Modules§

android: Android platform support.
apple: Apple platform support.
artifact_symbols: Symbols embedded in compiled Rust artifacts.
backend: Backend configuration and initialization for WaterUI projects.
bench: water bench engine.
brew: Brew toolchain manager for WaterUI CLI
build: Build system
build_info: Build-time metadata embedded into the water CLI binary.
capture: Screen capture utilities for devices.
debug: Debugging utilities for WaterUI CLI.
device: Device management and application running utilities for WaterUI CLI.
diff: Image comparison and diff generation for visual testing.
esp32: ESP32 (Dew) backend support for WaterUI CLI.
framework: Framework channel resolution and persisted dependency selection.
gesture: Unified gesture API for device automation.
gtk4: GTK4 backend support for WaterUI CLI.
hydrolysis: Hydrolysis backend support for WaterUI CLI.
inspector: Inspector app launcher and lifecycle utilities.
macos_bundle: Helpers for packaging native binaries into macOS .app bundles.
mcp: water mcp: serves an MCP session that drives the app headless.
platform: Platform abstraction for WaterUI CLI.
preview: Preview system for rendering and capturing WaterUI views.
project: Project management and build utilities for WaterUI CLI.
project_types: Newtypes and enums describing a project’s identity, platforms, and targets.
toolchain: Toolchain management for WaterUI CLI
toolchain_checks: Shared toolchain checks for the terminal commands and the water mcp preview tool.
tui: Experimental terminal (TUI) backend support.
utils: Utility functions for the CLI.
water_dir: Management of the global Water home and per-project managed backend build cache.
web: Web-frontend toolchain plumbing.