udara_cli 1.0.0

A CLI tool for managing whitelabel Flutter projects with multi-client support

Udara CLI (Private)

A self-contained tool to manage and build Flutter projects for different clients with whitelabel support.

---

Installation 📦

This is a private repository. To install the CLI, you must have access to this repository and authenticate using SSH (recommended) or a Personal Access Token.

Using SSH (Recommended)

Make sure you have added your SSH key to your GitHub account.

dart pub global activate --source git [e-mail]:your-username/udara_cli.git

Using a Personal Access Token (PAT)

Generate a PAT with the repo scope.

dart pub global activate --source git https://<YOUR_TOKEN>@github.com/your-username/udara_cli.git

---

Getting Started 🎯

After installing the CLI, you need to initialize your project. The CLI provides a guided setup process:

1. Initial Project Setup

Run the setup command to configure your project dependencies and create necessary configuration files:

udara_cli setup

This will:

• Install required dependencies (rename, flutter_launcher_icons, splash_master)
• Create flutter_launcher_icons.yaml configuration file
• Add splash_master configuration to your pubspec.yaml
• Set up the basic project structure

2. Initialize Client Directories

Create your client directories with pre-configured templates:

# Create one or more clients (comma-separated)
udara_cli setup --clients default,clientA,clientB

This will create the complete directory structure for each client, including:

• Client folder in clients/[name]/
• Environment files (.env and .env_test)
• Placeholder logo files
• Fonts directory
• Client-specific README

Note: Always include a default client as a fallback configuration.

3. Optional: Configure Slack Notifications

If you want build notifications sent to Slack:

udara_cli setup --notify

You'll need:

• A Slack Bot Token (starts with xoxb-)
• Bot token scopes: chat:write, files:write, channels:read

4. List Available Clients

To see all configured clients:

udara_cli list

Other Setup Options

# Reset all CLI configurations
udara_cli setup --reset

# Get detailed help on setup command
udara_cli setup --help

---

Project Structure 📁

Your Flutter project must follow this structure for the CLI to work properly:

your_flutter_project/
├── clients/
│   ├── default/
│   │   ├── assets/
│   │   ├── fonts/ (optional)
│   │   └── .env
│   │
│   ├── clientA/
│   │   ├── assets/
│   │   ├── fonts/ (optional)
│   │   ├── .env
│   │   └── .env_test
│   └── clientB/
│       ├── assets/
│       ├── fonts/ (optional)
│       ├── .env
│       └── .env_test
├── assets/
│   └── branding/
│       └── default/
│           ├── default_icon.png
│           ├── default_logo.png
│           └── default_icon_small.png
└── pubspec.yaml

---

Environment Configuration 🔧

Important: flutter_dotenv Dependency

This tool is heavily dependent on environment files and requires the flutter_dotenv package. Make sure to add it to your pubspec.yaml:

dependencies:
  flutter_dotenv: ^5.1.0  # or latest version

Environment File Initialization

You must have a default/base client folder and environment file that acts as a fallback. Initialize the environment in your Flutter app as follows:

import 'package:flutter_dotenv/flutter_dotenv.dart';

// In your main() function or initialization code
const envFile = String.fromEnvironment(
  'CLIENT_ENV',
  defaultValue: 'clients/your_default_client_folder_name/.env',
);

await dotenv.load(fileName: envFile);

This ensures that:

• A default environment is always loaded if no client is specified
• Client-specific environments can override the default when building
• Your app has access to all environment variables at runtime

Client-Specific Variables

Environment files can store client-specific variables for use throughout your application and whitelabel variants. Access these variables in your Flutter code using:

dotenv.env['VARIABLE_NAME']

How It Works

The whitelabel system operates in two phases:

1. Build Time: When you run the CLI with a specific --client flag, it swaps out the environment files and configures the build process accordingly. The CLI:

   • Loads the client-specific .env file from clients/[client_name]/.env
   • Copies client-specific assets (icons, logos, fonts) to the appropriate locations
   • Updates the app's bundle ID, app name, and other build configurations
   • Passes the environment file path to Flutter via the CLIENT_ENV compile-time constant

2. Runtime: Once the app is running, flutter_dotenv reads the environment variables that were configured at build time. This allows you to:

   • Access build configurations that were set during compilation
   • Store and retrieve client-specific UI variables (feature flags, theme colors, API endpoints)
   • Drive your whitelabel logic dynamically based on these variables
   • Maintain a single codebase that adapts to different client requirements

Example Use Cases:

• Feature flags: SHOW_SIGN_UP=true to enable/disable signup for specific clients
• API configuration: Different API_BASE_URL values per client
• Theme customization: Client-specific PRIMARY_COLOR and SECONDARY_COLOR values
• Content variations: Different assets, logos, or branding elements per client

Required Environment Variables

Each client must have corresponding environment files in their respective clients/client_name/ directory with the following structure:

# App Names for Different Environments
APP_NAME_DEV="Your App Dev"
APP_NAME_STAGING="Your App Staging"
APP_NAME_PROD="Your App"

# Bundle/Package Identifier
BUNDLE_ID="com.yourcompany.yourapp"

# Asset Paths (relative to project root)
ASSETS_PATH="clients/default/"
APP_ICON_PATH="assets/branding/default/default_icon.png"
APP_LOGO_PATH="assets/branding/default/default_logo.png"
APP_LOGO_ICON_PATH="assets/branding/default/default_icon_small.png"

Optional Theme Variables

These variables can be used to modify app colors based on the environment:

# Theme Colors (hex format with 0x prefix)
PRIMARY_COLOR="0xFFF26333"
BACKGROUND_COLOR="0XFFF9F9F9"
SECONDARY_COLOR="0xFF81BF42"
TERTIARY_COLOR=""

# Feature Modifications
SHOW_HOME_TEXT=true
SHOW_SIGN_UP=true
ENABLE_LION=true
ONBOARDING_IMAGES=

Example Environment Files

clients/default/.env:

APP_NAME_DEV="Default App Dev"
APP_NAME_STAGING="Default App Staging"
APP_NAME_PROD="Default App"
BUNDLE_ID="com.company.defaultapp"
ASSETS_PATH="clients/default/"
APP_ICON_PATH="assets/branding/default/default_icon.png"
APP_LOGO_PATH="assets/branding/default/default_logo.png"
APP_LOGO_ICON_PATH="assets/branding/default/default_icon_small.png"
PRIMARY_COLOR="0xFFF26333"
BACKGROUND_COLOR="0XFFF9F9F9"
SECONDARY_COLOR="0xFF81BF42"
SHOW_HOME_TEXT=true
SHOW_SIGN_UP=true
ENABLE_LION=true

clients/clientA/.env:

APP_NAME_DEV="Client A App Dev"
APP_NAME_STAGING="Client A App Staging"
APP_NAME_PROD="Client A App"
BUNDLE_ID="com.company.clientaapp"
ASSETS_PATH="clients/clientA/"
APP_ICON_PATH="assets/branding/clientA/clientA_icon.png"
APP_LOGO_PATH="assets/branding/clientA/clientA_logo.png"
APP_LOGO_ICON_PATH="assets/branding/clientA/clientA_icon_small.png"
PRIMARY_COLOR="0xFF2196F3"
BACKGROUND_COLOR="0XFFFFFFFF"
SECONDARY_COLOR="0xFF4CAF50"
SHOW_HOME_TEXT=false
SHOW_SIGN_UP=true
ENABLE_LION=false

---

Usage 🚀

Basic Build Command

udara_cli build --client clientA --platform android

Build Options

• --client or -c: Required - The name of the client to build for (e.g., default, clientA)
• --platform or -p: Target platform (android or ios) - defaults to android
• --type or -t: Android build type (aab or apk) - defaults to aab
• --test: Build using the test environment (.env_test)

Examples

# Build Android AAB for clientA
udara_cli build --client clientA --platform android --type aab

# Build Android APK for clientB
udara_cli build --client clientB --platform android --type apk

# Build iOS for default client
udara_cli build --client default --platform ios

# Build with test environment
udara_cli build --client clientA --platform android --test

---

Build Process 🔄

The CLI performs the following steps:

1. Validation & Setup: Validates client exists and loads environment variables
2. Project Configuration:
   • Backs up and modifies pubspec.yaml
   • Handles client-specific fonts
   • Copies client assets
3. Build Commands:
   • Runs flutter pub get
   • Sets bundle ID and app name
   • Generates launcher icons
   • Creates splash screens
   • Fixes platform-specific issues
4. Final Build: Builds the app with client-specific configuration
5. Cleanup: Restores original project state

---

Prerequisites 📋

• Flutter SDK installed and configured
• Dart SDK (comes with Flutter)
• Access to this private repository
• Proper project structure as outlined above
• Required dependencies in pubspec.yaml:
  • flutter_dotenv (required for environment variable management)
  • flutter_launcher_icons
  • splash_master
  • rename

---

Troubleshooting 🔧

Common Issues

1. Client not found: Ensure the client directory exists in clients/ and has the corresponding .env file in that directory
2. Missing assets: Check that all required asset paths exist and are correctly specified in the environment file
3. Build failures: Ensure all Flutter dependencies are properly installed and the project builds normally before using the CLI
4. Environment variables not loading: Verify that flutter_dotenv is installed and properly initialized in your app's main function

Getting Help

For issues specific to this CLI tool, please check the repository issues or contact the development team.