# flutter-watcher

**Repository Path**: nur/flutter-watcher

## Basic Information

- **Project Name**: flutter-watcher
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-18
- **Last Updated**: 2026-07-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# flutter-watcher

`flutter-watcher` is a small Rust CLI that runs a Flutter app without a PTY,
prints readable real-time logs, watches project files, and triggers hot reload
through Flutter's `--pid-file` signal support.

It currently targets Unix-like systems only. Windows support is intentionally
out of scope for this first implementation.

## Usage

```bash
cargo run -- --project-dir /path/to/flutter/app -- -d chrome
```

Arguments after `--` are passed to `flutter run`.

Common options:

```bash
flutter-watcher --help
flutter-watcher --project-dir . -- --flavor dev
flutter-watcher --fvm -- --dart-define=API_BASE_URL=http://localhost:8080
flutter-watcher --no-color --raw-log .flutter-watcher/latest.log
```

## Live Log Search and Filtering

The tool reads its own stdin for line-based search commands while Flutter runs.
This keeps Flutter itself outside a PTY.

```text
/text          Search forward through recent logs
?text          Search backward through recent logs
n              Jump to the next match
N              Jump to the previous match
:filter text   Show only new logs matching text
:filter        Clear the live log filter
:errors        Print collected error source locations
:search-help   Print search and filter commands
```

The default search history keeps the latest 8000 log lines. Use
`--history-lines <N>` to tune it.

Filtering only changes what is printed to the terminal after the filter is set.
Raw logs and search history keep all Flutter output.

Terminal output uses semantic colors for API request/response markers, URLs,
HTTP methods, status codes, auth/token logs, warnings, errors, and source
locations. JSON bodies printed after `API Log:` or `Response Text:` are expanded
with indentation for readability. Raw logs and search/filter matching still use
the original single-line text.

## What It Does

- Starts `flutter run --pid-file .flutter-watcher/flutter.pid`.
- Reads `stdout` and `stderr` in real time.
- Adds stable log prefixes, levels, semantic colors, source-location
  highlighting, and readable JSON expansion in terminal output.
- Writes plain raw logs to `.flutter-watcher/latest.log`.
- Watches common Flutter paths such as `lib`, `assets`, `pubspec.yaml`,
  `test`, and `integration_test`.
- Debounces file changes and runs `kill -USR1 <pid>` to trigger hot reload.

## Notes

This tool avoids PTY emulation. That keeps the process model simple, but it also
means interactive Flutter keyboard commands such as `r`, `R`, and `q` are not
used. Hot reload is handled through the pid-file signal path instead.