Python utility for creating wrapper scripts that launch Flatpak applications by simplified names (e.g., firefox instead of flatpak run org.mozilla.firefox).
Creates wrapper scripts that intelligently choose between:
- System packages (native applications)
- Flatpak applications (sandboxed)
- User-defined preferences
# Install with uv (recommended)
uv tool install fplaunchwrapper
# Or with pip
pip install fplaunchwrapper# Generate wrappers for all Flatpak apps
fplaunch generate ~/bin
# List wrappers
fplaunch list
# Set preference
fplaunch set-pref firefox flatpak
# Launch
firefox # Uses your saved preferenceAvailable executables
The project installs a main user-facing CLI and several helper standalone executables. Use the main CLI in interactive workflows and the standalone helpers when invoking specific entrypoints or from system packaging/automation.
- fplaunch — primary CLI (recommended for interactive use):
fplaunch generate,fplaunch list, etc. - fplaunch- — packaging-friendly helper executables (e.g.,
fplaunch-generate,fplaunch-systemd) that map directly to individual entry points and are sometimes referenced by packagers and man pages.
fplaunch generate [DIR] # Generate wrappers
fplaunch list # List all wrappers
fplaunch set-pref APP PREF # Set launch method (system/flatpak)
fplaunch remove APP # Remove wrapper
fplaunch launch APP # Launch application
fplaunch monitor # Start monitoring daemon
fplaunch config # Show configuration
fplaunch systemd enable # Set up automatic updatesAll commands support --emit for dry-run mode.
fplaunch profiles list # List profiles
fplaunch profiles create work # Create profile
fplaunch profiles switch work # Switch profile
fplaunch presets list # List permission presets
fplaunch presets add gaming --permissions "--device=dri" "--socket=pulseaudio"fplaunch systemd enable # Enable automatic updates
fplaunch systemd disable # Disable
fplaunch systemd status # Check statusEach wrapper supports:
firefox --fpwrapper-help # Help
firefox --fpwrapper-info # App info
firefox --fpwrapper-config-dir # Config directory
firefox --fpwrapper-sandbox-info # Sandbox details
firefox --fpwrapper-launch flatpak # Force method
firefox --fpwrapper-set-override flatpak # Set preferenceTerminal: Full functionality with prompts and menus Desktop files/scripts: Auto-bypass to system command, silent execution
Force interactive mode:
FPWRAPPER_FORCE=interactive firefox --fpwrapper-help
firefox --fpwrapper-force-interactive --helpEdit ~/.config/fplaunchwrapper/config.toml:
bin_dir = "/home/user/bin"
log_level = "INFO"
[global_preferences]
launch_method = "auto"
[app_preferences.firefox]
launch_method = "flatpak"
custom_args = ["--new-window"]Test commands without making changes:
fplaunch generate --emit ~/bin
fplaunch set-pref firefox flatpak --emit
fplaunch systemd enable --emitAdd --emit-verbose to see file contents.
git clone https://github.com/dtg01100/fplaunchwrapper.git
cd fplaunchwrapper
./setup-dev.sh
# Run tests (3,058 tests, 99% coverage)
uv run pytest tests/python/ -q
# Format code
uv run ruff format lib/ tests/python/
# Lint
uv run ruff check lib/
uv run flake8 lib/ tests/python/fplaunchwrapper/
├── lib/ # Python package
├── tests/ # Test suite
├── docs/ # Documentation
├── examples/ # Usage examples
└── pyproject.toml # Package config
- Python 3.10+ (tested through 3.13)
- Flatpak 1.0+
- Linux: systemd or cron support
MIT