Metadata-Version: 2.4
Name: fluttership
Version: 1.1.7
Summary: AI agent that builds, signs, and ships Flutter apps — APK/AAB/IPA — from the terminal
Author: Abu Sayed Chowdhury
License: MIT
Project-URL: Homepage, https://github.com/AscEmon/fluttership
Project-URL: Repository, https://github.com/AscEmon/fluttership
Project-URL: Issues, https://github.com/AscEmon/fluttership/issues
Keywords: flutter,release,ci,cd,appstore,playstore,testflight,ai-agent,automation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic
Requires-Dist: google-genai
Requires-Dist: langchain-google-genai
Requires-Dist: langgraph
Requires-Dist: pyyaml
Requires-Dist: python-dotenv
Requires-Dist: cryptography
Requires-Dist: httpx
Requires-Dist: pydantic
Requires-Dist: questionary>=2.0.1
Requires-Dist: rich>=13.7.0
Requires-Dist: google-api-python-client>=2.149.0
Requires-Dist: google-auth>=2.35.0
Dynamic: license-file

# 🚀 FlutterShip

> An AI agent that builds, signs, and ships your Flutter app — APK, App Bundle, and IPA — from one terminal. Talk to it in plain English.

```
fluttership "build apk aab ipa for DEV and LIVE"
```

One command. Parallel builds. No forgotten version bumps, no wrong keystore passwords, no babysitting.

---

## Table of contents

- [What is FlutterShip?](#what-is-fluttership)
- [Quick start (free — uses a Gemini API key)](#quick-start)
- [How you actually use it](#how-you-actually-use-it)
- [Command reference](#command-reference)
- [⚡ Parallel builds](#-parallel-builds)
- [🔐 The secure vault](#-the-secure-vault)
- [📦 Publishing to the stores (what you need to download)](#-publishing-to-the-stores)
- [👤 Solo vs 👥 Team mode](#solo-vs-team-mode)
- [Requirements](#requirements)
- [Security model](#security-model)
- [Uninstalling](#uninstalling)
- [License](#license)

---

## What is FlutterShip?

FlutterShip is a Python CLI with an AI agent at its core. You point it at your Flutter
project and tell it what you want — *"build a LIVE apk"*, *"release 2.0.0 to TestFlight"* —
and it does the rest:

- **Reads your project automatically** — version, flavors, `dart-define` keys, bundle id, signing config. No config file to write.
- **Detects your build pattern** — flavors, `--dart-define`, `--dart-define-from-file`, or plain. It figures out the right `flutter build` command for you.
- **Builds in parallel** — APK + AAB + IPA across multiple flavors at once, each in an isolated sandbox.
- **Signs and submits** — uploads AAB to Google Play and IPA to TestFlight/App Store, with credentials kept in an encrypted vault the AI never sees.
- **Explains failures in plain English** — when a build breaks, it reads the log and tells you exactly what to fix.
- **Keeps a release history** — every build and upload is logged outside your repo.

You can drive it conversationally (the agent decides which tools to run) or with plain
subcommands (`fluttership doctor`, `fluttership status`, …).

---

## Quick start

FlutterShip needs an **LLM API key** to power the agent. The easiest free option is
**Google Gemini** — the free tier is plenty for normal use.

### 1. Get a free Gemini API key

1. Go to **[aistudio.google.com](https://aistudio.google.com)** and sign in.
2. Click **Get API key** → **Create API key**.
3. Copy the key (looks like `[YOUR_GEMINI_API_KEY]`).

> Want another free option? FlutterShip also supports `groq` — free and very
> fast (Llama / open models). Get a key at console.groq.com/keys.
> Prefer Claude or GPT? `anthropic` (console.anthropic.com) and `openai`
> (platform.openai.com) work too. Pick your provider during setup, or switch
> anytime in-session with `/model`.

### 2. Install FlutterShip

```bash
pip install fluttership
```

That's it — the `fluttership` command is now on your `PATH`.

<details>
<summary>Install from source (for development)</summary>

```bash
git clone https://github.com/AscEmon/fluttership.git
cd fluttership

python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

pip install -e .
```
</details>

### 3. First run — the setup wizard

From inside **any Flutter project**, run:

```bash
cd /path/to/your/flutter/app
fluttership
```

On first run a ~30-second wizard walks you through:

- **Mode** — solo (just you) or team (a lead shares credentials).
- **AI provider + model** — pick `gemini` and the default model.
- **Your API key** — paste it and FlutterShip saves it to `~/.fluttership/.env` (permissions `600`), or set it yourself (see below).

After that, you're talking to the agent. That's it.

### Setting the API key manually (optional)

Instead of pasting it into the wizard, you can put it in a `.env` file in your project
root, or in `~/.fluttership/.env`:

```env
# Pick one, matching your chosen provider
GEMINI_API_KEY=[YOUR_GEMINI_API_KEY]
# GROQ_API_KEY=[YOUR_GROQ_API_KEY]
# ANTHROPIC_API_KEY=[YOUR_ANTHROPIC_API_KEY]
# OPENAI_API_KEY=[YOUR_OPENAI_API_KEY]

# Optional — override provider/model without re-running the wizard
# (or just run /model in-session)
# LLM_PROVIDER=gemini
# GEMINI_MODEL=gemini-2.5-flash
# LLM_PROVIDER=groq
# GROQ_MODEL=llama-3.3-70b-versatile
```

> Project `.env` wins; `~/.fluttership/.env` fills the gaps. Both are git-ignored.

Verify everything is wired up:

```bash
fluttership doctor
```

---

## How you actually use it

There are two ways to drive FlutterShip — mix them however you like.

### A) Talk to the agent (natural language)

Just run `fluttership` and type what you want. Or pass it inline:

```bash
fluttership "build LIVE apk"
fluttership "build apk aab ipa for DEV and LIVE"     # parallel matrix
fluttership "release version 2.0.0 to production"
fluttership "what was the last release?"
```

The agent reads your project, shows a short build plan, asks for confirmation, builds,
and offers the right next step (e.g. *"Submit to TestFlight?"* only after an IPA is built).

Inside an interactive session, type **`/`** to open the command palette
(`/status`, `/doctor`, `/vault`, `/mode`, `/new`, `/exit`, …). Press **Esc** to
interrupt the agent mid-thought and redirect it.

### B) Plain subcommands (no LLM involved)

```bash
fluttership status      # version, bundle id, detected build pattern
fluttership doctor      # health checks — tools, signing, vault, API key
fluttership history     # build & release history for this project
fluttership clean       # delete build artifacts (fluttership-dist/)
fluttership uninstall   # remove FlutterShip + all its data from your machine
```

---

## Command reference

| Command | What it does |
|---|---|
| `fluttership` | Start the interactive AI agent |
| `fluttership "<request>"` | Run a one-off request, e.g. `"build LIVE apk"` |
| `fluttership setup` | Re-run the setup wizard (mode / provider / model) |
| `fluttership mode` | Show or switch solo/team mode |
| `fluttership mode solo` | Switch to solo mode |
| `fluttership mode team lead\|member` | Switch to team mode with a role |
| `fluttership config` | Show current configuration |
| `fluttership doctor` | Environment + project health checks |
| `fluttership status` | Project info — version, bundle id, build pattern |
| `fluttership history` | Build & release history |
| `fluttership clean` | Delete build artifacts (`fluttership-dist/`) |
| `fluttership vault setup` | Create the encrypted credentials vault (team: lead only) |
| `fluttership vault verify` | Test the vault password + show what's configured |
| `fluttership vault status` | Vault info (no password needed) |
| `fluttership vault log` | Credential-access audit log |
| `fluttership vault export [dest]` | Share the encrypted vault with your team (lead only) |
| `fluttership vault import <file>` | Install a vault shared by your team lead |
| `fluttership uninstall` | Remove FlutterShip completely — deletes `~/.fluttership` (config, vault, history) and uninstalls the pip package. Use `--keep-data` to keep your vault/history, or `--yes` to skip the prompt |
| `fluttership help` | Full usage |

**Slash commands** (inside an interactive session): `/status`, `/history`, `/doctor`,
`/clean`, `/mode`, `/model`, `/config`, `/vault`, `/setup`, `/new`, `/exit`.

---

## ⚡ Parallel builds

FlutterShip's headline feature. Ask for several targets and/or flavors at once and it
builds them **concurrently**, each job in its own isolated git worktree sandbox:

```bash
fluttership "build apk aab ipa for DEV and LIVE"
```

A live dashboard shows every job's status as it runs:

```
⚡ Building 6 jobs · v2.0.0+9
┌──────────────┬──────────────┬────────┬──────────────────────────────┐
│ Job          │ Status       │   Time │ Detail                       │
├──────────────┼──────────────┼────────┼──────────────────────────────┤
│ apk·DEV      │ ✅ done      │  1m42s │ myapp_DEV_2.0.0(9).apk       │
│ apk·LIVE     │ ✅ done      │  1m48s │ myapp_LIVE_2.0.0(9).apk      │
│ aab·LIVE     │ 🔨 building  │  0m55s │ logs/aab-LIVE.log            │
│ ipa·LIVE     │ 🍎 archiving │  2m10s │ logs/ipa-LIVE.log            │
└──────────────┴──────────────┴────────┴──────────────────────────────┘
```

**Why it's worth it:**

- **Faster releases** — wall-clock time is your *slowest* build, not the sum of all of them.
- **No collisions** — each job runs in a fresh, isolated worktree, so Gradle's project lock and the shared `build/` directory never clash. iOS archives are automatically serialized (Xcode's global state can't take two `Runner` archives at once), while Android builds stay fully parallel.
- **One shared version** — every artifact in a run carries the same version+build number, so a matrix release is consistent.
- **Artifacts collected safely** — finished builds land in `fluttership-dist/` (outside `build/`), so `flutter clean` can't wipe what you just built. Per-job logs go to `build/fluttership-logs/`.
- **Different flavors per platform** — *"LIVE and DEV apk, plus LIVE ipa only"* builds exactly those pairs, no wasted builds.

Run `fluttership clean` to reclaim space from `fluttership-dist/` when you're done
(your release history, kept in `~/.fluttership`, is never touched).

---

## 🔐 The secure vault

Store credentials (App Store `.p8` key, Play Store service-account JSON, IDs) are
sensitive. FlutterShip keeps them in an **encrypted vault** — never in your repo, never
in plain text, and **never shown to the AI model**.

**How it's protected:**

- **AES-256-GCM** encryption with **PBKDF2** key derivation (200,000 iterations).
- Lives in `~/.fluttership/vault.enc` (`chmod 600`) — outside your project.
- Files are base64-encoded *before* encryption — not human-readable.
- Decrypted **in memory only**; temp files written to `/tmp` (`chmod 600`) are deleted immediately after each upload.
- The LLM only ever sees **success/fail status** — never a key, password, or token.
- Every access is written to an **audit log** (`fluttership vault log`).

**Set it up once:**

```bash
fluttership vault setup
```

It asks for your Play Store service-account JSON, App Store `.p8` key, and the matching
IDs (see the next section for how to get those), then asks you to set a vault password.

```bash
fluttership vault verify    # test your password + see what's configured
fluttership vault status    # info only — no password needed
```

> Choose a strong vault password and store it in a password manager. If you share the
> vault with a team, **never** send the password over chat or email — use a shared
> password-manager item.

---

## 📦 Publishing to the stores

To upload builds, FlutterShip needs store credentials in the vault. Here's exactly what
to download and where to get each piece. Run `fluttership vault setup` and have these
ready.

### 🍎 App Store / TestFlight (iOS — IPA)

You need an **App Store Connect API key**. Three pieces:

| What | Where to get it |
|---|---|
| **`.p8` key file** | App Store Connect → **Users & Access** → **Integrations / Keys** → **(+)** generate a key with *App Manager* access. **Download the `.p8` — it can only be downloaded once.** |
| **Key ID** | Shown next to the key you created (e.g. `[YOUR_KEY_ID]`). |
| **Issuer ID** | At the top of the **Keys** page (e.g. `[YOUR_ISSUER_ID]`). |
| **Bundle ID** | Your app's bundle identifier, must match your Xcode project. |

> The app must already exist in App Store Connect (**My Apps → (+) New App**) with a
> matching bundle ID before the first upload. Uploads go to TestFlight via `xcrun altool`,
> so iOS publishing requires **macOS + Xcode**.

### 🤖 Google Play (Android — AAB)

You need a **service-account JSON** with Play Developer API access:

| What | Where to get it |
|---|---|
| **Service account JSON** | Google Play Console → **Setup → API access** → create/link a service account in Google Cloud Console, grant it release permissions, then **download its JSON key**. |
| **Package name** | Your app's `applicationId` (e.g. `com.example.myapp`). |

> Play uploads default to the **`internal`** track (safest). Change it with
> `fluttership config` or by telling the agent *"release to production"*.
> The Play Store rejects duplicate version codes, so FlutterShip prompts you to confirm
> the version + build number for every store-bound build.

### Then just ask

```bash
fluttership "release 2.0.0 to TestFlight and Play Store"
```

FlutterShip unlocks the vault (you enter the vault password), uploads, and records it as
a **release** in your history. A build that was only compiled — never uploaded — stays a
"build", not a "release".

---

## Solo vs Team mode

**Solo** — everything lives on your machine. You own the vault and the releases.

**Team** — a shared-vault workflow:

- The **lead** runs `vault setup` once, then `vault export` to produce the encrypted
  `fluttership-vault.enc` file and hands it to members.
- **Members** run `vault import <file>` and can build + submit, but never manage or
  re-export credentials.
- The vault **file** is safe to share (it's AES-256-GCM encrypted and useless without the
  password). Share the **password** only through a team password manager.

```bash
fluttership mode team lead      # you manage credentials
fluttership mode team member    # you import the lead's vault
```

---

## Requirements

- **Python 3.9+**
- **Flutter SDK** (on your `PATH`)
- **git** and **rsync** (rsync powers the isolated parallel-build sandboxes)
- For iOS builds/uploads: **macOS + Xcode + CocoaPods**
- An LLM API key (Gemini free tier works great)

Run `fluttership doctor` any time to check all of the above.

---

## Security model

- **Credentials are never committed** — the vault lives in `~/.fluttership/`, outside your repo, and `.p8`/`.jks`/`.json`/`.env` files are git-ignored by default.
- **The AI never sees secrets** — it receives only success/fail status and file *paths*, never key material.
- **Encryption at rest** — AES-256-GCM + PBKDF2; decrypted only in memory; temp files wiped after use.
- **Audit trail** — vault unlocks, exports, imports, and uploads are logged.
- Built artifacts can embed compiled code and `dart-define` values, so `fluttership-dist/` is git-ignored automatically — **never commit your builds.**

> If you fork or publish this repo, scrub any API keys from your git history before
> making it public — a key committed even once stays in the history until rewritten.

---

## Uninstalling

To remove FlutterShip completely from your machine:

```bash
fluttership uninstall
```

This deletes `~/.fluttership/` — your config, the **encrypted vault** (signing
credentials, store API keys), and your release history — and then uninstalls the
pip package. It asks you to type `uninstall` to confirm, because wiping the vault
is irreversible.

```bash
fluttership uninstall --keep-data   # uninstall the tool, keep your vault + history
fluttership uninstall --yes         # skip the confirmation prompt
```

> Want to remove only build artifacts from a project (not the whole tool)? Use
> `fluttership clean` instead.

---

## License

MIT

---

*Built by [Abu Sayed Chowdhury](https://github.com/AscEmon) — a Flutter dev who got tired of spending 3 hours on a 10-minute release.*
