⚡ Qyro CLI

The official developer CLI and project orchestrator for the Qyro desktop and mobile application ecosystem.

---

✨ Features

• ⚡ Unified Multi-Framework Support: Scaffold projects for PySide6, PyQt6, PyQt5, PySide2, Kivy, or Tkinter.
• 🔄 Smart Template Resolution: Uses template providers with fallback support for robust initialization workflows.
• ❄️ Packaging & Freezing Ready: Native desktop freezing with PyInstaller.
• 📦 Distribution Bundling: Platform-aware bundling for DMG, NSIS, and Linux package formats.
• 🔐 Code Signing & Notarization: Windows Authenticode and macOS signing with optional notarization and stapling.
• ✅ Release Preflight Checks: Validate dependencies and release.json paths and options before packaging.
• 🧹 Artifact Cleanup: Clean build outputs and optional release outputs with one command.

---

Compatibility

The table below reports validation results for the complete desktop workflow:

init → start → build → bundle

Table last validated: 2026-10-02
CI run: #37052349565

Framework	Platform	Python 3.10	Python 3.11	Python 3.12	Python 3.13	Python 3.14	Notes
PySide6	Windows	✅	✅	✅	✅	✅	Full pass
PySide6	macOS	✅	✅	✅	✅	✅	Full pass
PySide6	Linux	✅	✅	✅	✅	✅	Full pass
PySide2	Linux	—	—	—	—	—	No CI coverage
PySide2	Windows	—	—	—	—	—	No CI coverage
PySide2	macOS	—	—	—	—	—	No CI coverage
PyQt6	Windows	✅	✅	✅	✅	✅	Full pass
PyQt6	macOS	✅	✅	✅	✅	✅	Full pass
PyQt6	Linux	✅	✅	✅	✅	✅	Full pass
PyQt5	Windows	✅	✅	✅	✅	✅	Full pass
PyQt5	macOS	✅	✅	✅	✅	✅	Full pass
PyQt5	Linux	✅	✅	✅	✅	✅	Full pass
Kivy	Windows	✅	✅	✅	✅	❌	Python 3.14 failed at install
Kivy	macOS	✅	✅	✅	✅	✅	Full pass
Kivy	Linux	✅	✅	✅	✅	✅	Full pass
Tkinter	Windows	✅	✅	✅	✅	✅	Full pass
Tkinter	macOS	✅	✅	✅	✅	✅	Full pass
Tkinter	Linux	✅	✅	✅	✅	✅	Full pass

Legend:

• ✅ FULL PASS: all four workflow stages completed.
• ❌ FAIL: validation was attempted and failed.
• — NOT TESTED: no validation result is available.

Known failure:

• Kivy · Python 3.14 · Windows: failed during install.

Compatibility results are specific to the operating system, Python version, framework, dependency state, and CI environment used during testing.

---

🚀 Installation

Supported desktop installation

# Using pip
pip install "qyro-cli[desktop]"

# Using Poetry
poetry add qyro-cli -E desktop

The core package can also be installed without the desktop extra:

# Using pip
pip install qyro-cli

# Using Poetry
poetry add qyro-cli

Experimental mobile installation

# Using pip
pip install "qyro-cli[mobile]"

# Using Poetry
poetry add qyro-cli -E mobile

The [all] extra includes experimental mobile dependencies and is not recommended for production use:

# Using pip
pip install "qyro-cli[all]"

# Using Poetry
poetry add qyro-cli -E all

---

Qyro Settings Builder

The Qyro Settings Builder provides a visual interface for preparing application, platform-specific, and release configuration files used by Qyro projects.

It helps simplify:

• Application settings.
• Platform-specific settings.
• Release and packaging options.
• Distribution metadata.

Open the builder:

Open Qyro Settings Builder

Generated files can be placed in the project's settings/ directory and reviewed before running Qyro CLI commands.

---

💻 Quick Start

Qyro CLI provides the following desktop workflow:

1. Initialize a project from a framework template.
2. Run the application from source.
3. Freeze the application into executable artifacts.
4. Bundle the artifacts for distribution.
5. Optionally sign and notarize the release.

1) Initialize a project

qyro init --name my-app

You can preselect a binding and template version:

qyro init \
  --name my-app \
  --binding PySide6 \
  --template-version 1.0.x

For non-interactive initialization:

qyro init \
  --name my-app \
  --target-platform desktop \
  --binding PySide6 \
  --app-name "My App" \
  --version 1.0.0 \
  --author "Your Name" \
  --addon pydux \
  --addon requests \
  --yes

Supported initialization options:

• --target-platform: desktop, x86_64, apple-silicon, iphone, or android.
• --app-name: Application display name.
• --version: Semantic application version.
• --author: Author name.
• --addon: Optional dependency add-on. Repeatable. Supported values: hotrl, pydux, sentry-sdk, and requests.
• --bundle-id: Bundle identifier for iPhone or Apple Silicon templates.
• -y, --yes: Skip the confirmation prompt.

Notes:

• desktop maps to the desktop template target.
• If these flags are omitted, qyro init uses the interactive wizard.
• Mobile targets are experimental and are not part of the supported desktop workflow.

Supported bindings:

• PySide6
• PyQt6
• PyQt5
• PySide2
• Kivy
• Tkinter

2) Run from source

Run this command from the generated project directory:

cd my-app
qyro start

qyro start currently runs the application from source without release flag variants.

3) Freeze executable artifacts

Run these commands from a Qyro project directory:

# Default desktop target with the release profile
qyro build

# Single executable
qyro build --onefile

# Equivalent mode syntax
qyro build --mode onefile

# Platform target override
qyro build --target mac
qyro build --target windows
qyro build --target linux

# Additional controls
qyro build --debug --console --uac --clean --interactive

4) Bundle for distribution

Run these commands from a Qyro project directory:

# Select the default format for the host operating system
qyro bundle

# Explicit platform and format
qyro bundle --platform mac --format dmg
qyro bundle --platform windows --format nsis
qyro bundle --platform linux --format tar.gz
qyro bundle --platform linux --format deb
qyro bundle --platform linux --format rpm
qyro bundle --platform linux --format arch

# Include an additional ZIP and use a custom output directory
qyro bundle --zip --release-dir release

Validate before packaging

qyro bundle --check

This validates dependencies and release settings, such as DMG backgrounds and extra files, without generating artifacts.

---

Windows NSIS customization

When packaging with:

qyro bundle --platform windows --format nsis

you can customize installer behavior using bundle.nsis in settings/release.json.

Supported options:

• bundle.nsis.icons.install: Installer icon path (.ico).
• bundle.nsis.icons.uninstall: Uninstaller icon path (.ico).
• bundle.nsis.welcome_bitmap: Welcome/finish bitmap path.
• bundle.nsis.install_location: programfiles64, programfiles32, or appdata.
• bundle.nsis.execution_level: highest, admin, or user.

Defaults:

• install_location: programfiles64
• execution_level: highest
• icons.install: resources/base/icons/install.ico if the file exists.
• icons.uninstall: resources/base/icons/uninstall.ico if the file exists.
• welcome_bitmap: not set by default.

Example:

{
  "bundle": {
    "nsis": {
      "icons": {
        "install": "resources/base/icons/install.ico",
        "uninstall": "resources/base/icons/uninstall.ico"
      },
      "welcome_bitmap": "resources/base/welcome.bmp",
      "install_location": "programfiles64",
      "execution_level": "highest"
    }
  }
}

Validate NSIS options before generating the installer:

qyro bundle --check --platform windows --format nsis

---

Clean outputs

Run these commands from a Qyro project directory:

# Clean the freeze directory
qyro clean

# Also clean the release directory
qyro clean --release

---

Sign compiled artifacts

Run these commands from a Qyro project directory:

# Preflight validation only
qyro sign --check --platform windows
qyro sign --check --platform mac

# Sign frozen binaries or application bundles
qyro sign --platform windows
qyro sign --platform mac

# macOS notarization flow
qyro sign \
  --platform mac \
  --notarize \
  --staple \
  --keychain-profile "QYRO-NOTARY"

# Skip Gatekeeper assessment if required
qyro sign \
  --platform mac \
  --notarize \
  --staple \
  --no-assess

---

Signing guide

Use settings/release.json to configure signing.

Windows signing

Requirements:

• Windows host with signtool available in PATH.
• Code-signing certificate file, such as .pfx.
• Certificate password supplied through settings/secrets.json.

Example settings/release.json:

{
  "sign": {
    "windows": {
      "certificate": "src/sign/windows/certificate.pfx",
      "timestamp_server": "https://timestamp.digicert.com",
      "description": "MyApp",
      "url": "https://example.com"
    }
  }
}

Do not commit passwords, tokens, certificates, or private keys.

Recommended flow:

# 1. Build artifacts
qyro build --target windows

# 2. Validate signing prerequisites
qyro sign --check --platform windows

# 3. Sign supported binaries in build/
qyro sign --platform windows

By default, Qyro signs supported binary types in the freeze output, such as .exe, .dll, .msi, and .cab.

macOS signing and notarization

Requirements:

• macOS host with Xcode Command Line Tools: codesign, xcrun, notarytool, stapler, and spctl.
• Apple Developer membership.
• Valid Developer ID Application certificate in Keychain.
• Entitlements file for Python runtime behavior, recommended for GUI applications.

Example:

{
  "sign": {
    "mac": {
      "identity": "Developer ID Application: Your Name (TEAMID)",
      "entitlements": "src/sign/mac/entitlements.plist",
      "target_architecture": "universal2",
      "notary": {
        "enabled": true,
        "staple": true,
        "assess_gatekeeper": true,
        "keychain_profile": "QYRO-NOTARY"
      }
    }
  }
}

Do not commit Apple credentials, API keys, passwords, private keys, or credential-bearing configuration to the repository. Use settings/secrets.json for local secret overrides.

Recommended flow:

# 1. Build the macOS application bundle
qyro build --target mac

# 2. Validate signing and notarization prerequisites
qyro sign --check --platform mac

# 3. Sign the application
qyro sign --platform mac

# 4. Sign, notarize, and staple
qyro sign \
  --platform mac \
  --notarize \
  --staple \
  --keychain-profile "QYRO-NOTARY"

Supported notarization authentication options:

• keychain_profile
• key_path + key_id + optional issuer
• apple_id + team_id + app_password

When sign.mac.identity and sign.mac.entitlements are configured, Qyro also forwards them to PyInstaller through --codesign-identity and --osx-entitlements-file during macOS builds.

---

Secret management

Qyro supports a local-only secrets file:

• settings/secrets.json.

Qyro loads base and profile settings first, then applies secrets.json as the highest-precedence override.

Example settings/secrets.json:

{
  "sign": {
    "windows": {
      "password": "<local-secret>"
    },
    "mac": {
      "notary": {
        "keychain_profile": "QYRO-NOTARY-LOCAL",
        "app_password": "<local-secret>"
      }
    }
  }
}

Repository safety:

• Never commit settings/secrets.json.
• The repository .gitignore includes this path by default.

---

Alpha status

The following areas are still under active development:

• Some optional CLI flags may change or require further validation.
• Mobile targets and Buildozer integration are experimental.
• Code signing and notarization require platform-specific tools and credentials.
• Compatibility depends on the framework, operating system, Python version, dependency versions, and test environment.

The compatibility matrix distinguishes successful, failed, and not-yet-tested combinations. It does not guarantee compatibility with every dependency revision or operating-system update.

---

🎛️ CLI Commands Reference

Commands marked as requiring a project must be run from a generated Qyro project directory.

Command	Project required	Flags / Args	Description
qyro init	No	-n, --name, -b, --binding, --template-version	Initialize a new project.
qyro start	Yes	None	Run the application from source.
qyro build	Yes	-m, --mode, --onefile, --debug, --console, --uac, -p, --profile, -c, --clean, -i, --interactive, --target, --init-spec	Freeze/build artifacts.
qyro bundle	Yes	--release-dir, --no-resources, --zip, --platform, --format, --check	Create distributable packages or run preflight checks.
qyro sign	Yes	--platform, --check, --notarize, --staple, --no-assess, --keychain-profile	Sign compiled artifacts and optionally notarize/staple macOS apps.
qyro clean	Yes	--release	Remove generated build artifacts.
qyro version	No	None	Show version information.

---

⚙️ Bundle configuration

Projects can configure bundle behavior in:

• settings/release.json — current layout.

Example:

{
  "release": true,
  "environment": "development",
  "bundle": {
    "dmg": {
      "window": {
        "x": 200,
        "y": 120
      },
      "window_size": {
        "width": 660,
        "height": 420
      },
      "icon_size": 120,
      "app_position": {
        "x": 180,
        "y": 180
      },
      "applications_position": {
        "x": 480,
        "y": 180
      },
      "background": "assets/dmg-background.jpg"
    },
    "extra_files": [
      "README.md",
      {
        "source": "docs/RELEASE_NOTES.md",
        "destination": "docs/RELEASE_NOTES.md"
      }
    ]
  }
}

bundle.extra_files

Supported forms:

• String path: copied to the bundle root.
• Object with source and destination: copied to a relative destination inside the bundle.

Validation rules:

• source must exist.
• destination must be relative.
• Absolute destinations are not allowed.
• destination must not escape the output directory.

bundle.dmg

When DMG customization is configured, create-dmg is required.

Without custom DMG options, bundling can fall back to native hdiutil on macOS.

---

🧰 Packaging dependencies

Format	Requirement
DMG with customization	create-dmg
DMG without customization	hdiutil on macOS
NSIS	makensis
DEB, RPM, or Arch	fpm

Install create-dmg on macOS with one of:

brew install create-dmg

or:

npm install -g create-dmg

---

🖼️ Supported framework ecosystem

qyro-cli generates applications that integrate with Qyro adapters:

Binding	Adapter	Best For
PySide6	PySide6Adapter	Modern Qt 6 desktop applications.
PyQt6	PyQt6Adapter	Feature-complete Qt 6 desktop applications.
PyQt5	PyQt5Adapter	Legacy Qt 5 desktop applications.
PySide2	PySide2Adapter	Qt 5 environments; not included in the current matrix.
Kivy	KivyAdapter	Cross-platform desktop interfaces; mobile support is experimental.
Tkinter	TkinterAdapter	Desktop utilities built on the Python standard library.

---

🔌 Built-in add-ons

Projects can be configured with modular add-ons:

• hotrl — Hot Reloading: Iterative development with live code reload.
• pydux — Predictable State: Redux-inspired state container patterns.
• sentry-sdk — Telemetry: Exception and crash reporting integration.
• requests — HTTP Client: Optional HTTP client dependency.

---

📝 Notes for developers

• qyro bundle --check is the fastest way to validate release readiness in CI.
• qyro clean --release is useful before reproducible release builds.
• If a bundle step fails, inspect the exact command output and step-specific logs.
• Compatibility results should be refreshed when supported Python versions, dependency constraints, or packaging logic change.

---

🤝 Contributing

Contributions to qyro-cli and the Qyro ecosystem are welcome.

1. Fork the repository on GitHub.

2. Create a feature branch:

   git checkout -b feature/amazing-feature
   

3. Run the test suite:

   poetry run pytest
   

4. Commit your changes:

   git commit -m "feat: add amazing feature"
   

5. Push your branch:

   git push origin feature/amazing-feature
   

6. Open a pull request.

---

📄 License

MIT. See LICENSE.

---

👥 Organization and maintainers

• Organization: Neuri
• Lead Maintainer: Luis Alfredo De Los Reyes (luisalfredoreyes98@gmail.com)
• Ecosystem: Qyro • Qyro CLI • Boilerplates