DartDosh CLI – User Guide

📖 Read this in other languages: 🇺🇿 O'zbekcha | 🇷🇺 Русский | 🇹🇷 Türkçe

---

DartDosh is a powerful CLI tool for simplifying Flutter builds with automatic version management, multi-language support, and smart output handling.

🌍 Multi-Language Support

DartDosh now supports 4 languages!

• 🇺🇿 Uzbek (uz) - "Xo'jayiin" style - Default
• 🇬🇧 English (en) - "Boss" style
• 🇷🇺 Russian (ru) - "Босс" style
• 🇹🇷 Turkish (tr) - "Patron" style - NEW!

📺 Video Tutorial

Watch the full tutorial on YouTube: DartDosh - Flutter Build Automation

---

dartdosh build <target> --<environment> [extra flags]

Examples:

# With environment (flavor builds) - automatic version management
dartdosh build ipa --production --split
dartdosh build apk --development --other-flag
dartdosh build appbundle --staging

# Short flags (convenient!)
dartdosh build apk -p              # production
dartdosh build apk -prod           # production
dartdosh build apk -d              # development
dartdosh build apk -dev            # development
dartdosh build apk -s              # staging

# Without environment - plain Flutter build (no version management)
dartdosh build apk                 # flutter build apk
dartdosh build apk --release       # flutter build apk --release
dartdosh build ipa --split         # flutter build ipa --split-per-abi

---

🔧 Using --dart-define-from-file

DartDosh fully supports Flutter's --dart-define-from-file for loading configuration from JSON files. You can use it in two ways:

Method 1: Direct Command Line

Pass the flag directly when building:

# Load config from file
dartdosh build apk -p --dart-define-from-file=config/prod.json
dartdosh build ipa -s --dart-define-from-file=config/staging.json

# Combine with other flags
dartdosh build apk -p --dart-define-from-file=config/prod.json --obfuscate

Method 2: Configure in build_config.json (Recommended for Teams)

Add --dart-define-from-file to your build commands in dartdosh_config/build_config.json:

{
  "apk": {
    "production": "flutter build apk --release --flavor production --dart-define-from-file=config/prod.json",
    "staging": "flutter build apk --release --flavor staging --dart-define-from-file=config/staging.json"
  },
  "ipa": {
    "production": "flutter build ipa --release --flavor production --dart-define-from-file=config/prod.json",
    "staging": "flutter build ipa --release --flavor staging --dart-define-from-file=config/staging.json"
  }
}

Then simply run:

dartdosh build apk -p    # Automatically uses config/prod.json
dartdosh build ipa -s    # Automatically uses config/staging.json

Why use Method 2?

• ✅ Team consistency - Everyone uses the same config files
• ✅ No need to remember file paths
• ✅ One command for all environments
• ✅ Easier to maintain in teams

Example config file (config/prod.json):

{
  "API_URL": "https://api.production.com",
  "API_KEY": "prod-key-12345",
  "ENABLE_ANALYTICS": "true"
}

---

Requirements

• Dart SDK ≥ 3.0
• Flutter SDK installed
• Terminal (Mac/Linux/Windows)

---

Installation

Install from pub.dev

dart pub global activate dartdosh

Add to PATH (if needed)

Mac/Linux (.zshrc or .bashrc):

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

Windows PowerShell:

$env:PATH += ";$env:USERPROFILE\.pub-cache\bin"

---

Configuration

Initialize DartDosh

Run this command first in your Flutter project:

dartdosh init

This creates dartdosh_config folder with 2 files:

1. build_config.json (Team Shared - Git Tracked)

Build commands for your team. Everyone uses the same commands:

{
  "apk": {
    "production": "flutter build apk --release --flavor production",
    "staging": "flutter build apk --release --flavor staging",
    "development": "flutter build apk --debug --flavor development"
  },
  "ipa": {
    "production": "flutter build ipa --release --flavor production",
    "staging": "flutter build ipa --release --flavor staging",
    "development": "flutter build ipa --debug --flavor development"
  },
  "appbundle": {
    "production": "flutter build appbundle --release --flavor production",
    "staging": "flutter build appbundle --release --flavor staging",
    "development": "flutter build appbundle --debug --flavor development"
  },
  "firebase_distribution": {
    "production": {
      "app_id": "1:123456789:android:prodabc123",
      "tester_groups": "production-testers,management"
    },
    "staging": {
      "app_id": "1:123456789:android:stagabc123",
      "tester_groups": "qa-team,staging-testers"
    },
    "development": {
      "app_id": "1:123456789:android:devabc123",
      "tester_groups": "developers,internal-testers"
    }
  }
}

2. settings.json (Personal - Git Ignored)

Your personal settings. Each developer has their own:

{
  "language": "uz",
  "project_name": "my_app",
  "auto_increment_build_number": false,
  "output_path": "~/Desktop/dartdosh-builds",
  "ipa_upload": {
    "enabled": true,
    "apple_id": "developer@example.com",
    "app_specific_password": "abcd-efgh-ijkl-mnop"
  },
  "firebase_distribution": {
    "production": {
      "enabled": false
    },
    "staging": {
      "enabled": true
    },
    "development": {
      "enabled": true
    }
  }
}

Why 2 files?

• build_config.json → Team shares build commands (Git tracked)
• settings.json → Your personal settings like Apple ID (Git ignored)
• No more credential conflicts in team!

Settings Parameters:

• language: Interface language

  • uz (Uzbek), en (English), ru (Russian), tr (Turkish)
  • Default: uz

• project_name: Project name for organizing builds

  • Default: Reads from pubspec.yaml

• auto_increment_build_number: Auto increase version

  • true: Increases build number before each build
  • false: Keeps current version (default)

• output_path: Where to save builds

  • Default: ~/Desktop/dartdosh-builds
  • Absolute or relative path

• ipa_upload: Auto upload IPA to App Store

  • enabled: true/false
  • apple_id: Your Apple ID
  • app_specific_password: Get from appleid.apple.com
  • macOS only

• firebase_distribution: Auto upload APK to Firebase App Distribution (per environment)

  • Each environment (production, staging, development) has:
    • enabled: true/false - Enable/disable upload for this environment
  • App ID and tester groups are configured in build_config.json
  • Requires Firebase CLI installed

How to get App-Specific Password:

1. Go to https://appleid.apple.com
2. Security → Generate Password
3. Name it "DartDosh"
4. Copy and paste in settings.json

How to setup Firebase App Distribution:

1. Install Firebase CLI: npm install -g firebase-tools
2. Login: firebase login
3. Get App ID from Firebase Console → Project Settings
4. Add tester groups in Firebase Console → App Distribution
5. Enable and configure in settings.json

---

Usage

dartdosh build <target> [--<environment>] [extra flags]

Parameters:

• <target>: Build target

  • apk - Android APK
  • ipa - iOS IPA
  • appbundle or aab - Android App Bundle (both commands supported)

• <environment>: Build environment (OPTIONAL - multiple flag variants supported!)

  • Production: --production, -p, -prod
  • Staging: --staging, -s
  • Development: --development, -d, -dev
  • Note: If no environment specified, runs plain Flutter build without version management

• [extra flags]: Additional Flutter build flags

  • --split - For APK builds, automatically adds --split-per-abi
  • --obfuscate - Obfuscate Dart code
  • --dart-define=KEY=VALUE - Define environment variables
  • Any other Flutter build flags

---

📱 iOS (IPA) Build Quick Guide

Building iOS apps with DartDosh is simple and includes automatic upload to App Store Connect.

Prerequisites

1. macOS with Xcode - Required for iOS builds
2. Valid Apple Developer Account - For distribution builds
3. Code Signing Setup - Certificates and provisioning profiles configured in Xcode

Basic IPA Build

# Production build
dartdosh build ipa --production
dartdosh build ipa -p

# Staging build
dartdosh build ipa --staging
dartdosh build ipa -s

# With obfuscation
dartdosh build ipa -p --obfuscate

# With dart-define variables
dartdosh build ipa -p --dart-define=API_URL=https://api.production.com

Automatic Upload to App Store Connect

DartDosh can automatically upload your IPA to App Store Connect after a successful build.

1. Get App-Specific Password

1. Go to appleid.apple.com
2. Sign in with your Apple ID
3. In Security section → App-Specific Passwords → Generate Password
4. Name it "DartDosh" and copy the password (format: xxxx-xxxx-xxxx-xxxx)

2. Configure in build_config.json

{
  "ipa_upload": {
    "enabled": true,
    "apple_id": "your-email@example.com",
    "app_specific_password": "xxxx-xxxx-xxxx-xxxx"
  }
}

3. Build and Upload

dartdosh build ipa -p

Output:

[████████████████████████████████] 100% - [ipa - production] - Ready!
✅ ipa build completed successfully, Boss!
✅ Build saved: ~/Desktop/dartdosh-builds/my_app/ipa/prod_1.0.0_100.ipa, Boss!

📤 Uploading IPA to App Store Connect...
📊 Upload in progress...
✅ IPA successfully uploaded to App Store Connect, Boss!

⏱️ Total time: 180.5 seconds

Output Files

IPA files are automatically organized:

~/Desktop/dartdosh-builds/
└── my_app/
    └── ipa/
        ├── prod_1.0.0_100.ipa
        ├── prod_1.0.0_101.ipa
        └── stg_1.0.0_50.ipa

File naming format: {env}_{version}_{buildNumber}.ipa

Important Notes

• Upload requires macOS - Uses xcrun altool (built into Xcode)
• Upload is optional - Set "enabled": false to disable
• Security - Add build_config.json to .gitignore to protect credentials
• App must exist in App Store Connect - Create your app first at appstoreconnect.apple.com
• Upload doesn't submit - It only uploads the build; you still need to submit through App Store Connect

Troubleshooting

Upload fails?

• Verify your Apple ID and app-specific password
• Ensure app exists in App Store Connect
• Check internet connection
• Make sure Xcode command line tools are installed: xcode-select --install

Build fails?

• Check code signing in Xcode
• Verify provisioning profiles are valid
• Run flutter doctor to check iOS setup

---

Features

🌍 Multi-Language Support

DartDosh supports three languages for all interface messages and progress indicators:

• Uzbek (uz) - Default language with "Xo'jayiin" (Boss) addressing
• English (en) - Professional English interface with "Boss" addressing
• Russian (ru) - Russian interface with "Босс" (Boss) addressing

Setting Language:

{
  "language": "en"  // Set in build_config.json
}

Language Features:

• All log messages translated
• Progress bar stages localized
• Build status messages in selected language
• Donation messages with cultural humor
• Automatic fallback to English for unsupported languages with warning

Example Uzbek:

📈 Yangi build number: 46 (oldingi: 45), Xo'jayiin!
[████████████████░░░░░░░░░░░░░░]  60% - [apk - production] - Bundle yaratilmoqda...
✅ apk build muvaffaqiyatli yakunlandi, Xo'jayiin!

Example English:

📈 New build number: 46 (previous: 45), Boss!
[████████████████░░░░░░░░░░░░░░]  60% - [apk - production] - Creating bundle...
✅ apk build completed successfully, Boss!

🤖 Auto Configuration

When build_config.json doesn't exist in your Flutter project, DartDosh will:

1. Create the config with sensible defaults
2. Open it in your IDE automatically for review
3. Stop execution and prompt you to re-run the command

This ensures you can review and adjust the configuration before your first build.

Example workflow:

# First run (no config exists)
dartdosh build apk --production
# Output: Config created and opened in IDE, please review and run again

# Second run (config reviewed)
dartdosh build apk --production
# Output: Normal build proceeds

🔢 Automatic Version Management (Optional)

When using environment flags (flavor builds) and auto_increment_build_number: true, DartDosh automatically:

1. Reads the current version from pubspec.yaml
2. Increments the build number by 1
3. Updates pubspec.yaml with the new build number

Example:

# Before build (with environment flag and auto_increment enabled)
version: 1.2.3+45

# After build
version: 1.2.3+46

Notes:

• Default: false (auto increment is disabled by default)
• Version increment only happens for flavor builds (with environment flag)
• Enable by setting auto_increment_build_number: true in config
• Plain builds (dartdosh build apk) never modify version numbers

📦 Smart File Naming

For flavor builds (with environment flags), built files are automatically renamed using the format:

{shortEnv}_{version}_{buildNumber}.{extension}

Environment short names:

• production → prod
• development → dev
• staging → stg

Examples:

• prod_1.2.3_46.apk
• stg_2.0.0_12.ipa
• dev_1.5.0_78.aab

For split APKs:

• prod_1.2.3_46_arm64-v8a.apk
• prod_1.2.3_46_armeabi-v7a.apk
• prod_1.2.3_46_x86_64.apk

For plain builds (without environment), files are renamed using the format:

{target}_{version}_{buildNumber}.{extension}

Examples:

• apk_1.2.3_46.apk
• ipa_2.0.0_12.ipa
• appbundle_1.5.0_78.aab

Note: Plain builds don't increment version, but still get renamed and moved to output_path.

📁 Output Path Management

If output_path is specified in build_config.json:

• Built files are copied to the specified directory with organized structure
• Files are organized by: output_path/project_name/{apk|ipa|aab}/
• Each build type gets its own subfolder for better organization
• Original files remain in the build directory
• Directory structure is created automatically

Example structure:

~/Desktop/dartdosh-builds/
└── my_app/
    ├── apk/
    │   ├── prod_1.0.0_100.apk
    │   └── dev_1.0.0_101.apk
    ├── ipa/
    │   └── prod_1.0.0_100.ipa
    └── aab/
        └── prod_1.0.0_100.aab

Without output_path:

• Files are only renamed in the build directory

---

🚀 IPA Auto Upload to App Store Connect

DartDosh can automatically upload your IPA files to App Store Connect after a successful build using Apple's official Transporter tool.

Prerequisites

1. macOS with Xcode installed - Required for xcrun iTMSTransporter
2. Valid Apple Developer Account - With app created in App Store Connect
3. Valid Certificates & Provisioning Profiles - iOS Distribution certificate and provisioning profile
4. App-Specific Password - Generated from Apple ID settings

Step 1: Generate App-Specific Password

1. Go to https://appleid.apple.com
2. Sign in with your Apple ID (the one used for App Store Connect)
3. Navigate to Security section
4. Under App-Specific Passwords, click Generate Password
5. Enter a label (e.g., "DartDosh CLI Tool")
6. Click Create
7. Copy the generated password (format: xxxx-xxxx-xxxx-xxxx)
   • ⚠️ Save this password - you can't view it again!

Step 2: Configure build_config.json

Open your build_config.json and add/update the ipa_upload section:

{
  "language": "uz",
  "project_name": "my_app",
  "auto_increment_build_number": false,
  "output_path": "~/Desktop/dartdosh-builds",
  "ipa_upload": {
    "enabled": true,                                    // ← Set to true
    "apple_id": "developer@example.com",                // ← Your Apple ID
    "app_specific_password": "abcd-efgh-ijkl-mnop"     // ← Paste generated password
  }
}

Step 3: Build and Upload

Simply build your IPA as usual:

dartdosh build ipa --production

What happens:

1. ✅ Flutter builds the IPA
2. ✅ DartDosh renames and moves the file
3. ✅ Automatically uploads to App Store Connect
4. ✅ Shows upload progress and result

Example output:

✅ ipa build completed successfully, Boss!
📂 File saved: ~/Desktop/dartdosh-builds/my_app/ipa/prod_1.0.0_100.ipa

📤 Uploading IPA to App Store Connect...
File: ~/Desktop/dartdosh-builds/my_app/ipa/prod_1.0.0_100.ipa
Apple ID: developer@example.com
✅ IPA successfully uploaded to App Store Connect!

Configuration Options

Field	Type	Default	Description
enabled	boolean	false	Enable/disable automatic upload
apple_id	string	""	Your Apple ID email address
app_specific_password	string	""	App-specific password from Apple ID

Troubleshooting

Error: "IPA upload enabled but credentials not set!"

• Make sure you've filled in both apple_id and app_specific_password in config

Error: "xcrun: error: unable to find utility"

• Xcode is not installed or command-line tools are not configured
• Install Xcode from Mac App Store
• Run: xcode-select --install

Error: "Authentication failed"

• App-specific password might be incorrect or expired
• Generate a new app-specific password and update config
• Make sure you're using the correct Apple ID

Error: "Package upload failed"

• Check that your app exists in App Store Connect
• Verify iOS distribution certificate is valid
• Ensure provisioning profile matches the build

Upload is slow or hanging

• This is normal for large IPA files (can take several minutes)
• Check your internet connection
• The tool will show progress and wait for completion

Security Notes

⚠️ Important Security Considerations:

1. Don't commit credentials to git

   • Add build_config.json to .gitignore
   • Never push files containing your app-specific password

2. App-specific passwords are safer

   • They can be revoked individually
   • Don't give access to your main Apple ID password
   • Can be regenerated if compromised

3. Team workflows

   • Each developer should use their own Apple ID and password
   • Or use shared credentials stored in secure password manager
   • Consider using CI/CD secrets for automated builds

Disabling Auto Upload

To disable automatic upload while keeping your credentials:

"ipa_upload": {
  "enabled": false,  // ← Just set to false
  "apple_id": "developer@example.com",
  "app_specific_password": "abcd-efgh-ijkl-mnop"
}

---

Notes

Environment Flags

• Full flags: --production, --staging, --development
• Short flags: -p, -prod, -s, -d, -dev
• All variants work identically

Language Support

• Supported: uz (Uzbek), en (English), ru (Russian), tr (Turkish)
• Default: Uzbek (uz)
• Usage: Use --language or -l flag:

  dartdosh build apk -p --language tr    # Turkish
  dartdosh build apk -p -l uz            # Uzbek
  dartdosh build ipa -s -l en            # English
  dartdosh build aab -d -l ru            # Russian
  

• Or set in config: In dartdosh_config/settings.json:

  {
    "language": "tr"
  }
  

• Unsupported language: Automatically falls back to English with a warning:

  ⚠️  Warning: Language "fr" is not supported. Falling back to English.
     Supported languages: uz (Uzbek), en (English), ru (Russian), tr (Turkish)
  

Build Behavior

• For APK builds, --split automatically adds --split-per-abi
• Any additional flags after the base command are appended automatically
• Build number is incremented before the build starts
• All messages are personalized ("Xo'jayiin" for Uzbek, "Boss" for English/Russian)
• Missing build_config.json is automatically created with default settings
• Progress bar shows real-time build stages in your selected language