⚡ 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 freezing for desktop targets 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/stapling.
• ✅ Release Preflight Checks: Validate dependencies and release.json paths/options before packaging.
• 🧹 Artifact Cleanup: Clean build outputs and optional release outputs with one command.

---

🚀 Installation

Core CLI

# Using pip
pip install qyro-cli

# Using Poetry
poetry add qyro-cli

Desktop Packaging Support (PyInstaller)

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

# Using Poetry
poetry add qyro-cli -E desktop

Mobile Packaging Support (Buildozer)

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

# Using Poetry
poetry add qyro-cli -E mobile

Complete Bundle (Desktop + Mobile)

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

# Using Poetry
poetry add qyro-cli -E all

---

💻 Quick Start & Usage

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.0

Supported --binding values:

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

2) Run from source

cd my-app
qyro start

Note: qyro start currently runs from source without release flag variants.

3) Freeze executable artifacts

# default desktop target, profile=release
qyro build

# single executable
qyro build --onefile
# or
qyro build --mode onefile

# platform profile override
qyro build --target mac
qyro build --target windows
qyro build --target linux

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

4) Bundle for distribution

# auto format by host OS
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 custom output dir
qyro bundle --zip --release-dir release

Validate before packaging (preflight)

qyro bundle --check

This validates dependencies and release settings (like DMG background and extra files) without generating artifacts.

Clean outputs

# clean freeze directory (default: build/)
qyro clean

# also clean release/
qyro clean --release

Sign compiled artifacts

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

# sign frozen binaries/app bundle
qyro sign --platform windows
qyro sign --platform mac

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

# skip Gatekeeper assessment if desired
qyro sign --platform mac --notarize --staple --no-assess

Signing guide (Windows + macOS)

Use settings/release.json (or build/settings/release.json) to configure signing.

Windows signing (Authenticode)

Requirements:

• Windows host with signtool available in PATH.
• A code-signing certificate file (for example .pfx) and its password.

Example configuration:

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

Security note:

• Do not commit real passwords, tokens or private keys in settings/release.json.
• Put sensitive values in settings/secrets.json instead (loaded locally at build/sign time).

Recommended flow:

# 1) build artifacts
qyro build --target windows

# 2) validate signing prerequisites
qyro sign --check --platform windows

# 3) sign all signable binaries in build/
qyro sign --platform windows

By default, Qyro signs supported binary types in the freeze output (for example .exe, .dll, .msi, .cab).

macOS signing + notarization

Requirements:

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

Example entitlements.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>com.apple.security.cs.allow-jit</key>
    <true/>
    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
    <true/>
    <key>com.apple.security.cs.disable-library-validation</key>
    <true/>
  </dict>
</plist>

Example configuration:

{
  "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"
      }
    }
  }
}

Security note:

• Do not commit Apple credentials (app_password, API key paths, keychain profile names tied to private key workflows) in shared config files.
• Use settings/secrets.json for local secret overrides.

Recommended flow:

# 1) build mac app bundle
qyro build --target mac

# 2) validate signing/notary prerequisites
qyro sign --check --platform mac

# 3) sign only
qyro sign --platform mac

# 4) sign + notarize + staple
qyro sign --platform mac --notarize --staple --keychain-profile "QYRO-NOTARY"

Authentication options for sign.mac.notary:

• keychain_profile
• key_path + key_id (+ issuer for Team keys)
• apple_id + team_id + app_password

When sign.mac.identity and sign.mac.entitlements are configured, Qyro also forwards them to PyInstaller (--codesign-identity and --osx-entitlements-file) during qyro build on macOS so collected binaries are signed during packaging.

Secret management (settings/secrets.json)

Qyro supports a local-only secrets file:

• settings/secrets.json (preferred)
• build/settings/secrets.json (legacy compatibility)

How it works:

• Qyro loads base/profile settings first, then applies secrets.json as highest-precedence overrides.
• This means values in secrets.json replace values from base.json, release.json, windows.json, mac.json, etc.

Repository safety:

• settings/secrets.json must never be committed.
• The repository .gitignore includes this path by default.

Example:

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

---

🎛️ CLI Commands Reference

Command	Flags / Args	Description
qyro init	-n, --name -b, --binding --template-version	Initialize a new project.
qyro start	none	Run the app from source.
qyro build	`-m, --mode onedir	onefile --onefile --debug --console --uac -p, --profile -c, --clean -i, --interactive --target --init-spec`
qyro bundle	--release-dir --no-resources --zip --platform --format --check	Create distributable packages or run preflight checks.
qyro sign	`--platform windows	mac
qyro clean	--release	Remove generated build artifacts.
qyro version	none	Show current version info.

---

⚙️ Bundle Configuration (release.json)

Projects can configure bundle behavior in:

• build/settings/release.json (legacy/generated layout)
• settings/release.json (also supported)

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

Supports:

• String path: copied to bundle root.
• Object with source + destination: copied to relative destination inside bundle.

Validation rules:

• source must exist.
• destination must be relative (no absolute paths).
• destination cannot escape output directory.

bundle.dmg

When DMG custom options are set, create-dmg is required.

If no DMG custom options are set, bundling can fallback to native hdiutil.

---

🧰 Packaging Dependencies

Format	Requirement
dmg with customization	create-dmg
dmg without customization	hdiutil (macOS)
nsis	makensis
deb, rpm, 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 apps that integrate natively with qyro-engine adapters:

Binding	Adapter	Best For
PySide6	PySide6Adapter	Modern Qt 6 desktop apps with rich widgets and tooling.
PyQt6	PyQt6Adapter	Feature-complete Qt 6 desktop software.
PyQt5	PyQt5Adapter	Legacy enterprise Qt 5 systems.
PySide2	PySide2Adapter	Official Qt 5 environments.
Kivy	KivyAdapter	Cross-platform touch interfaces for desktop/mobile.
Tkinter	TkinterAdapter	Zero-dependency desktop utilities built on stdlib.

---

🔌 Built-in Add-ons

Projects can be configured with modular add-ons in settings:

• hotrl (Hot Reloading): Iterative development with live code reload.
• pydux (Predictable State): Redux-inspired state container patterns.
• sentry (Telemetry): Exception and crash reporting integration.

---

📝 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, use the exact error output; validations are strict by design to avoid silent bad packages.

---

🤝 Contributing

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

1. Fork the repository on GitHub.
2. Create your feature branch (git checkout -b feature/amazing-feature).
3. Run test suites (poetry run pytest).
4. Commit your changes (git commit -m 'feat: add amazing feature').
5. Push to your branch (git push origin feature/amazing-feature).
6. Open a Pull Request.

---

📄 License

MIT. See LICENSE.

---

👥 Organization & Maintainers

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