Flaunch CLI

Installation

Install FLaunch using our one-line installer script for your platform:

Verify Installation

Supported platforms: macOS (Intel & Apple Silicon), Linux (x86_64 & ARM64), Windows (x86_64)

Quick Start

# flaunch.local.yaml (keep this file private!)
releasehub:
  api_key: "your-api-key-here"

Configuration Overview

Flaunch uses two configuration files: flaunch.yaml for shared settings (committed to git) and flaunch.local.yaml for sensitive data (automatically added to .gitignore).

# flaunch.yaml - Example configuration

project:
  name: "My Flutter App"
  bundle_id: "com.example.myapp"
  type: "flutter"  # or "fvm", "cargo", "cargo-iss"
  output_naming: "{name}-{version}-{arch}-{flavor}.apk"

flavors:
  dev:
    display_name: "Development"
    single_apk: false
    build_commands:
      - "flutter build apk --flavor dev --split-per-abi"
    output_paths:
      - "./build/app/outputs/apk/dev/release/*.apk"

  prod:
    display_name: "Production"
    single_apk: true
    build_commands:
      - "flutter build apk --flavor prod --release"
    output_paths:
      - "./build/app/outputs/apk/prod/release/*.apk"

releasehub:
  api_url: "https://app.releasehub.dev"
  channel: "beta"

discord:
  webhooks:
    - "${DISCORD_WEBHOOK_URL}"
  include_commits: true

git:
  enabled: true
  auto_commit_bump: false

flaunch run

Execute the full release pipeline: bump version, build, upload, and notify.

Options

flaunch bump

Bump the version number in your pubspec.yaml or Cargo.toml.

Bump Types

Options

flaunch build

Execute build commands for a specific flavor.

Options

flaunch upload

Upload built APKs/AABs to ReleaseHub or via SFTP.

Options

flaunch sync

Sync your local version with the latest from ReleaseHub. Useful for keeping multiple developers in sync.

Options

flaunch notify

Send a Discord notification about a build.

Options

The --results flag accepts JSON-formatted upload results, typically piped from the upload command for richer Discord notifications with download links.

flaunch version

Display the current version from pubspec.yaml or Cargo.toml.

flaunch flavors

List all available build flavors defined in your configuration.

flaunch validate

Validate your configuration file and check for common issues.

flaunch init

Run the interactive configuration wizard to create a new flaunch.yaml file.

Options

Global Options

These options can be used with any command:

Project Settings

project:
  name: "My App"           # Display name
  bundle_id: "com.example.app"  # App bundle ID
  type: "flutter"          # Project type
  output_naming: "{name}-{version}-{arch}.apk"

Built-in Project Types

Project types are data-driven using JSON definitions. You can create custom types or override built-in ones. See Custom Project Types for details.

Output Naming Placeholders

Custom Project Types

FLaunch uses data-driven project type definitions stored as JSON files. This enables you to add support for new project types, customize version patterns, or define secondary files that should be updated alongside the main version file.

Type Definition Locations

FLaunch searches for type definitions in this order:

Creating a Custom Type

Create a JSON file in your user types directory. Example for Node.js projects:

// %APPDATA%\flaunch\types\node.json
{
  "name": "node",
  "display_name": "Node.js",
  "description": "Node.js projects using package.json",

  "version_format": {
    "pattern": "^(\\d+)\\.(\\d+)\\.(\\d+)$",
    "has_build_number": false,
    "example": "1.2.3"
  },

  "default_bump_type": "patch",

  "version_files": {
    "primary": {
      "path": "package.json",
      "read_pattern": "\"version\"\\s*:\\s*\"(?P<version>[^\"]+)\"",
      "write_template": "\"version\": \"{version}\""
    }
  }
}

Type Schema Reference

Type Inheritance

Types can inherit from other types using the extends field. Child values override parent values:

// cargo-iss inherits from cargo, adds secondary files
{
  "name": "cargo-iss",
  "display_name": "Rust + Inno Setup",
  "extends": "cargo",

  "version_files": {
    "secondary": [
      {
        "path_glob": "installer/*.iss",
        "read_pattern": "#define\\s+MyAppVersion\\s+\"(?P<version>[^\"]+)\"",
        "write_template": "#define MyAppVersion \"{version}\"",
        "version_format": "semver_only"
      }
    ]
  }
}

Build Flavors

flavors:
  dev:
    display_name: "Development"
    single_apk: false        # Split APKs per architecture
    build_commands:
      - "flutter build apk --flavor dev --split-per-abi"
    output_paths:
      - "./build/app/outputs/apk/{flavor}/release/*.apk"
    env:                      # Optional environment variables
      API_URL: "https://dev.api.example.com"

  prod:
    display_name: "Production"
    single_apk: true         # Universal APK
    build_commands:
      - "flutter build apk --flavor prod --release"
    output_paths:
      - "./build/app/outputs/apk/{flavor}/release/*.apk"

ReleaseHub Configuration

releasehub:
  api_url: "https://app.releasehub.dev"
  api_key: "${RELEASEHUB_API_KEY}"  # Use env var!
  channel: "beta"                   # Default channel
  platform: "android"              # android, windows, macos
  chunk_size: 10485760            # 10MB chunks
  create_as_draft: false

SFTP Upload (Alternative)

upload:
  host: "your-server.com"
  port: 22
  username: "deploy"
  password: "${SFTP_PASSWORD}"  # Or use private_key
  # private_key: "~/.ssh/id_rsa"
  remote_dir: "/var/www/apk"

Discord Notifications

discord:
  webhooks:
    - "${DISCORD_WEBHOOK_URL}"
    - "https://discord.com/api/webhooks/..."  # Multiple webhooks
  embed_color: 3066993     # Green (decimal color)
  embed_title: "New Build Available!"
  include_commits: true   # Show git commits since last build

Git Integration

git:
  enabled: true
  build_cache: ".flaunch_cache"  # Tracks last build commit
  auto_commit_bump: false
  bump_commit_message: "chore: bump version to {version}"

Local Configuration Overrides

Create a flaunch.local.yaml file for machine-specific settings and sensitive data. This file is automatically added to .gitignore.

# flaunch.local.yaml - Local overrides (DO NOT COMMIT)

releasehub:
  api_key: "sk_live_xxxxxxxxxxxxxxxxxxxx"

discord:
  webhooks:
    - "https://discord.com/api/webhooks/123/abc..."

upload:
  password: "my-sftp-password"

Interactive Mode

Running flaunch without arguments opens an interactive menu:

GitHub Actions

Create a workflow file at .github/workflows/release.yml to automate releases on push to main or on tags:

name: Release

on:
  push:
    tags:
      - 'v*'
  workflow_dispatch:
    inputs:
      flavor:
        description: 'Build flavor'
        required: true
        default: 'prod'
        type: choice
        options:
          - dev
          - prod

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Flutter
        uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.24.0'
          channel: 'stable'

      - name: Install FLaunch
        run: curl -fsSL https://releasehub.dev/install.sh | sh

      - name: Build and Release
        env:
          RELEASEHUB_API_KEY: ${{ secrets.RELEASEHUB_API_KEY }}
          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
        run: |
          flaunch run \
            --flavor ${{ inputs.flavor || 'prod' }} \
            --channel stable \
            --changelog "Release ${{ github.ref_name }}"

GitLab CI

Add to your .gitlab-ci.yml file:

stages:
  - release

variables:
  FLUTTER_VERSION: "3.24.0"

release:
  stage: release
  image: ghcr.io/cirruslabs/flutter:$FLUTTER_VERSION
  before_script:
    - curl -fsSL https://releasehub.dev/install.sh | sh
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    - flaunch run --flavor prod --channel stable
  only:
    - tags
  variables:
    RELEASEHUB_API_KEY: $RELEASEHUB_API_KEY
    DISCORD_WEBHOOK_URL: $DISCORD_WEBHOOK_URL

Configure RELEASEHUB_API_KEY and DISCORD_WEBHOOK_URL as CI/CD variables in your GitLab project settings (Settings → CI/CD → Variables).

Bitbucket Pipelines

Add to your bitbucket-pipelines.yml file:

image: ghcr.io/cirruslabs/flutter:3.24.0

pipelines:
  tags:
    'v*':
      - step:
          name: Build and Release
          caches:
            - flutter
          script:
            - curl -fsSL https://releasehub.dev/install.sh | sh
            - export PATH="$HOME/.local/bin:$PATH"
            - flutter pub get
            - flaunch run --flavor prod --channel stable --changelog "Release ${BITBUCKET_TAG}"

definitions:
  caches:
    flutter: ~/.pub-cache

Add RELEASEHUB_API_KEY and DISCORD_WEBHOOK_URL as repository variables in Bitbucket (Repository settings → Pipelines → Repository variables).

CI/CD Best Practices