fflow-cli 1.0.3

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
  Verify: git --version

• Flutter SDK (includes Dart) — flutter.dev/docs/get-started/install
  Verify: flutter --version
  Required to install the FlutterFlow CLI via dart pub global.

• FlutterFlow CLI — install via:

  dart pub global activate flutterflow_cli
  

  Add Dart's pub global bin to PATH if not already:

  # Mac/Linux (bash)
  echo 'export PATH="$PATH:$HOME/.pub-cache/bin"' >> ~/.bashrc && source ~/.bashrc
  
  # Mac (zsh)
  echo 'export PATH="$PATH:$HOME/.pub-cache/bin"' >> ~/.zshrc && source ~/.zshrc
  

  Verify: flutterflow --version

• GitLab SSH access — fflow pushes via SSH. Set up your SSH key:

  ssh-keygen -t ed25519 -C "[e-mail]"
  cat ~/.ssh/id_ed25519.pub
  

  Copy the output and add it to GitLab under Profile → SSH Keys.
  Verify: ssh -T [e-mail]

• 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

1. Install pip (if not already installed)

Mac / Linux:

python3 -m ensurepip --upgrade

Or using the get-pip script:

curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python3 get-pip.py

Windows: pip comes bundled with Python. If missing:

python -m ensurepip --upgrade

Verify pip is installed:

pip3 --version

---

2. Add pip's bin directory to PATH

After installing pip packages, the fflow command needs to be on your PATH.

Mac / Linux (bash):

echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Mac (zsh — default on macOS Catalina+):

echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

Windows:
Python's user scripts folder is usually %APPDATA%\Python\PythonXX\Scripts.
Add it to PATH via System Properties → Environment Variables → Path → Edit.

Verify:

echo $PATH

---

3. Install fflow-cli

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