quickscale-cli 0.72.0__tar.gz → 0.74.2__tar.gz

{quickscale_cli-0.72.0 → quickscale_cli-0.74.2}/PKG-INFO

@@ -1,30 +1,38 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: quickscale-cli
-Version: 0.72.0
+Version: 0.74.2
 Summary: Command-line interface for QuickScale Django project generator
-Home-page: https://github.com/Experto-AI/quickscale
 License: Apache-2.0
 Keywords: django,cli,project-generator,saas
 Author: Experto AI
 Author-email: victor@experto.ai
-Requires-Python: >=3.10,<4.0
+Requires-Python: >=3.12,<4.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: Django
-Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 6.0
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: click (>=8.3.0,<9.0.0)
-Requires-Dist: quickscale-core @ file:///home/victor/Code/quickscale/quickscale_core
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: click (>=8.3.1,<9.0.0)
+Requires-Dist: quickscale-core (>=0.74.2,<0.75.0)
 Project-URL: Documentation, https://github.com/Experto-AI/quickscale/tree/main/docs
+Project-URL: Homepage, https://github.com/Experto-AI/quickscale
 Project-URL: Repository, https://github.com/Experto-AI/quickscale
 Description-Content-Type: text/markdown
 
 # 🚀 QuickScale
 
+[![PyPI version](https://img.shields.io/pypi/v/quickscale.svg)](https://pypi.org/project/quickscale/)
+[![CI](https://github.com/Experto-AI/quickscale/actions/workflows/ci.yml/badge.svg)](https://github.com/Experto-AI/quickscale/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/badge/coverage-90%25-green.svg)](https://github.com/Experto-AI/quickscale/actions/workflows/ci.yml)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Version](https://img.shields.io/badge/version-0.74.0-green.svg)](https://github.com/Experto-AI/quickscale/releases)
+[![Code style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
 > **You are here**: **QuickScale README** (Project Overview)
 > **Related docs**: [Start Here](START_HERE.md) | [Glossary](GLOSSARY.md) | [Decisions](docs/technical/decisions.md) | [User Manual](docs/technical/user_manual.md)
 
@@ -93,10 +101,11 @@ See [decisions.md - Glossary section](./docs/technical/decisions.md#document-res
 
 ### Development Flow
 1. `quickscale plan myapp` → Interactive configuration wizard
-2. `quickscale apply` → Generates production-ready Django project
-3. Add your custom Django apps and features
-4. Build your unique client application
-5. Deploy to Railway with `quickscale deploy railway` (or use standard Django deployment)
+2. `cd myapp` → Navigate to your project directory
+3. `quickscale apply` → Generates production-ready Django project
+4. Add your custom Django apps and features
+5. Build your unique client application
+6. Deploy to Railway with `quickscale deploy railway` (or use standard Django deployment)
 
 ℹ️ The [MVP Feature Matrix](./docs/technical/decisions.md#mvp-feature-matrix-authoritative) is the single source of truth for what's in or out.
 
@@ -104,6 +113,7 @@ See [decisions.md - Glossary section](./docs/technical/decisions.md#document-res
 
 Running `quickscale plan myapp && quickscale apply` generates a **production-ready Django project** with:
 
+- ✅ **React + shadcn/ui** frontend (TypeScript, Vite, Tailwind CSS) — **NEW in v0.74.0**
 - ✅ **Docker** setup (development + production)
 - ✅ **PostgreSQL** configuration
 - ✅ **Environment-based** settings (dev/prod split)
@@ -115,6 +125,8 @@ Running `quickscale plan myapp && quickscale apply` generates a **production-rea
 - ✅ **Poetry** for dependency management
 - ✅ **One-Command Deployment**: Deploy to Railway with `quickscale deploy railway` - fully automated setup
 
+**Alternative**: Use `quickscale plan myapp --theme showcase_html` for pure HTML/CSS (simpler projects).
+
 **See the complete project structure:** [scaffolding.md - Generated Project Output](./docs/technical/scaffolding.md#5-generated-project-output)
 
 The generated project is **yours to own and modify** - no vendor lock-in, just Django best practices.
@@ -132,8 +144,148 @@ See [competitive_analysis.md](./docs/overview/competitive_analysis.md) for detai
 
 ---
 
+## Installation
+
+QuickScale can be installed in two ways:
+
+### Method 1: Install from PyPI (Recommended)
+
+**Quick install:**
+```bash
+pip install quickscale
+```
+
+**Or with Poetry:**
+```bash
+poetry add quickscale
+```
+
+**Then use directly:**
+```bash
+quickscale plan myapp
+cd myapp
+quickscale apply
+```
+
+### Method 2: Install from Source
+
+**For those who prefer building from source:**
+```bash
+git clone https://github.com/Experto-AI/quickscale.git
+cd quickscale
+./scripts/install_global.sh
+```
+
+**Then use directly:**
+```bash
+quickscale plan myapp
+cd myapp
+quickscale apply
+```
+
+**Both methods use the same command syntax:** `quickscale plan`, `quickscale apply`, etc.
+
+---
+
+### For Contributors
+
+If you want to contribute to QuickScale development, see the [Development Guide](./docs/technical/development.md) for setup instructions.
+
+---
+
+## 🚀 5-Minute Quickstart
+
+**Want to see QuickScale in action right now?** Here's the fastest path to a working Django SaaS:
+
+```bash
+# 1. Install QuickScale
+./scripts/install_global.sh
+
+# 2. Create your project configuration
+quickscale plan myapp
+# → Accept defaults: theme (showcase_html), no modules, Docker enabled
+
+# 3. Generate and enter the project
+cd myapp
+quickscale apply
+# → Docker services auto-start! (default: docker.start=true)
+
+# 4. Setup and verify
+quickscale manage migrate
+quickscale manage createsuperuser
+quickscale ps  # Check services are running
+
+# 5. Open http://localhost:8000
+```
+
+**That's it!** 🎉 You now have a production-ready Django SaaS running with Docker + PostgreSQL.
+
+**Note**: Services started automatically during `quickscale apply`. No need to run `quickscale up` manually!
+
+**Prefer native Python?** After step 3, run:
+```bash
+poetry install
+poetry run python manage.py migrate
+poetry run python manage.py runserver
+# Open http://localhost:8000
+```
+
+---
+
+## Understanding Docker Auto-Start
+
+**When does `quickscale apply` start Docker automatically?**
+
+✅ **Services auto-start** (no `quickscale up` needed):
+- First-time project generation
+- When `docker.start: true` in quickscale.yml (**default**)
+- When `--no-docker` flag is NOT used
+
+❌ **Manual start required** (`quickscale up` needed):
+- You set `docker.start: false` during `quickscale plan` wizard
+- After stopping services with `quickscale down`
+- When running `quickscale apply --no-docker`
+- Adding modules to existing project (incremental apply)
 
-## Quick Start
+**Example - No manual start needed:**
+```bash
+quickscale plan myapp  # Accept defaults (docker.start: true)
+cd myapp
+quickscale apply       # ← Docker services auto-start!
+
+# Already running - just check status:
+quickscale ps
+curl http://localhost:8000  # ✅ Works immediately
+```
+
+**Example - Manual start needed:**
+```bash
+quickscale plan myapp
+# During wizard, set: "Docker start? [Y/n]: n"
+cd myapp
+quickscale apply       # Services do NOT start
+
+# Must start manually:
+quickscale up
+```
+
+**Docker configuration options** in quickscale.yml:
+
+```yaml
+docker:
+  start: true   # Auto-start services during apply?
+  build: true   # Rebuild images? (slower but ensures latest)
+```
+
+- `start: true` + `build: true` → Full rebuild + start (slowest, most reliable)
+- `start: true` + `build: false` → Start with cached images (faster)
+- `start: false` → Manual control with `quickscale up`
+
+**Need more details?** See [Docker Workflows Guide](./docs/technical/docker_workflows.md) for comprehensive scenarios and troubleshooting.
+
+---
+
+## Full Documentation & Setup
 
 ```bash
 # Install QuickScale globally
@@ -142,11 +294,11 @@ See [competitive_analysis.md](./docs/overview/competitive_analysis.md) for detai
 # Create a configuration interactively
 quickscale plan myapp
 # → Select theme, modules, Docker options
-# → Generates quickscale.yml
+# → Generates quickscale.yml in myapp/ directory
 
-# Execute the configuration
-quickscale apply
+# Navigate to project and execute the configuration
 cd myapp
+quickscale apply
 ```
 
 **Choose your development workflow:**

{quickscale_cli-0.72.0 → quickscale_cli-0.74.2}/README.md

@@ -1,5 +1,13 @@
 # 🚀 QuickScale
 
+[![PyPI version](https://img.shields.io/pypi/v/quickscale.svg)](https://pypi.org/project/quickscale/)
+[![CI](https://github.com/Experto-AI/quickscale/actions/workflows/ci.yml/badge.svg)](https://github.com/Experto-AI/quickscale/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/badge/coverage-90%25-green.svg)](https://github.com/Experto-AI/quickscale/actions/workflows/ci.yml)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Version](https://img.shields.io/badge/version-0.74.0-green.svg)](https://github.com/Experto-AI/quickscale/releases)
+[![Code style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
 > **You are here**: **QuickScale README** (Project Overview)
 > **Related docs**: [Start Here](START_HERE.md) | [Glossary](GLOSSARY.md) | [Decisions](docs/technical/decisions.md) | [User Manual](docs/technical/user_manual.md)
 
@@ -68,10 +76,11 @@ See [decisions.md - Glossary section](./docs/technical/decisions.md#document-res
 
 ### Development Flow
 1. `quickscale plan myapp` → Interactive configuration wizard
-2. `quickscale apply` → Generates production-ready Django project
-3. Add your custom Django apps and features
-4. Build your unique client application
-5. Deploy to Railway with `quickscale deploy railway` (or use standard Django deployment)
+2. `cd myapp` → Navigate to your project directory
+3. `quickscale apply` → Generates production-ready Django project
+4. Add your custom Django apps and features
+5. Build your unique client application
+6. Deploy to Railway with `quickscale deploy railway` (or use standard Django deployment)
 
 ℹ️ The [MVP Feature Matrix](./docs/technical/decisions.md#mvp-feature-matrix-authoritative) is the single source of truth for what's in or out.
 
@@ -79,6 +88,7 @@ See [decisions.md - Glossary section](./docs/technical/decisions.md#document-res
 
 Running `quickscale plan myapp && quickscale apply` generates a **production-ready Django project** with:
 
+- ✅ **React + shadcn/ui** frontend (TypeScript, Vite, Tailwind CSS) — **NEW in v0.74.0**
 - ✅ **Docker** setup (development + production)
 - ✅ **PostgreSQL** configuration
 - ✅ **Environment-based** settings (dev/prod split)
@@ -90,6 +100,8 @@ Running `quickscale plan myapp && quickscale apply` generates a **production-rea
 - ✅ **Poetry** for dependency management
 - ✅ **One-Command Deployment**: Deploy to Railway with `quickscale deploy railway` - fully automated setup
 
+**Alternative**: Use `quickscale plan myapp --theme showcase_html` for pure HTML/CSS (simpler projects).
+
 **See the complete project structure:** [scaffolding.md - Generated Project Output](./docs/technical/scaffolding.md#5-generated-project-output)
 
 The generated project is **yours to own and modify** - no vendor lock-in, just Django best practices.
@@ -107,8 +119,148 @@ See [competitive_analysis.md](./docs/overview/competitive_analysis.md) for detai
 
 ---
 
+## Installation
+
+QuickScale can be installed in two ways:
+
+### Method 1: Install from PyPI (Recommended)
+
+**Quick install:**
+```bash
+pip install quickscale
+```
+
+**Or with Poetry:**
+```bash
+poetry add quickscale
+```
+
+**Then use directly:**
+```bash
+quickscale plan myapp
+cd myapp
+quickscale apply
+```
+
+### Method 2: Install from Source
+
+**For those who prefer building from source:**
+```bash
+git clone https://github.com/Experto-AI/quickscale.git
+cd quickscale
+./scripts/install_global.sh
+```
+
+**Then use directly:**
+```bash
+quickscale plan myapp
+cd myapp
+quickscale apply
+```
+
+**Both methods use the same command syntax:** `quickscale plan`, `quickscale apply`, etc.
+
+---
+
+### For Contributors
+
+If you want to contribute to QuickScale development, see the [Development Guide](./docs/technical/development.md) for setup instructions.
+
+---
+
+## 🚀 5-Minute Quickstart
+
+**Want to see QuickScale in action right now?** Here's the fastest path to a working Django SaaS:
+
+```bash
+# 1. Install QuickScale
+./scripts/install_global.sh
+
+# 2. Create your project configuration
+quickscale plan myapp
+# → Accept defaults: theme (showcase_html), no modules, Docker enabled
+
+# 3. Generate and enter the project
+cd myapp
+quickscale apply
+# → Docker services auto-start! (default: docker.start=true)
+
+# 4. Setup and verify
+quickscale manage migrate
+quickscale manage createsuperuser
+quickscale ps  # Check services are running
+
+# 5. Open http://localhost:8000
+```
+
+**That's it!** 🎉 You now have a production-ready Django SaaS running with Docker + PostgreSQL.
+
+**Note**: Services started automatically during `quickscale apply`. No need to run `quickscale up` manually!
+
+**Prefer native Python?** After step 3, run:
+```bash
+poetry install
+poetry run python manage.py migrate
+poetry run python manage.py runserver
+# Open http://localhost:8000
+```
+
+---
+
+## Understanding Docker Auto-Start
+
+**When does `quickscale apply` start Docker automatically?**
+
+✅ **Services auto-start** (no `quickscale up` needed):
+- First-time project generation
+- When `docker.start: true` in quickscale.yml (**default**)
+- When `--no-docker` flag is NOT used
+
+❌ **Manual start required** (`quickscale up` needed):
+- You set `docker.start: false` during `quickscale plan` wizard
+- After stopping services with `quickscale down`
+- When running `quickscale apply --no-docker`
+- Adding modules to existing project (incremental apply)
 
-## Quick Start
+**Example - No manual start needed:**
+```bash
+quickscale plan myapp  # Accept defaults (docker.start: true)
+cd myapp
+quickscale apply       # ← Docker services auto-start!
+
+# Already running - just check status:
+quickscale ps
+curl http://localhost:8000  # ✅ Works immediately
+```
+
+**Example - Manual start needed:**
+```bash
+quickscale plan myapp
+# During wizard, set: "Docker start? [Y/n]: n"
+cd myapp
+quickscale apply       # Services do NOT start
+
+# Must start manually:
+quickscale up
+```
+
+**Docker configuration options** in quickscale.yml:
+
+```yaml
+docker:
+  start: true   # Auto-start services during apply?
+  build: true   # Rebuild images? (slower but ensures latest)
+```
+
+- `start: true` + `build: true` → Full rebuild + start (slowest, most reliable)
+- `start: true` + `build: false` → Start with cached images (faster)
+- `start: false` → Manual control with `quickscale up`
+
+**Need more details?** See [Docker Workflows Guide](./docs/technical/docker_workflows.md) for comprehensive scenarios and troubleshooting.
+
+---
+
+## Full Documentation & Setup
 
 ```bash
 # Install QuickScale globally
@@ -117,11 +269,11 @@ See [competitive_analysis.md](./docs/overview/competitive_analysis.md) for detai
 # Create a configuration interactively
 quickscale plan myapp
 # → Select theme, modules, Docker options
-# → Generates quickscale.yml
+# → Generates quickscale.yml in myapp/ directory
 
-# Execute the configuration
-quickscale apply
+# Navigate to project and execute the configuration
 cd myapp
+quickscale apply
 ```
 
 **Choose your development workflow:**

{quickscale_cli-0.72.0 → quickscale_cli-0.74.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "quickscale-cli"
-version = "0.72.0"
+version = "0.74.2"
 description = "Command-line interface for QuickScale Django project generator"
 authors = ["Experto AI <victor@experto.ai>"]
 license = "Apache-2.0"
@@ -14,18 +14,18 @@ classifiers = [
     "Intended Audience :: Developers",
     "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Framework :: Django",
-    "Framework :: Django :: 5.0",
+    "Framework :: Django :: 6.0",
 ]
 packages = [{include = "quickscale_cli", from = "src"}]
 
 [tool.poetry.dependencies]
-python = "^3.10"
-click = "^8.3.0"
-quickscale-core = {path = "../quickscale_core"}
+python = "^3.12"
+click = "^8.3.1"
+quickscale-core = "^0.74.2"
 
 [tool.poetry.group.dev.dependencies]
 # Dev dependencies centralized in root pyproject.toml
@@ -49,6 +49,7 @@ addopts = [
     "--cov=quickscale_cli",
     "--cov-report=term-missing",
     "--cov-report=html",
+    "--cov-fail-under=90",
     "-m", "not e2e",  # Skip E2E tests by default (run with: pytest -m e2e)
 ]
 markers = [
@@ -57,6 +58,10 @@ markers = [
     "e2e: end-to-end tests",
 ]
 
+[tool.coverage.report]
+fail_under = 90
+# Per-file minimum target: 80% (enforced via code review)
+
 # Ruff and mypy configurations centralized in root ruff.toml and mypy.ini
 # Package-specific isort override
 [tool.ruff.lint.isort]

{quickscale_cli-0.72.0 → quickscale_cli-0.74.2}/src/quickscale_cli/_version.py

@@ -1,2 +1,2 @@
 # Auto-generated by scripts/version_tool.sh
-__version__ = "0.72.0"
+__version__ = "0.74.2"

{quickscale_cli-0.72.0 → quickscale_cli-0.74.2}/src/quickscale_cli/commands/apply_command.py

@@ -23,6 +23,7 @@ from quickscale_cli.schema.state_schema import (
     QuickScaleState,
     StateManager,
 )
+from quickscale_core.utils.git_utils import is_working_directory_clean
 from quickscale_core.generator import ProjectGenerator
 from quickscale_core.manifest import ModuleManifest
 from quickscale_core.manifest.loader import get_manifest_for_module
@@ -91,18 +92,21 @@ def _generate_project(config: QuickScaleConfig, output_path: Path) -> bool:
         click.echo(f"⏳ Generating project: {config.project.name}...")
 
         # Validate theme availability
-        if config.project.theme in ["showcase_htmx", "showcase_react"]:
+        if config.project.theme == "showcase_htmx":
             click.secho(
                 f"❌ Error: Theme '{config.project.theme}' is not yet implemented",
                 fg="red",
                 err=True,
             )
             click.echo(
-                f"\n💡 The '{config.project.theme}' theme is planned for a future release:",
+                "\n💡 The 'showcase_htmx' theme is planned for a future release:",
+                err=True,
+            )
+            click.echo("   - showcase_htmx: Coming in v0.78.0", err=True)
+            click.echo(
+                "   - Use 'showcase_react' (default) or 'showcase_html' instead",
                 err=True,
             )
-            click.echo("   - showcase_htmx: Coming in v0.70.0", err=True)
-            click.echo("   - showcase_react: Coming in v0.71.0", err=True)
             return False
 
         generator = ProjectGenerator(theme=config.project.theme)
@@ -196,18 +200,54 @@ def _run_migrations(project_path: Path) -> bool:
     )[0]
 
 
-def _start_docker(project_path: Path, build: bool = True) -> bool:
-    """Start Docker services using quickscale up"""
+def _start_docker(
+    project_path: Path, build: bool = True, verbose: bool = False
+) -> bool:
+    """Start Docker services using quickscale up
+
+    Args:
+        project_path: Path to the project directory
+        build: Whether to build images before starting
+        verbose: Whether to show Docker build output (useful for debugging)
+
+    Returns:
+        True if Docker started successfully, False otherwise
+    """
     cmd = ["quickscale", "up"]
     if build:
         cmd.append("--build")
 
-    success, _ = _run_command(
-        cmd,
-        project_path,
-        "Starting Docker services",
-    )
-    return success
+    if verbose:
+        # Show Docker build output for debugging
+        click.echo("⏳ Starting Docker services (showing build output)...")
+        click.echo("=" * 50)
+        try:
+            result = subprocess.run(
+                cmd,
+                cwd=project_path,
+                text=True,
+                check=False,
+            )
+            click.echo("=" * 50)
+            if result.returncode == 0:
+                click.secho("✅ Starting Docker services", fg="green")
+                return True
+            else:
+                click.secho("❌ Starting Docker services failed", fg="red")
+                return False
+        except FileNotFoundError:
+            click.secho(f"❌ Command not found: {cmd[0]}", fg="red", err=True)
+            return False
+        except Exception as e:
+            click.secho(f"❌ Unexpected error: {e}", fg="red", err=True)
+            return False
+    else:
+        success, _ = _run_command(
+            cmd,
+            project_path,
+            "Starting Docker services",
+        )
+        return success
 
 
 def _load_module_manifests(
@@ -516,6 +556,9 @@ def _embed_modules_step(
                 f"⚠️  Module embedding failed for {module_name}, continuing...",
                 fg="yellow",
             )
+            # Commit any partial changes to allow subsequent modules to be embedded
+            if not is_working_directory_clean(output_path):
+                _git_commit(output_path, f"Partial module: {module_name} (incomplete)")
         else:
             embedded_modules.append(module_name)
             _git_commit(output_path, f"Add module: {module_name}")
@@ -642,7 +685,11 @@ def _prepare_apply_context(config_path: Path) -> ApplyContext:
 
 
 def _execute_apply_steps(
-    ctx: ApplyContext, force: bool, no_docker: bool, no_modules: bool
+    ctx: ApplyContext,
+    force: bool,
+    no_docker: bool,
+    no_modules: bool,
+    verbose_docker: bool = False,
 ) -> None:
     """Execute the apply steps after confirmation."""
     click.echo("\n" + "=" * 50)
@@ -681,7 +728,9 @@ def _execute_apply_steps(
 
     # Start Docker
     if not no_docker and ctx.qs_config.docker.start:
-        if not _start_docker(ctx.output_path, ctx.qs_config.docker.build):
+        if not _start_docker(
+            ctx.output_path, ctx.qs_config.docker.build, verbose_docker
+        ):
             click.secho("⚠️  Docker start failed, continuing...", fg="yellow")
 
     # Save state
@@ -720,7 +769,14 @@ def _execute_apply_steps(
     is_flag=True,
     help="Skip module embedding",
 )
-def apply(config: str, force: bool, no_docker: bool, no_modules: bool) -> None:
+@click.option(
+    "--verbose-docker",
+    is_flag=True,
+    help="Show Docker build output (useful for debugging build issues)",
+)
+def apply(
+    config: str, force: bool, no_docker: bool, no_modules: bool, verbose_docker: bool
+) -> None:
     """
     Execute project configuration from quickscale.yml.
 
@@ -733,6 +789,7 @@ def apply(config: str, force: bool, no_docker: bool, no_modules: bool) -> None:
       quickscale apply myapp/quickscale.yml  # Use specific config file
       quickscale apply --force            # Overwrite existing project
       quickscale apply --no-docker        # Skip Docker operations
+      quickscale apply --verbose-docker   # Show Docker build output
 
     \b
     Execution Order:
@@ -756,10 +813,23 @@ def apply(config: str, force: bool, no_docker: bool, no_modules: bool) -> None:
     # Check output directory
     _check_output_directory(ctx.output_path, ctx.existing_state, force)
 
+    # Ask about Docker build output visibility if Docker will be started
+    show_docker_output = verbose_docker
+    if (
+        not no_docker
+        and ctx.qs_config.docker.start
+        and ctx.qs_config.docker.build
+        and not verbose_docker
+    ):
+        show_docker_output = click.confirm(
+            "\n🐳 Show Docker build output? (useful for debugging build issues)",
+            default=False,
+        )
+
     # Confirm before proceeding
     if not click.confirm("\n❓ Proceed with apply?", default=True):
         click.echo("❌ Cancelled")
         raise click.Abort()
 
     # Execute apply steps
-    _execute_apply_steps(ctx, force, no_docker, no_modules)
+    _execute_apply_steps(ctx, force, no_docker, no_modules, show_docker_output)