CLI Tools and Commands

# All Flask-AppBuilder CLI commands are accessed via:
# flask fab <command> [options]

# User Management Commands
flask fab create-admin
"""
Create application administrator user interactively.

Options:
--username: Admin username (interactive if not provided)
--firstname: Admin first name  
--lastname: Admin last name
--email: Admin email address
--password: Admin password (secure prompt if not provided)

Usage:
flask fab create-admin
flask fab create-admin --username admin --email admin@company.com
"""

flask fab create-user  
"""
Create regular application user interactively.

Options:
--username: Username
--firstname: First name
--lastname: Last name  
--email: Email address
--password: Password
--role: User role name

Usage:
flask fab create-user
flask fab create-user --username jdoe --role Public
"""

flask fab reset-password
"""
Reset user password interactively.

Options:
--username: Username to reset password for

Usage:
flask fab reset-password
flask fab reset-password --username jdoe
"""

flask fab list-users
"""
List all application users with details.

Options:
--verbose: Show detailed user information

Usage:
flask fab list-users
flask fab list-users --verbose
"""

# Database Commands
flask fab create-db
"""
Create all database tables and initial data.
Equivalent to db.create_all() with Flask-AppBuilder setup.

Usage:
flask fab create-db
"""

# Security Management Commands  
flask fab create-permissions
"""
Create all permissions for registered views and menus.
Scans all registered views and creates corresponding permissions.

Usage:
flask fab create-permissions
"""

flask fab security-cleanup
"""
Remove unused permissions and roles from database.
Cleans up orphaned permissions that no longer have associated views.

Options:
--dry-run: Show what would be cleaned up without making changes

Usage:
flask fab security-cleanup
flask fab security-cleanup --dry-run
"""

flask fab security-converge  
"""
Migrate permissions to new naming conventions.
Updates permission names to match current view structure.

Options:
--dry-run: Show migration plan without executing

Usage:  
flask fab security-converge
flask fab security-converge --dry-run
"""

# Role Management Commands
flask fab export-roles
"""
Export roles and permissions to JSON file.

Options:
--filename: Output filename (default: roles_export.json)

Usage:
flask fab export-roles
flask fab export-roles --filename my_roles.json
"""

flask fab import-roles
"""
Import roles and permissions from JSON file.

Options:  
--filename: Input filename (default: roles_export.json)

Usage:
flask fab import-roles  
flask fab import-roles --filename my_roles.json
"""

# Application Information
flask fab version
"""
Show Flask-AppBuilder version information.

Usage:
flask fab version
"""

flask fab list-views
"""
List all registered views with details.

Options:
--verbose: Show detailed view information including permissions

Usage:
flask fab list-views
flask fab list-views --verbose
"""

# Development Commands
flask fab create-app
"""
Create new Flask-AppBuilder application skeleton.

Options:
--name: Application name
--engine: Database engine (SQLAlchemy, MongoEngine)  

Usage:
flask fab create-app --name MyApp
flask fab create-app --name MyApp --engine SQLAlchemy
"""

flask fab create-addon
"""
Create Flask-AppBuilder addon skeleton.

Options:
--name: Addon name

Usage:
flask fab create-addon --name MyAddon
"""

# Static Files Management
flask fab collect-static
"""
Copy static files from Flask-AppBuilder to application static folder.

Options:
--target: Target directory for static files

Usage:
flask fab collect-static
flask fab collect-static --target /path/to/static
"""

# Internationalization Commands
flask fab babel-extract
"""
Extract translatable strings for internationalization.

Options:
--target: Target directory for translation files
--config: Babel configuration file

Usage:
flask fab babel-extract
flask fab babel-extract --target translations --config babel.cfg
"""

flask fab babel-compile
"""
Compile translation files for production use.

Options:
--target: Translation files directory

Usage:
flask fab babel-compile  
flask fab babel-compile --target translations
"""

# Initial application setup workflow
"""
1. Create database tables
2. Create admin user  
3. Create initial permissions
"""

# Step 1: Create database
flask fab create-db

# Step 2: Create admin user
flask fab create-admin --username admin --email admin@company.com

# Step 3: Create permissions for all views
flask fab create-permissions

# User management workflow
"""
Adding new users and managing existing ones
"""

# Create new user with specific role
flask fab create-user \
    --username employee1 \
    --firstname John \
    --lastname Doe \  
    --email john.doe@company.com \
    --role Employee

# List all users to verify
flask fab list-users --verbose

# Reset password for user  
flask fab reset-password --username employee1

# Security maintenance workflow
"""
Regular security cleanup and updates
"""

# Check what permissions would be cleaned up
flask fab security-cleanup --dry-run

# Clean up unused permissions
flask fab security-cleanup

# Update permission names to new format
flask fab security-converge --dry-run
flask fab security-converge

# Export current roles for backup
flask fab export-roles --filename backup_roles.json

# Role management workflow  
"""
Backing up and restoring role configurations
"""

# Export roles from production
flask fab export-roles --filename prod_roles.json

# Import roles to development environment
flask fab import-roles --filename prod_roles.json

# Verify roles were imported correctly
flask fab list-users --verbose

# Development workflow
"""
Setting up new development environment
"""

# Create new application skeleton
flask fab create-app --name MyNewApp --engine SQLAlchemy

# Create addon for custom functionality  
flask fab create-addon --name MyCustomAddon

# Collect static files for deployment
flask fab collect-static --target /var/www/myapp/static

# Internationalization workflow
"""
Managing translations for multi-language support
"""

# Extract translatable strings from templates and code
flask fab babel-extract --target translations --config babel.cfg

# Compile translation files for production
flask fab babel-compile --target translations

# Application information and debugging
"""
Getting information about application state
"""

# Check Flask-AppBuilder version
flask fab version

# List all registered views and their permissions  
flask fab list-views --verbose

# List all users and their roles
flask fab list-users --verbose

# Creating custom CLI commands
from flask.cli import with_appcontext
from flask_appbuilder.cli import cli
import click

@cli.command()
@click.option('--format', default='json', help='Export format (json, csv)')
@click.option('--output', help='Output filename')
@with_appcontext  
def export-data(format, output):
    """Export application data in specified format."""
    from flask import current_app
    
    if format == 'json':
        export_to_json(output or 'data_export.json')
    elif format == 'csv':
        export_to_csv(output or 'data_export.csv')
    else:
        click.echo(f"Unsupported format: {format}")

@cli.command()
@click.option('--days', default=30, help='Days of data to keep')  
@with_appcontext
def cleanup-logs(days):
    """Clean up old log entries."""
    from datetime import datetime, timedelta
    
    cutoff_date = datetime.now() - timedelta(days=days)
    
    # Custom cleanup logic
    deleted_count = cleanup_old_logs(cutoff_date)
    click.echo(f"Deleted {deleted_count} log entries older than {days} days")

@cli.command()
@click.argument('model_name')
@click.option('--count', default=10, help='Number of records to generate')
@with_appcontext
def generate-test-data(model_name, count):
    """Generate test data for specified model."""
    model_class = get_model_by_name(model_name)
    
    if not model_class:
        click.echo(f"Model '{model_name}' not found")
        return
    
    generated_count = generate_fake_data(model_class, count)
    click.echo(f"Generated {generated_count} test records for {model_name}")

@cli.command()
@with_appcontext  
def init-sample-data():
    """Initialize application with sample data."""
    click.echo("Creating sample data...")
    
    # Create sample departments
    create_sample_departments()
    
    # Create sample users  
    create_sample_users()
    
    # Create sample products
    create_sample_products()
    
    click.echo("Sample data created successfully!")

# Usage of custom commands
"""
flask fab export-data --format json --output backup.json
flask fab cleanup-logs --days 7  
flask fab generate-test-data Person --count 50
flask fab init-sample-data
"""

# Advanced custom command with progress bar
@cli.command()
@click.option('--batch-size', default=1000, help='Batch size for processing')
@with_appcontext
def migrate-legacy-data(batch_size):
    """Migrate data from legacy system."""
    import tqdm
    
    # Get total count for progress bar
    total_records = get_legacy_record_count()
    
    with tqdm.tqdm(total=total_records) as pbar:
        offset = 0
        
        while offset < total_records:
            # Process batch of records
            batch = get_legacy_records(offset, batch_size)
            process_legacy_batch(batch)
            
            offset += len(batch)
            pbar.update(len(batch))
    
    click.echo(f"Migration completed: {total_records} records processed")

# Command with confirmation prompt
@cli.command()
@click.option('--force', is_flag=True, help='Skip confirmation prompt')
@with_appcontext
def reset-database(force):
    """Reset database to initial state (WARNING: destructive)."""
    if not force:
        if not click.confirm('This will delete all data. Are you sure?'):
            click.echo('Operation cancelled.')
            return
    
    # Drop all tables
    db.drop_all()
    
    # Recreate tables  
    db.create_all()
    
    # Create default admin user
    create_default_admin()
    
    click.echo('Database reset completed.')

# Command group for related operations
@cli.group()
def backup():
    """Backup and restore operations."""
    pass

@backup.command()
@click.option('--output-dir', default='backups', help='Backup directory')
def create(output_dir):
    """Create full application backup."""
    import os
    from datetime import datetime
    
    timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
    backup_path = os.path.join(output_dir, f'backup_{timestamp}')
    
    create_full_backup(backup_path)
    click.echo(f'Backup created: {backup_path}')

@backup.command()
@click.argument('backup_path')  
@click.option('--force', is_flag=True, help='Overwrite existing data')
def restore(backup_path, force):
    """Restore from backup."""
    if not force:
        if not click.confirm('This will overwrite existing data. Continue?'):
            return
    
    restore_from_backup(backup_path)
    click.echo('Restore completed successfully.')

# Usage:
# flask fab backup create --output-dir /path/to/backups
# flask fab backup restore backup_20231201_143022 --force

# DEPRECATED: fabmanager console script 
# Use 'flask fab' commands instead

# Old fabmanager commands (DEPRECATED):
"""
fabmanager create-admin --app myapp
fabmanager create-user --app myapp
fabmanager create-db --app myapp
fabmanager reset-password --app myapp
fabmanager list-users --app myapp
fabmanager create-permissions --app myapp
fabmanager security-cleanup --app myapp
fabmanager version --app myapp
"""

# NEW: Flask CLI commands (RECOMMENDED):
"""  
flask fab create-admin
flask fab create-user
flask fab create-db
flask fab reset-password  
flask fab list-users
flask fab create-permissions
flask fab security-cleanup
flask fab version
"""

# Migration guide from fabmanager to flask fab:
"""
1. Replace 'fabmanager' with 'flask fab'
2. Remove '--app myapp' parameter (use FLASK_APP environment variable)
3. Set FLASK_APP environment variable:
   export FLASK_APP=myapp.py
   
4. Run new commands:
   flask fab create-admin (instead of fabmanager create-admin --app myapp)
"""

# Environment setup for Flask CLI:
"""
# Linux/Mac:
export FLASK_APP=app.py
export FLASK_ENV=development

# Windows:  
set FLASK_APP=app.py
set FLASK_ENV=development

# Or use .flaskenv file:
echo "FLASK_APP=app.py" > .flaskenv
echo "FLASK_ENV=development" >> .flaskenv
"""

# Batch migration script example:
"""
#!/bin/bash
# migrate_to_flask_cli.sh

# Set Flask app
export FLASK_APP=myapp.py

# Old fabmanager commands -> New flask fab commands
echo "Migrating CLI commands..."

# Replace fabmanager calls in scripts:
sed -i 's/fabmanager create-admin --app myapp/flask fab create-admin/g' deploy.sh
sed -i 's/fabmanager create-db --app myapp/flask fab create-db/g' deploy.sh
sed -i 's/fabmanager create-permissions --app myapp/flask fab create-permissions/g' deploy.sh

echo "Migration completed. Update your documentation and scripts."
"""

# Accessing Flask-AppBuilder components in CLI commands
from flask.cli import with_appcontext
from flask import current_app

@cli.command()
@with_appcontext
def sync-users():
    """Sync users from external system."""
    # Access AppBuilder instance
    appbuilder = current_app.appbuilder
    
    # Access security manager
    security_manager = appbuilder.sm
    
    # Access database session
    db_session = appbuilder.get_session
    
    # Sync users from LDAP/Active Directory
    external_users = get_external_users()
    
    for ext_user in external_users:
        # Check if user exists
        user = security_manager.find_user(username=ext_user['username'])
        
        if not user:
            # Create new user
            user = security_manager.add_user(
                username=ext_user['username'],
                first_name=ext_user['first_name'],
                last_name=ext_user['last_name'], 
                email=ext_user['email'],
                role=security_manager.find_role('Employee')
            )
            click.echo(f"Created user: {user.username}")
        else:
            # Update existing user
            user.email = ext_user['email']
            security_manager.update_user(user)
            click.echo(f"Updated user: {user.username}")

# Command with database operations
@cli.command()
@click.option('--model', help='Model name to analyze')
@with_appcontext
def analyze-data(model):
    """Analyze application data."""
    appbuilder = current_app.appbuilder
    
    if model:
        # Analyze specific model
        model_class = get_model_by_name(model)
        if model_class:
            analyze_model_data(model_class, appbuilder.get_session)
    else:
        # Analyze all models
        for model_class in get_all_models():
            analyze_model_data(model_class, appbuilder.get_session)

# Command with view registration
@cli.command()
@with_appcontext  
def register-views():
    """Register additional views dynamically."""
    appbuilder = current_app.appbuilder
    
    # Register new views
    appbuilder.add_view(
        DynamicView,
        "Dynamic View",
        icon="fa-cog",
        category="Dynamic"
    )
    
    # Update permissions  
    appbuilder.add_permissions(update_perms=True)
    
    click.echo("Dynamic views registered successfully")

# Command with configuration management
@cli.command()
@click.option('--key', help='Configuration key to show')
@with_appcontext
def show-config(key):
    """Show application configuration."""
    config = current_app.config
    
    if key:
        if key in config:
            click.echo(f"{key} = {config[key]}")
        else:
            click.echo(f"Configuration key '{key}' not found")
    else:
        # Show all Flask-AppBuilder related config
        fab_keys = [k for k in config.keys() if k.startswith(('FAB_', 'AUTH_'))]
        
        for config_key in sorted(fab_keys):
            click.echo(f"{config_key} = {config[config_key]}")

# Command with menu management
@cli.command()
@with_appcontext
def rebuild-menu():
    """Rebuild application menu structure."""
    appbuilder = current_app.appbuilder
    
    # Clear existing menu
    appbuilder.menu.clear()
    
    # Rebuild menu from configuration
    rebuild_menu_from_config(appbuilder)
    
    click.echo("Menu structure rebuilt successfully")

# Usage examples:
"""
flask fab sync-users
flask fab analyze-data --model Person
flask fab register-views  
flask fab show-config --key AUTH_TYPE
flask fab rebuild-menu
"""