fflow-cli 1.0.1

FlutterFlow Git workflow CLI — manage feature branches, exports, staging and pushes.

fflow — FlutterFlow Git Workflow CLI

Automates the FlutterFlow → Git workflow for teams.
Designed for developers who export FlutterFlow code via CLI and push to GitLab.

---

Requirements

Before installing, make sure you have:

• Python 3.9+ — python.org/downloads
• Git — git-scm.com
• FlutterFlow CLI — install via:

  dart pub global activate flutterflow_cli
  

  Then make sure flutterflow is in your PATH.
• A GitLab repository with your FlutterFlow project connected
• A FlutterFlow export CLI command — get it from your FlutterFlow project settings under Developer Settings → Export Code CLI

---

Installation

pip install fflow-cli

Verify the install:

fflow --help

---

One-time Setup (per repository)

Run this inside your Flutter project's git repo:

cd /path/to/your/flutter/repo
fflow setup

You will be asked for:

1. FlutterFlow CLI export command — paste the full command from FlutterFlow (token stored securely, never in git)
2. GitLab repository URL — e.g. [e-mail]:group/repo.git
3. Parent branches — e.g. uat, migrated_uat, migrated_prod
4. Custom files — any hand-written files to protect from FF export overwrites

Run fflow setup again anytime to update individual settings.

---

Daily Usage

Every time you work — just run:

fflow

fflow reads your current git state and guides you through every step interactively:

1. Creates your feature branch (PROJ-123-uat)
2. Runs FlutterFlow CLI export
3. Restores your custom code files automatically
4. Asks which pages/folders you worked on
5. Shows exact file list before staging
6. Detects if someone pushed to the parent branch mid-work
7. Safely syncs (rebases) without losing your work
8. Commits with the correct format (PROJ-123 LoginPage, ProfilePage changes)
9. Pushes to GitLab

---

Commands

Command	When to use
fflow	Every time — runs the main workflow
fflow setup	Once per repo, or to update settings
fflow doctor	When something looks broken
fflow status	Check current task phase and branch

---

Branch & Commit Format

• Branch: PROJ-123-uat
• Commit: PROJ-123 LoginPage, ProfilePage changes

---

Custom File Protection

Protect hand-written files that would otherwise be overwritten by FlutterFlow export:

fflow setup  # → choose "Custom files" to add/remove entries

Before every FF export, fflow backs up all registered files and restores them after — your code is never lost.

---

Mid-Work Sync

If someone pushes to the parent branch while you're working, fflow:

1. Detects it automatically before every step
2. Warns you with the number of new commits
3. Stashes your changes → rebases → re-applies → restores custom files
4. Auto-resolves FF-generated file conflicts
5. Pauses for manual resolution on your files
6. Run fflow again after resolving to continue

---

Files Created in Your Repo

File	Purpose	Git-tracked?
.fflow.json	Project config (branches, endpoint, project ID)	✔ Yes
.fflow.env	Your FF token (secret)	✖ No (gitignored)
.fflow_registry.json	List of your custom files	✔ Yes
.fflow_state.json	Current task session state	✖ No (gitignored)
.fflow_custom_backup/	Backup of custom files before FF export	✖ No (gitignored)

---

Upgrading

pip install --upgrade fflow-cli