Flutter Native Helper #

A powerful CLI tool to automate native Android and iOS configuration in Flutter projects. Stop manually editing AndroidManifest.xml, build.gradle, and Info.plist files!

Features #

• Set Android minSdkVersion - Update build.gradle or build.gradle.kts with a single command
• Add Android Permissions - Inject permissions into AndroidManifest.xml automatically
• Add iOS Plist Keys - Configure Info.plist entries for iOS permissions and settings
• Interactive Permission Selector - Choose from 60+ pre-configured permissions organized by category
• Cross-Platform Support - Add permissions to both Android and iOS simultaneously
• Smart Defaults - Auto-generates iOS usage descriptions for common permissions
• Add Dependencies - Quick wrapper for flutter pub add

Installation #

Global Activation (Recommended) #

dart pub global activate flutter_native_helper

Then use it from any Flutter project:

flutter_native_helper <command>

Local Installation #

Add to your dev_dependencies:

dev_dependencies:
  flutter_native_helper: ^1.0.0

Then run:

dart run flutter_native_helper <command>

Quick Start #

# Set Android minSdkVersion to 23
flutter_native_helper set-sdk --version 23

# Add camera permission to both platforms
flutter_native_helper add-permission --name camera

# Interactive mode - browse and select permissions
flutter_native_helper add-permission --interactive

# List all available permissions
flutter_native_helper list-permissions

Commands #

set-sdk - Set Android minSdkVersion #

Update the minSdkVersion in your Android build.gradle or build.gradle.kts file.

flutter_native_helper set-sdk --version <VERSION>
flutter_native_helper set-sdk -v <VERSION>

Options:

Examples:

# Set to API level 23 (Android 6.0)
flutter_native_helper set-sdk -v 23

# Set to API level 26 (Android 8.0)
flutter_native_helper set-sdk --version 26

Supports:

• Groovy DSL: minSdkVersion 21 or minSdkVersion = 21
• Kotlin DSL: minSdk = 21
• Variable references: minSdkVersion flutter.minSdkVersion

add-permission - Add Permissions #

Add permissions to Android's AndroidManifest.xml and/or iOS's Info.plist.

flutter_native_helper add-permission [OPTIONS]

Options:

Examples:

# Add single permission to both platforms
flutter_native_helper add-permission -n camera

# Add multiple permissions (comma-separated)
flutter_native_helper add-permission -n camera,location,microphone

# Add multiple permissions (multiple flags)
flutter_native_helper add-permission -n camera -n location -n microphone

# Android only
flutter_native_helper add-permission -n internet -p android

# iOS only with custom description
flutter_native_helper add-permission -n camera -p ios -d "We need camera to scan QR codes"

# Interactive mode
flutter_native_helper add-permission -i
flutter_native_helper add-permission --interactive

list-permissions - List Available Permissions #

Display all 60+ available permissions organized by category.

flutter_native_helper list-permissions [OPTIONS]

Options:

Examples:

# List all permissions
flutter_native_helper list-permissions

# Filter by category
flutter_native_helper list-permissions -c camera
flutter_native_helper list-permissions -c bluetooth
flutter_native_helper list-permissions -c location

add-plist - Add iOS Plist Key #

Add custom key-value pairs to iOS Info.plist.

flutter_native_helper add-plist --key <KEY> --value <VALUE> [OPTIONS]

Options:

Examples:

# Add string value
flutter_native_helper add-plist -k CFBundleDisplayName -v "My App"

# Add boolean value
flutter_native_helper add-plist -k UIRequiresFullScreen -v true -t boolean

# Add integer value
flutter_native_helper add-plist -k MinimumOSVersion -v 12 -t integer

add-dep - Add Dependency #

Quick wrapper for flutter pub add.

flutter_native_helper add-dep --name <PACKAGE> [OPTIONS]

Options:

Examples:

# Add regular dependency
flutter_native_helper add-dep -n http

# Add dev dependency
flutter_native_helper add-dep -n mockito -d
flutter_native_helper add-dep --name build_runner --dev

Available Permissions #

Permission Categories #

Common Permission Keys #

Run flutter_native_helper list-permissions to see all 60+ available permissions.

Interactive Mode #

The interactive mode provides a guided experience for selecting permissions:

flutter_native_helper add-permission --interactive

Features:

• Browse permissions by category
• See descriptions for each permission
• Select multiple permissions at once (e.g., 1,3,5 or all)
• Visual indicators for iOS-compatible permissions
• Review selections before applying

Interactive Flow:

╔════════════════════════════════════════════╗
║     PERMISSION SELECTOR                    ║
╚════════════════════════════════════════════╝

Select permissions by category. Enter numbers separated by commas
to select multiple permissions (e.g., 1,3,5).

📁 Select a category (or 0 to finish):

  1. Network & Connectivity (10 permissions)
  2. Camera & Media Capture (3 permissions)
  3. Location Services (3 permissions)
  ...
  0. ✓ Done - Add selected permissions

Enter choice: 2

📋 Camera & Media Capture
   Enter numbers separated by commas, "all" for all, or "back" to go back

  [ ]  1. Camera [iOS]
       Take photos and videos
  [ ]  2. Microphone [iOS]
       Record audio
  [ ]  3. Flashlight
       Control camera flashlight

Enter choices (e.g., 1,3,5 or "all"): 1,2
Added 2 permission(s)

✅ Currently selected (2):
   • Camera (camera)
   • Microphone (microphone)

Add more permissions? (y/n): n

Adding 2 permission(s)...

• Camera (camera)
  ✓ Android: Successfully added permission: android.permission.CAMERA
  ✓ iOS: Successfully added "NSCameraUsageDescription" to Info.plist.
• Microphone (microphone)
  ✓ Android: Successfully added permission: android.permission.RECORD_AUDIO
  ✓ iOS: Successfully added "NSMicrophoneUsageDescription" to Info.plist.

Summary
──────────────────────────────
  Android: 2 added
  iOS: 2 added

Programmatic Usage #

You can also use the library programmatically in your Dart code:

import 'package:flutter_native_helper/flutter_native_helper.dart';

void main() {
  final projectRoot = '/path/to/flutter/project';

  // Android Manager
  final androidManager = AndroidManager(projectRoot);

  // Update minSdkVersion
  final sdkResult = androidManager.updateMinSdk(23);
  switch (sdkResult) {
    case Success(:final message):
      print('Success: $message');
    case Failure(:final error):
      print('Error: $error');
  }

  // Add permission
  final permResult = androidManager.addPermission('android.permission.CAMERA');

  // iOS Manager
  final iosManager = IosManager(projectRoot);

  // Add plist key
  final plistResult = iosManager.addPlistKey(
    'NSCameraUsageDescription',
    'We need camera access for photos',
  );

  // Use permission constants
  final cameraPermission = findPermission('camera');
  if (cameraPermission != null) {
    print('Android: ${cameraPermission.androidPermission}');
    print('iOS Key: ${cameraPermission.iosPermissionKey}');
    print('iOS Description: ${cameraPermission.iosDefaultDescription}');
  }
}

Error Handling #

The CLI provides helpful error messages:

# Not in a Flutter project
$ flutter_native_helper set-sdk -v 23
Error: Not a Flutter/Dart project. Could not find pubspec.yaml in current directory.

# Invalid permission
$ flutter_native_helper add-permission -n invalid_perm
Warning: Permission "invalid_perm" not found. Use --list to see available permissions.

# Missing Android directory
$ flutter_native_helper set-sdk -v 23
Warning: Android directory not found. Run "flutter create ." to add Android support.

Requirements #

• Dart SDK: ^3.0.0
• Flutter project with pubspec.yaml
• For Android commands: android/ directory
• For iOS commands: ios/ directory

Dependencies #

dependencies:
  args: ^2.5.0      # Command-line argument parsing
  xml: ^6.5.0       # XML parsing for AndroidManifest.xml
  path: ^1.9.0      # Cross-platform path handling

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License #

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog #

See CHANGELOG.md for a list of changes.

Support #

If you encounter any issues or have questions:

• Open an issue
• View documentation

Made with Dart for Flutter developers