flutter-run-tui

KO | EN

gitlite — search

#animation #agent #react-native #kotlin #windows #terminal #c #python #list #editor

flutter-run-tui

(★ 9)

Terminal UI for Flutter run, in Rust + ratatui. Replaces a zsh/python frun script.

파일 탐색기

ZIP 다운로드

- - 01-picker.png
  - 02-building.png
  - 03-running.png
  - 04-build-failed.png
  - 05-switch.png
- flutter-trim.png
- flutter.png
- - build.rs
  - chrome.rs
  - devices.rs
  - logo.rs
  - logs.rs
  - mod.rs
  - project.rs
  - target.rs
  - theme_picker.rs
- budget.rs
- data.rs
- dump.rs
- flutter.rs
- main.rs
- probe.rs
- theme.rs
- watcher.rs
- widgets.rs
- toolchain.rs
.gitignore
Cargo.lock
Cargo.toml
DESIGN.md
LICENSE
README.md

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

*A fast terminal UI for `flutter run` — instant device picker, live build stages, and clean app logs.*

![Rust](https://img.shields.io/badge/Rust-2021-000000?logo=rust&style=flat-square)
  ![ratatui](https://img.shields.io/badge/ratatui-0.30.2-38bdf8?style=flat-square)
  ![Platform](https://img.shields.io/badge/platform-macOS-71717a?style=flat-square)
  ![Flutter](https://img.shields.io/badge/Flutter-FVM%20or%20plain%20SDK-02569B?logo=flutter&style=flat-square)

[Features](#features) • [Requirements](#requirements) • [Install](#install) • [Usage](#usage) • [Keyboard](#keyboard) • [Development](#development)
</div>

`flutter run` outputs a noisy, scrolling wall of text where device selection, build stages, timing metrics, and application logs fight for the same lines. **frun** organizes everything into clean, dedicated cards: a project status card, target device details, a real-time build stage tracker, and an interactive log viewer — while proxying Flutter through a pty so all interactive shortcuts remain fully functional.

<div align="center">
  <img src="assets/screens/03-running.png" alt="frun during a live run" width="760">
  <br>
  <sub>Live run on iOS Simulator: project card, device card, build timings, and streaming app logs.</sub>
</div>

## Features

- **⚡ Fast Device Picker (<200ms):** Queries `adb`, `emulator`, and `simctl` directly to display running and bootable targets instantly, rather than waiting 6–9s on `flutter devices`.
- **🚀 Boot on Enter:** Select any shut-down simulator or AVD and press `Enter` to boot it and start the build automatically.
- **⏱️ Honest Build Timings:** Separate tracking for toolchain startup time (Dart VM & `flutter_tools`) and actual compilation time (Gradle/Xcode).
- **🔄 Smart Device Switching (`^D`):** Switch targets mid-session without exiting. Press `⇧Enter` to launch another device in a separate Ghostty or tmux tab.
- **🎨 10 Curated Themes (`t`):** Instant floating modal with real-time live preview, 10 curated dark palettes (Color Hunt & developer favorites), smart text contrast, and persistent settings across sessions.
- **🧱 Seamless 0-Gap Dashboard:** Compact, modular card layout with 0 outer spacing, 7-row ProjectCard with balanced spacing, and optimal vertical log space.
- **💊 Rounded Border-Radius Badges:** Status pills (` Running`, `last used`) and log tags (`WRN`, `ERR`, `INF`) feature curved Powerline caps matching card rounded corners with snug padding.
- **🔤 Uniform Bold Typography:** Crisp, balanced font weights across all metadata fields and values with slate gray label accents for high legibility without glare.
- **🔥 Built-in Auto-Reload:** Automatically watches `lib/` for `.dart` file changes with a 100ms debounce — UI updates instantly on save without editor plugins.
- **📜 Ergonomic Log Window:** 15-column aligned gutter, word-wrapped logs, keyboard/mouse scrolling (`j`/`k`, arrows, wheel), fullscreen log toggle (`e`), and transcript replay into your terminal history on exit.
- **🎯 Full Interactive Forwarding:** Hot reload (`r`), hot restart (`R`), and all native Flutter shortcuts (`h`, `c`, `p`, `o`, `w`, `d`) pass through directly.

## Requirements

> [!NOTE]
> Tested primarily on macOS. Android emulation and tmux multi-tab workflows are cross-platform.

## Install

### Option 1: Via Homebrew (Recommended for macOS)
```bash
brew tap okasutarto/frun
brew install frun
```

---

### Option 2: Via Cargo (Rust)
> [!NOTE]
> Requires the Rust toolchain (`cargo`). If not installed yet: `brew install rust` or `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`.

```bash
cargo install --git https://github.com/okasutarto/flutter-run-tui.git
```
*Installs the `frun` binary directly to `~/.cargo/bin/frun`.*

---

<details>
<summary><b>Option 3: Build from source (Manual)</b></summary>

```bash
git clone https://github.com/okasutarto/flutter-run-tui.git ~/.config/zsh/flutter-run-tui
cd ~/.config/zsh/flutter-run-tui
cargo build --release
ln -s "$PWD/target/release/frun" ~/.local/bin/frun
```

**Optional zsh function:**
```zsh
# ~/.zshrc
frun() {
  local bin="$HOME/.config/zsh/flutter-run-tui/target/release/frun"
  [[ -x $bin ]] || { print -u2 "frun: not built yet (run cargo build --release)"; return 127 }
  "$bin" "$@"
}
```
</details>

## Usage

Run `frun` in any Flutter project containing a `pubspec.yaml`. All command-line arguments are forwarded to `flutter run`:

```bash
frun                                    # Pick device, build, and run
frun --flavor staging                   # Forward flavor flag
frun --dart-define=API=http://localhost # Forward dart-defines
```

### Device Status Badges

In the device picker (`SELECT DEVICE`) and switcher (`SWITCH DEVICE` via `^D`), `frun` displays the real-time state and relationship of each target:

> [!TIP]
> Devices are automatically ranked at the top of the list by status: **`running` → `in use` → `last used` → `active`**.

### Exit Codes

| Code | Meaning |
| ---: | :--- |
| `0` | Normal exit or graceful quit (`q` / `^S`) |
| `1` | Fatal error (missing `pubspec.yaml`, boot failure, discovery error) |
| `130` | Device selection cancelled with `Esc` |
| *Flutter's* | Direct exit code from Flutter build failure |

## Keyboard Shortcuts

The footer cheatsheet automatically adapts to the current state.

## 🎨 Themes & Customization

Press **`t`** from any screen to open the **Theme Switcher** modal with instant real-time preview:

- **Real-Time Live Preview**: Navigate with `↑`/`↓` or `j`/`k` to instantly test colors across the active TUI.
- **Rollback on Cancel**: Press `Esc` or `q` to immediately restore your previous theme.
- **Persistent Storage**: Chosen theme is automatically remembered across sessions in `~/.config/zsh/.frun-theme`.
- **Smart Text Contrast**: Badges dynamically compute luminance to maintain sharp text legibility on all backgrounds.

## Toolchain & Configuration

### SDK Detection
`frun` automatically detects your Flutter SDK without manual configuration:
1. `FRUN_FLUTTER` environment variable (if set)
2. Project-level `.fvmrc` or `.fvm/` directory with `fvm` on `PATH`
3. Global `flutter` on `PATH`

Custom runners can be supplied via `FRUN_FLUTTER`:
```bash
FRUN_FLUTTER='mise exec flutter --' frun
FRUN_FLUTTER=puro frun
```

### Environment Variables

## Development & Testing

```bash
cargo build --release
cargo test --release            # 85 unit tests, 6 integration tests
cargo clippy --all-targets
```

### Diagnostic Flags
`frun` includes headless diagnostic and testing flags:

## Architecture & Further Reading

For deep implementation details, layout budget rules, parser nuances, and design rationale:
- Read [`DESIGN.md`](DESIGN.md) — complete specification and architectural guide.

flutter-run-tui

파일 탐색기

# CDN으로 사용하기

Was this content helpful?

Recent Feedback

Download README