Sync open source content 🐝 (from 4509a1aeb0fb5dbeba382b036edb9f457516ada7)

beezythebot · beezythebot · commit 61f3b37106ff · 2026-01-26T15:21:14.000Z
diff --git a/docs/speakeasy-reference/cli/diff/files.md b/docs/speakeasy-reference/cli/diff/files.md
@@ -0,0 +1,51 @@
+# files  
+`speakeasy diff files`  
+
+
+Compare two local spec files  
+
+## Details
+
+# Diff Files
+
+Compare two OpenAPI spec files directly from disk and show SDK-level changes.
+
+This is the simplest mode - just provide paths to your old and new spec files.
+
+Example usage:
+```bash
+speakeasy diff files --old ./old-openapi.yaml --new ./new-openapi.yaml
+
+# Use a specific language for SDK diff context
+speakeasy diff files --old v1.yaml --new v2.yaml --lang typescript
+
+# Specify output directory for intermediate files
+speakeasy diff files --old old.json --new new.json --output-dir ./diff-output
+```
+
+## Usage
+
+```
+speakeasy diff files [flags]
+```
+
+### Options
+
+```
+      --format-to-yaml      Pre-format specs to YAML before diffing (helps with consistent output) (default true)
+  -h, --help                help for files
+  -l, --lang string         Target language for SDK diff context (default "go")
+      --new string          Path to the new OpenAPI spec file
+      --old string          Path to the old OpenAPI spec file
+  -o, --output-dir string   Directory for intermediate files (default "/tmp/speakeasy-diff")
+```
+
+### Options inherited from parent commands
+
+```
+      --logLevel string   the log level (available options: [info, warn, error]) (default "info")
+```
+
+### Parent Command
+
+* [speakeasy diff](/docs/speakeasy-reference/cli/diff)	 - Compare spec revisions and show SDK changes
diff --git a/docs/speakeasy-reference/cli/diff/from-pr.md b/docs/speakeasy-reference/cli/diff/from-pr.md
@@ -0,0 +1,44 @@
+# from-pr  
+`speakeasy diff from-pr`  
+
+
+Compare specs from a GitHub PR  
+
+## Details
+
+# Diff From PR
+
+Compare spec revisions from a GitHub pull request created by Speakeasy.
+
+This command automatically looks up the spec revisions used in a Speakeasy-generated PR
+and shows the SDK-level changes between the previous and new specs.
+
+Example usage:
+```bash
+speakeasy diff from-pr https://github.com/org/sdk-repo/pull/123
+```
+
+## Usage
+
+```
+speakeasy diff from-pr [url] [flags]
+```
+
+### Options
+
+```
+      --format-to-yaml      Pre-format specs to YAML before diffing (helps with consistent output) (default true)
+  -h, --help                help for from-pr
+  -o, --output-dir string   Directory to download specs to (default "/tmp/speakeasy-diff")
+  -v, --verbose             Show detailed event information during lookup
+```
+
+### Options inherited from parent commands
+
+```
+      --logLevel string   the log level (available options: [info, warn, error]) (default "info")
+```
+
+### Parent Command
+
+* [speakeasy diff](/docs/speakeasy-reference/cli/diff)	 - Compare spec revisions and show SDK changes
diff --git a/docs/speakeasy-reference/cli/diff/index.md b/docs/speakeasy-reference/cli/diff/index.md
@@ -0,0 +1,67 @@
+---
+asIndexPage: true
+---
+
+# diff  
+`speakeasy diff`  
+
+
+Compare spec revisions and show SDK changes  
+
+## Details
+
+# Diff
+
+Compare OpenAPI spec revisions and show **SDK-level changes** - how the generated
+SDK methods, models, and types would differ between two spec versions.
+
+This is different from `speakeasy openapi diff` which shows raw OpenAPI schema
+changes (paths, operations, properties). Use this command when you want to understand
+the impact on your generated SDK code.
+
+This command supports three modes:
+
+## Files Mode (Local)
+Compare two spec files directly from disk:
+```bash
+speakeasy diff files --old old-spec.yaml --new new-spec.yaml
+```
+
+## From PR Mode
+Look up specs from a GitHub pull request created by Speakeasy:
+```bash
+speakeasy diff from-pr https://github.com/org/repo/pull/123
+```
+
+## Registry Mode
+Compare specs by providing registry namespace and digest values:
+```bash
+speakeasy diff registry --namespace my-api --old sha256:abc... --new sha256:def...
+```
+
+## Usage
+
+```
+speakeasy diff [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for diff
+```
+
+### Options inherited from parent commands
+
+```
+      --logLevel string   the log level (available options: [info, warn, error]) (default "info")
+```
+
+### Parent Command
+
+* [speakeasy](/docs/speakeasy-reference/cli/getting-started)	 - The Speakeasy CLI tool provides access to the Speakeasy.com platform
+### Sub Commands
+
+* [speakeasy diff files](/docs/speakeasy-reference/cli/diff/files)	 - Compare two local spec files
+* [speakeasy diff from-pr](/docs/speakeasy-reference/cli/diff/from-pr)	 - Compare specs from a GitHub PR
+* [speakeasy diff registry](/docs/speakeasy-reference/cli/diff/registry)	 - Compare specs by registry namespace and digests
diff --git a/docs/speakeasy-reference/cli/diff/registry.md b/docs/speakeasy-reference/cli/diff/registry.md
@@ -0,0 +1,57 @@
+# registry  
+`speakeasy diff registry`  
+
+
+Compare specs by registry namespace and digests  
+
+## Details
+
+# Diff Registry
+
+Compare two OpenAPI spec revisions from the Speakeasy registry and show SDK-level changes.
+
+This command will:
+1. Download the old spec revision from the registry
+2. Download the new spec revision from the registry
+3. Compute and display SDK-level changes between them
+
+Example usage:
+```bash
+speakeasy diff registry \
+  --namespace my-api \
+  --old sha256:abc123... \
+  --new sha256:def456...
+
+# Use a specific language for SDK diff context
+speakeasy diff registry --namespace myns --old sha256:abc... --new sha256:def... --lang typescript
+```
+
+## Usage
+
+```
+speakeasy diff registry [flags]
+```
+
+### Options
+
+```
+      --format-to-yaml      Pre-format specs to YAML before diffing (helps with consistent output) (default true)
+  -h, --help                help for registry
+  -l, --lang string         Target language for SDK diff context (default "go")
+      --namespace string    Source namespace
+      --new string          New revision digest (e.g., sha256:abc123...)
+      --old string          Old revision digest (e.g., sha256:abc123...)
+      --org string          Organization slug (defaults to current)
+  -o, --output-dir string   Directory to download specs to (default "/tmp/speakeasy-diff")
+      --workspace string    Workspace slug (defaults to current)
+```
+
+### Options inherited from parent commands
+
+```
+      --logLevel string   the log level (available options: [info, warn, error]) (default "info")
+```
+
+### Parent Command
+
+* [speakeasy diff](/docs/speakeasy-reference/cli/diff)	 - Compare spec revisions and show SDK changes
diff --git a/docs/speakeasy-reference/cli/index.md b/docs/speakeasy-reference/cli/index.md
@@ -52,6 +52,7 @@ speakeasy [flags]
 * [speakeasy bump](/docs/speakeasy-reference/cli/bump)	 - Bumps the version of a Speakeasy Generation Target
 * [speakeasy clean](/docs/speakeasy-reference/cli/clean)	 - Speakeasy clean can be used to clean up cache, stale temp folders, and old CLI binaries.
 * [speakeasy configure](/docs/speakeasy-reference/cli/configure)	 - Configure your Speakeasy SDK Setup.
+* [speakeasy diff](/docs/speakeasy-reference/cli/diff)	 - Compare spec revisions and show SDK changes
 * [speakeasy lint](/docs/speakeasy-reference/cli/lint)	 - Lint/Validate OpenAPI documents and Speakeasy configuration files
 * [speakeasy mcp](/docs/speakeasy-reference/cli/mcp)	 - Commands for MCP server management
 * [speakeasy merge](/docs/speakeasy-reference/cli/merge)	 - Merge multiple OpenAPI documents into a single document
diff --git a/docs/speakeasy-reference/cli/openapi/diff.md b/docs/speakeasy-reference/cli/openapi/diff.md
@@ -6,7 +6,12 @@ Visualize the changes between two OpenAPI documents
 
 ## Details
 
-Visualize the changes between two OpenAPI documents
+Visualize the **raw OpenAPI schema changes** between two documents - paths added/removed,
+operations changed, properties modified, etc.
+
+This is different from `speakeasy diff` which shows SDK-level changes (how generated
+SDK methods and types would differ). Use this command when you want to see the raw
+specification differences.
 
 ## Usage
 
