From bab31e5f16acb3fc71481ead8720853bf5f79a5f Mon Sep 17 00:00:00 2001
From: bghira <bghira@users.github.com>
Date: Mon, 31 Aug 2026 09:45:24 -0600
Subject: [PATCH] docs: make cog debug discoverable

---
 docs/cli.md           | 31 +++++++++++++++++++++++++++++++
 docs/llms.txt         | 31 +++++++++++++++++++++++++++++++
 pkg/cli/debug.go      | 15 +++++++++++----
 pkg/cli/debug_test.go | 16 ++++++++++++++++
 4 files changed, 89 insertions(+), 4 deletions(-)
 create mode 100644 pkg/cli/debug_test.go

diff --git a/docs/cli.md b/docs/cli.md
index a15bed8be0..78d3dfa2b8 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -68,6 +68,37 @@ cog build [flags]
       --use-cuda-base-image string   Use Nvidia CUDA base image, 'true' (default) or 'false' (use python base image). False results in a smaller image but may cause problems for non-torch projects (default "auto")
 ```
 
+## `cog debug`
+
+Generate and print the Dockerfile that Cog would use to build the
+current model. This is useful for inspecting generated build steps and
+troubleshooting build failures without building the image.
+
+```
+cog debug [flags]
+```
+
+**Examples**
+
+```
+  # Print the generated Dockerfile
+  cog debug
+
+  # Save it for inspection
+  cog debug > Dockerfile
+```
+
+**Options**
+
+```
+  -f, --file string                  The name of the config file. (default "cog.yaml")
+  -h, --help                         help for debug
+      --image-name string            The image name to use for the generated Dockerfile
+      --separate-weights             Separate model weights from code in image layers
+      --use-cog-base-image           Use pre-built Cog base image for faster cold boots (default true)
+      --use-cuda-base-image string   Use Nvidia CUDA base image, 'true' (default) or 'false' (use python base image). False results in a smaller image but may cause problems for non-torch projects (default "auto")
+```
+
 ## `cog doctor`
 
 Diagnose and fix common issues in your Cog project.
diff --git a/docs/llms.txt b/docs/llms.txt
index 3980e3ef3d..6906946359 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -389,6 +389,37 @@ cog build [flags]
       --use-cuda-base-image string   Use Nvidia CUDA base image, 'true' (default) or 'false' (use python base image). False results in a smaller image but may cause problems for non-torch projects (default "auto")
 ```
 
+## `cog debug`
+
+Generate and print the Dockerfile that Cog would use to build the
+current model. This is useful for inspecting generated build steps and
+troubleshooting build failures without building the image.
+
+```
+cog debug [flags]
+```
+
+**Examples**
+
+```
+  # Print the generated Dockerfile
+  cog debug
+
+  # Save it for inspection
+  cog debug > Dockerfile
+```
+
+**Options**
+
+```
+  -f, --file string                  The name of the config file. (default "cog.yaml")
+  -h, --help                         help for debug
+      --image-name string            The image name to use for the generated Dockerfile
+      --separate-weights             Separate model weights from code in image layers
+      --use-cog-base-image           Use pre-built Cog base image for faster cold boots (default true)
+      --use-cuda-base-image string   Use Nvidia CUDA base image, 'true' (default) or 'false' (use python base image). False results in a smaller image but may cause problems for non-torch projects (default "auto")
+```
+
 ## `cog doctor`
 
 Diagnose and fix common issues in your Cog project.
diff --git a/pkg/cli/debug.go b/pkg/cli/debug.go
index 4b83a2c366..96d4cda5b2 100644
--- a/pkg/cli/debug.go
+++ b/pkg/cli/debug.go
@@ -18,10 +18,17 @@ var imageName string
 
 func newDebugCommand() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:    "debug",
-		Hidden: true,
-		Short:  "Generate a Dockerfile from cog",
-		RunE:   cmdDockerfile,
+		Use:   "debug",
+		Short: "Generate the Dockerfile for the current Cog model",
+		Long: `Generate and print the Dockerfile that Cog would use to build the
+current model. This is useful for inspecting generated build steps and
+troubleshooting build failures without building the image.`,
+		Example: `  # Print the generated Dockerfile
+  cog debug
+
+  # Save it for inspection
+  cog debug > Dockerfile`,
+		RunE: cmdDockerfile,
 	}
 
 	addSeparateWeightsFlag(cmd)
diff --git a/pkg/cli/debug_test.go b/pkg/cli/debug_test.go
new file mode 100644
index 0000000000..7bf843838d
--- /dev/null
+++ b/pkg/cli/debug_test.go
@@ -0,0 +1,16 @@
+package cli
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestDebugCommandIsVisible(t *testing.T) {
+	root, err := NewRootCommand()
+	require.NoError(t, err)
+
+	debugCmd, _, err := root.Find([]string{"debug"})
+	require.NoError(t, err)
+	require.False(t, debugCmd.Hidden)
+}