Qwen-Image-Layered-MRP-MLX/src/mflux/completions/README.md

mflux Shell Completions

This module provides ZSH shell completion support for all mflux CLI commands.

Quick Start

1. Install completions:

   mflux-completions
   

2. Reload your shell:

   exec zsh
   

3. Test it:

   mflux-generate --<TAB>
   

Features

• Auto-completion for all 15 mflux commands: Generate, train, save, upscale, and more
• Smart completions:
  • Model names (dev, schnell, dev-fill, or HuggingFace repos)
  • Quantization levels (3, 4, 6, 8)
  • LoRA styles (storyboard, portrait, etc.)
  • File paths with native completion
  • Common percentage values for battery limit
• Dynamic generation: Completions stay in sync with code changes
• Mutually exclusive options: Properly handles -m/--model style options

Installation

Automatic Installation

The simplest way is to let mflux-completions auto-detect the best location:

mflux-completions

Custom Directory

Install to a specific directory:

mflux-completions --dir ~/.config/zsh/completions

Update Existing Installation

Update an existing completion file:

mflux-completions --update

Troubleshooting

Check Installation

Verify that completions are properly installed:

mflux-completions --check

This will:

• Check if the completion file exists in your $fpath
• Verify that compinit is available
• Provide troubleshooting steps if needed

Common Issues

1. Completions not working after installation:

   • Start a new shell: exec zsh

2. Completions not updated after mflux upgrade:

   • Update completions: mflux-completions --update
   • Then force reload: compinit -u

3. Permission denied:

   • Use --dir to specify a user-writable directory

4. Completion shows } or other artifacts:

   • Update to the latest version: mflux-completions --update

For Zsh-specific configuration issues (fpath, compinit, etc.), please refer to the official Zsh documentation.

Manual Installation

If automatic installation fails:

# Generate completion script
mflux-completions --print > _mflux

# Move to a directory in your $fpath
mkdir -p ~/.zsh/completions
mv _mflux ~/.zsh/completions/

# Restart your shell
exec zsh

How It Works

The completion system:

1. Introspects argparse: Dynamically extracts all command-line options from the parsers
2. Generates ZSH functions: Creates completion functions for each mflux command
3. Provides context-aware completions: Different completion strategies based on argument type
4. Handles special cases: Custom completions for models, LoRA styles, etc.

Development

Adding New Commands

When adding a new mflux CLI command:

1. Create the command with argparse as usual
2. Add it to the commands list in generator.py
3. Add the parser creation logic to create_parser_for_command()
4. Completions will be automatically generated!

Testing Completions

Test the generator without installing:

python -m mflux.completions.generator

File Structure

• generator.py: Core logic for generating ZSH completion scripts
• install.py: Installation utility with user-friendly CLI
• README.md: This documentation

Platform Support

Currently supports ZSH (the default macOS shell since 2019). Supporting other shells is possible but is considered out of scope for the official repository.