Flutter Runner CLI

CLI interaktif untuk menjalankan Flutter app — pilih environment (Local/Dev/Prod), pilih device, lalu auto-run dengan --dart-define yang sesuai.

Zero external dependencies — hanya pakai dart:io dan dart:convert.

Fitur

• 🎯 Pilih Environment — Local (auto-detect IP), Dev, atau Production
• 📱 Pilih Device — Deteksi otomatis device dari flutter devices
• ⚡ Auto Run — flutter run dengan --dart-define yang sesuai
• 🔧 Config Wizard — --init buat bikin .flutter_runner.json
• 🏢 Multi-project — Bisa dipake di project Flutter mana aja
• 📦 Zero dependencies — Ringan, gak perlu install library tambahan

Install

# Aktifkan global
dart pub global activate flutter_runner_cli

# Jalankan dari mana aja
flutter-runner

Atau tanpa install:

dart run flutter_runner_cli

Usage

flutter-runner            # Menu interaktif (pilih env → pilih device → run)
flutter-runner --init     # Buat/configurasi .flutter_runner.json
flutter-runner --help     # Bantuan

Alur Interaktif

Step 1 — Pilih Environment:

╔══════════════════════════════════════════╗
║          Pilih Environment               ║
╚══════════════════════════════════════════╝

  1)  🏠  Local
      IP otomatis :8000

  2)  🔧  Dev
      https://staging.example.com

  3)  🌐  Production
      https://api.example.com

Step 2 — Pilih Device:

╔══════════════════════════════════════════╗
║          Pilih Device                    ║
╚══════════════════════════════════════════╝

  1) iPhone 17 Pro (65F7E385-...)
  2) Pixel 7 (emulator-5554)

Step 3 — Auto Run:

$ flutter run -d <device> --dart-define=BASE_URL=<url> ...

Config

Bikin file .flutter_runner.json di root project:

flutter-runner --init

Atau buat manual:

{
  "local_port": "8000",
  "dev_url": "https://staging.example.com",
  "prod_url": "https://api.example.com",
  "extra_defines": {
    "APP_NAME": "MyApp",
    "API_KEY": "abc123"
  }
}

Field Config

Field	Wajib	Deskripsi
local_port	✅	Port backend lokal (contoh: 8000)
dev_url	❌	URL backend development
prod_url	❌	URL backend production
base_url_key	❌	Nama key dart-define untuk URL (default: BASE_URL)
hostname_key	❌	Nama key dart-define untuk hostname (default: BACKEND_HOSTNAME)
extra_defines	❌	--dart-define tambahan (key-value)
run_script	❌	Path custom script pengganti flutter run

Tanpa config file: flutter-runner akan error dan nyuruh bikin config pake --init.

Dart Define (Environment Variables untuk Aplikasi)

Saat flutter run dijalankan, flutter-runner CLI mengirim --dart-define berikut:

Key	Environment	Deskripsi
BASE_URL (default)	All	Base URL backend (bisa diubah via base_url_key di config)
BACKEND_HOSTNAME (default)	Local	IP host backend (bisa diubah via hostname_key di config)
extra_defines	All	Key-value tambahan dari .flutter_runner.json → extra_defines

Key dart-define untuk URL bisa dikustomisasi. Jika project-mu menggunakan API_BASE_URL sebagai ganti BASE_URL, tambahkan "base_url_key": "API_BASE_URL" di .flutter_runner.json. Lihat Customization di bawah.

Kustomisasi Dart Define Key

Jika project Flutter-mu menggunakan nama key yang berbeda (misal API_BASE_URL), tambahkan konfigurasi di .flutter_runner.json:

{
  "local_port": "8000",
  "base_url_key": "API_BASE_URL",
  "hostname_key": "BACKEND_HOSTNAME",
  "extra_defines": {}
}

Atau biarkan default (BASE_URL) jika tidak ada kustomisasi.

Aplikasi Flutter membaca key tersebut via String.fromEnvironment('API_BASE_URL'). Lihat contoh di Integration Guide.

Custom Run Script

Jika .flutter_runner.json memiliki field run_script, CLI akan menjalankan script tersebut sebagai pengganti flutter run langsung. Script akan menerima environment variable berikut:

Variable	Deskripsi
FLUTTER_EXECUTABLE	Path ke Flutter executable (fvm atau flutter)
FLUTTER_DEVICE_ID	ID device yang dipilih user
FLUTTER_DART_DEFINES	Semua --dart-define args (space-separated)

Contoh script (scripts/run.sh):

#!/usr/bin/env bash
"$FLUTTER_EXECUTABLE" flutter run -d "$FLUTTER_DEVICE_ID" $FLUTTER_DART_DEFINES

Integration Guide

Di project Flutter, baca URL dari --dart-define sesuai key yang dikonfigurasi:

class ApiConfig {
  // Gunakan key yang sudah ditentukan di .flutter_runner.json
  // Default: 'BASE_URL', bisa dikustom ke 'API_BASE_URL' dll
  static String get baseUrl => const String.fromEnvironment(
    'BASE_URL',
    defaultValue: 'http://localhost:8080',
  );
}

Jika menggunakan base_url_key kustom, sesuaikan:

static String get baseUrl => const String.fromEnvironment(
  'API_BASE_URL',
  defaultValue: 'http://localhost:8080',
);

Environment Variables (Override Config)

Override config via environment variable:

FLUTTER_RUNNER_LOCAL_PORT=9000 flutter-runner
FLUTTER_RUNNER_DEV_URL=https://staging.example.com flutter-runner

Development

git clone https://github.com/adibagasp23/flutter_runner_cli
cd flutter_runner_cli
dart run

Testing

dart analyze   # Static analysis
dart format .  # Code formatting
dart run       # Manual testing

Publikasi

dart pub publish

Lisensi

MIT — lihat LICENSE.