🚀 flutter_distribute_manager #

Build your Flutter app and hand QA a working link — in one command. Android APK + iOS IPA → uploaded to Google Drive and Diawi automatically.

No Google Cloud project. No OAuth client to register. No manual Xcode archiving. No dragging files into shared folders.

$ flutter_distribute_manager
╔══════════════════════════════════════════════╗
  flutter_distribute_manager · Build · Ship
╚══════════════════════════════════════════════╝
  Project : my_app v1.4.2

? Which platform do you want to build?
  1) Android (APK)   (default)
  2) iOS (IPA)
  3) Android + iOS

✔ Built    my_app_UAT_2026_06_19_0930_arm64-v8a.apk  (24 MB)
  [████████████████████] 100%  24 MB / 24 MB  8.1 MB/s
✔ Uploaded to Google Drive

Share links:
  Drive · my_app_UAT_2026_06_19_0930_arm64-v8a.apk
  https://drive.google.com/file/d/…

📖 Contents #

🤔 What it replaces #

Shipping a build to QA by hand is seven boring steps, every single time:

cd your_flutter_app
flutter_distribute_manager

That's the whole workflow.

🥊 Why not fastlane or Codemagic? #

They're excellent — and heavier. This tool is deliberately the small one.

Use this when you want QA builds out of your hands and into a tester's, right now, without standing up a pipeline. Use fastlane/Codemagic when you're automating store submissions, managing signing certificates across a team, or need a hosted build farm.

They compose fine, too — plenty of people use this for daily QA drops and fastlane for release day.

✅ What you'll need #

You do not need a Google Cloud project, an OAuth client ID, or a service-account key. rclone signs you in through your browser.

💻 Platform support #

📥 Install #

dart pub global activate flutter_distribute_manager

Make sure the global bin directory is on your PATH (add to ~/.zshrc or ~/.bashrc):

export PATH="$PATH":"$HOME/.pub-cache/bin"

Verify:

flutter_distribute_manager --version
flutter_distribute_manager --help

⚡ Quick start (3 steps) #

# 1️⃣  One-time setup — installs rclone, connects Google Drive, saves your Diawi token
flutter_distribute_manager init

# 2️⃣  Check everything is wired up correctly
flutter_distribute_manager doctor

# 3️⃣  From inside your Flutter project — build & ship
cd path/to/your/flutter_app
flutter_distribute_manager

The tool detects your project, asks for platform + environment, builds, uploads, and prints the share links.

💡 Not sure what a command will do? Add --dry-run. It prints the exact plan, checks that Flutter and Google Drive are actually reachable, and exits non-zero if the real run would fail — without building anything.

🧭 Commands #

Every command supports --help.

🚩 Build flags #

Every prompt has a flag, so any build is scriptable.

⚠️ --yes changes the defaults. With no terminal (or with -y), the tool never asks: --platform and --environment fall back to whatever is saved in .flutter_distribute_manager.json, and then to android / DEV. Pass both explicitly in CI so a fresh checkout builds what you expect.

🔐 Secrets via environment #

A token passed as a command-line argument is visible to every user on the machine (ps auxww) and lands in shell history and CI command echoes. Prefer:

Precedence is flag → environment → saved config.

🔄 Reset flags #

flutter_distribute_manager reset        # keep the Google sign-in
flutter_distribute_manager reset --all  # disconnect Drive too

Interactively, reset lists exactly what it will remove and asks you to type reset to confirm — nothing is deleted by accident. If --all cannot actually remove the remote, it says so and exits non-zero rather than claiming success.

⚙️ Config flags (scriptable) #

config is interactive by default, but every field has a flag so a provisioning script or CI image can configure the tool without a terminal:

flutter_distribute_manager config --show                 # current values
flutter_distribute_manager config --show --json          # machine-readable
flutter_distribute_manager config --set-remote gdrive \
                                  --set-folder "Flutter Builds"
flutter_distribute_manager config --upload-to-drive      # on by default
flutter_distribute_manager config --set-diawi-token -    # clear it

Secrets are never printed back — --show reports set / ***set***, never the value.

🤖 CI/CD #

One-time: get credentials onto the runner #

--upload-drive needs an rclone remote and this tool's config. On a fresh runner neither exists, and init is interactive — so provision them from secrets instead. Run init once locally, then copy ~/.config/rclone/rclone.conf into a CI secret (it contains the Drive OAuth refresh token — treat it as a credential).

GitHub Actions #

name: Ship to QA
on:
  workflow_dispatch:
  push:
    tags: ['v*']

jobs:
  ship:
    runs-on: ubuntu-latest          # use macos-latest to also build iOS
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2
        with: { channel: stable }

      - name: Install rclone
        run: sudo apt-get update && sudo apt-get install -y rclone

      - name: Restore credentials
        env:
          RCLONE_CONF: ${{ secrets.RCLONE_CONF }}
        run: |
          mkdir -p ~/.config/rclone
          printf '%s' "$RCLONE_CONF" > ~/.config/rclone/rclone.conf
          chmod 600 ~/.config/rclone/rclone.conf

      - name: Install the CLI
        run: |
          dart pub global activate flutter_distribute_manager
          echo "$HOME/.pub-cache/bin" >> "$GITHUB_PATH"

      - name: Configure
        run: |
          flutter_distribute_manager config \
            --set-remote gdrive \
            --set-folder "Flutter Builds"

      - name: Preflight
        run: flutter_distribute_manager -p android --upload-drive --dry-run -y

      - name: Build & ship
        env:
          FDM_NOTIFY_URL: ${{ secrets.SLACK_WEBHOOK }}
        run: |
          flutter_distribute_manager \
            --platform android \
            --environment UAT \
            --app-name MyApp \
            --upload-drive \
            --yes --json > result.json
          cat result.json

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: build-result
          path: result.json

💡 The Preflight step is worth its 5 seconds: --dry-run exits non-zero when Flutter is missing or the Drive token has expired, so you find out before paying for a 15-minute build.

Any other CI #

flutter_distribute_manager \
  --platform both -e UAT --app-name MyApp \
  --upload-drive --yes --json

All human-readable output goes to stderr, so stdout carries only JSON.

📋 JSON output schema #

--json writes exactly one JSON document to stdout:

{
  "tool": "flutter_distribute_manager",
  "success": true,          // false when an upload failed (the build still succeeded)
  "dryRun": false,
  "app": "MyApp",
  "version": "1.4.2+7",     // straight from pubspec.yaml
  "environment": "UAT",     // DEV | UAT | PROD
  "platform": "both",       // android | ios | both
  "artifacts": [
    {
      "name": "MyApp_UAT_2026_06_19_0930_arm64-v8a.apk",
      "platform": "android",       // android | ios
      "sizeBytes": 25165824,
      "path": "/abs/path/build/distribute/MyApp_UAT_….apk",
      "abi": "arm64-v8a"           // omitted when not a per-ABI split
    }
  ],
  "links": [
    { "service": "Drive", "artifact": "MyApp_UAT_….apk", "url": "https://…" },
    { "service": "Diawi", "artifact": "MyApp_UAT_….ipa", "url": "https://i.diawi.com/…" }
  ],
  "warnings": [             // non-fatal degradations; see below
    "iOS was skipped: builds require macOS with Xcode (this machine is linux)."
  ],
  "timingsMs": { "androidBuild": 182000, "driveUpload": 9400 }
}

warnings is the field to watch. A run can succeed while quietly doing less than you asked — iOS skipped on a Linux runner, Drive upload with no shareable link, Diawi requested with no token. success: true with a non-empty warnings array means "shipped, but not everything you asked for."

# Fail the pipeline on any degradation, not just on a non-zero exit:
jq -e '.warnings | length == 0' result.json

Even when an upload fails, the JSON document is still written (with "success": false) so you never lose the artifact paths and the links that did succeed.

🔢 Exit codes #

🗂 How files land on Google Drive #

Flutter Builds/                  ← your root folder (set during init)
└── MyApp/                       ← --app-name
    └── 2026/
        └── June/
            ├── DEV/
            ├── UAT/
            │   └── MyApp_UAT_2026_06_19_0930_arm64-v8a.apk
            └── PROD/

Folder matching is case-insensitive, so re-runs reuse the same folders instead of piling up duplicates.

🔬 How it works #

No magic, and nothing you couldn't do by hand:

  ┌─ 1. Detect ────────────────────────────────────────────────┐
  │  Walk up from --app-dir for a pubspec.yaml with Flutter.    │
  │  Resolve the toolchain: --flutter-path → fvm → PATH.        │
  └────────────────────────────────────────────────────────────┘
                              ↓
  ┌─ 2. Pre-flight ────────────────────────────────────────────┐
  │  Take a per-project lock (two builds corrupt Gradle caches).│
  │  Prove rclone works AND the Drive remote actually answers   │
  │  — before you pay for the build, not after.                 │
  └────────────────────────────────────────────────────────────┘
                              ↓
  ┌─ 3. Build ─────────────────────────────────────────────────┐
  │  flutter build apk --release [--split-per-abi]              │
  │  flutter build ipa --release --export-method …              │
  │  Failures are matched against known signatures and turned   │
  │  into an actionable hint (a corrupt Kotlin cache is even    │
  │  cleaned and retried once, automatically).                  │
  └────────────────────────────────────────────────────────────┘
                              ↓
  ┌─ 4. Stage ─────────────────────────────────────────────────┐
  │  Copy only *this* build's artifacts into build/distribute/  │
  │  as MyApp_UAT_2026_06_19_0930_arm64-v8a.apk.                │
  │  (flutter-apk/ keeps every variant ever built — picking the │
  │  wrong one is how a debug APK reaches QA.)                  │
  └────────────────────────────────────────────────────────────┘
                              ↓
  ┌─ 5. Distribute ────────────────────────────────────────────┐
  │  rclone copy → Drive (App/Year/Month/ENV), then rclone link.│
  │  IPA → Diawi, polled until the install link is ready.       │
  │  Retries use backoff; permanent errors are not retried.     │
  └────────────────────────────────────────────────────────────┘
                              ↓
  ┌─ 6. Report ────────────────────────────────────────────────┐
  │  Summary table + share links, --json document, and an       │
  │  optional Slack/Discord/Teams post. Sent on failure too.    │
  └────────────────────────────────────────────────────────────┘

⚙️ Configuration #

The machine config holds API tokens, so on macOS/Linux it is written user-only (chmod 600) via an atomic temp-file rename — there is no window in which it sits world-readable, and an interrupted write cannot truncate a good config. XDG_CONFIG_HOME is honoured.

Add .flutter_distribute_manager.json to .gitignore if you'd rather not commit your per-project choices.

🎯 fvm-pinned projects #

If your app is pinned with fvm, you don't need a global flutter on your PATH. The tool detects fvm (.fvmrc, .fvm/, or .fvm/fvm_config.json) and runs the project's pinned SDK via fvm flutter … automatically — so builds use the exact version your project expects.

• It also finds a vendored SDK (.fvm/flutter_sdk, .fvm/versions/<v>, $FVM_CACHE_PATH, ~/fvm/versions/<v>) when fvm itself isn't on PATH.
• doctor reports Flutter (fvm 3.x.x) when it resolves via fvm.
• If the project is pinned but nothing fvm-shaped is found, the run warns and records a warning in the result rather than silently using a different SDK.
• Override detection anytime with --flutter-path /path/to/flutter.

🛠 Troubleshooting #

export PATH="$PATH":"$HOME/.pub-cache/bin"   # add to ~/.zshrc or ~/.bashrc
source ~/.zshrc

xattr -d com.apple.quarantine /path/to/binary

rclone config reconnect <remote>:          # refresh the token
flutter_distribute_manager init            # or redo setup
flutter_distribute_manager doctor          # confirm

# Install Xcode from the App Store first, then:
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept

❓ FAQ #

Do I need a Google Cloud project or OAuth credentials? No. rclone handles Google Drive sign-in in your browser during init.

Where is my Diawi token stored, and is it safe? In the machine config file, written user-only (chmod 600) on macOS/Linux via an atomic rename. It is never echoed to the terminal (entry is hidden), never printed by config --show, and is redacted from logs and error messages — including the ones Diawi itself echoes back.

Can I upload without rebuilding? Yes — --skip-build (alias --upload-only). Add --flavor if you use flavors.

Does it work on Windows / Linux? Yes for Android builds and Drive uploads. iOS builds require macOS + Xcode. On Linux/Windows, --platform ios fails immediately with a clear message (exit 78) — and under --dry-run it is reported as a blocker, so the JSON document is still emitted. --platform both builds Android and records a warning about the skipped iOS in warnings.

How do I change a saved setting? flutter_distribute_manager config (interactive), config --set-… (scripted), or override per-run with the matching flag.

Is this safe to run in CI? Yes. Pass every value as a flag plus --yes for zero prompts, and --json for a parseable result. Use --dry-run as a preflight gate. Distinct exit codes (see above) let a pipeline react.

Does it upload my source code anywhere? No. It uploads only the built artifacts, only to the destinations you enable, and it has no telemetry.

🧩 Programmatic use #

The building blocks are also exported as a library:

import 'dart:io';

import 'package:flutter_distribute_manager/flutter_distribute_manager.dart';

Future<void> main() async {
  final project = FlutterProject.find(Directory.current.path);
  if (project == null) {
    stderr.writeln('No Flutter project here.');
    exit(64);
  }

  final artifacts = await AndroidBuilder(const ProcessRunner(), Logger())
      .build(project, environment: ReleaseEnvironment.uat);

  for (final artifact in artifacts) {
    print('${artifact.name}  ${artifact.humanReadableSize}');
  }
}

See example/ for a full walkthrough.

🤝 Contributing #

Issues and PRs welcome at github.com/Ashutoshtripathi980/flutter_distribute_manager.

dart pub get
dart analyze          # must be clean
dart test             # 450 tests

📄 License #

MIT © 2026 Ashutosh Tripathi.