`diff`

Compare local packages with the latest remote version

Usage

npx @vexblocks/cli diff [packages...] [options]

Description

The diff command compares your locally installed VexBlocks packages with the latest version available in the repository. It shows you exactly what files have changed, helping you make informed decisions before upgrading.

What It Shows

The diff command displays:

Current installed version vs. latest available version
List of files that have been added, modified, or deleted
File-by-file comparison with context (similar to git diff)
Which files are protected and won't be updated
Summary of changes by package

Options

Option	Type	Description
`--file`, `-f`	string	Compare a specific file instead of all files
`--summary`	boolean	Show only summary without detailed diff
`--cwd`	string	Working directory for the command

Examples

Compare All Packages

npx @vexblocks/cli diff

Shows differences for all installed packages.

Compare Specific Packages

npx @vexblocks/cli diff cms backend

Only shows differences for the CMS and backend packages.

Compare a Specific File

npx @vexblocks/cli diff --file apps/cms/app/layout.tsx

Shows detailed diff for a single file.

Summary Only

npx @vexblocks/cli diff --summary

Shows a high-level summary without detailed file contents.

Output Format

The command outputs information in this format:

📦 Comparing VexBlocks Packages

Package: cms
Current: v1.0.0
Latest:  v1.2.0

Changed files:
  M  apps/cms/app/layout.tsx
  M  apps/cms/components/ui/button.tsx
  A  apps/cms/components/media-library.tsx
  D  apps/cms/lib/deprecated-util.ts

Protected files (won't be updated):
  -  packages/backend/vexblocks.config.ts
  -  packages/cms-shared/src/types/generated.ts

Summary:
  2 modified, 1 added, 1 deleted

Legend:
  M = Modified
  A = Added
  D = Deleted
  - = Protected

Detailed File Diff

For modified files, you'll see a detailed diff:

--- apps/cms/app/layout.tsx (v1.0.0)
+++ apps/cms/app/layout.tsx (v1.2.0)
@@ -10,7 +10,8 @@
 export default function Layout({ children }) {
   return (
     <html lang="en">
-      <body>{children}</body>
+      <body className="min-h-screen">
+        {children}
+      </body>
     </html>
   )
 }

Tip: Use this before running upgrade to preview what will change.

Color-Coded Output

In your terminal, the diff will be color-coded:

Green lines - Additions
Red lines - Deletions
Blue - Modified files
Yellow - Protected files

Understanding Changes

Modified Files (M)

Files that exist in both your local version and the remote version but have different content. These will be updated during an upgrade.

Added Files (A)

New files in the latest version that don't exist in your local installation. These will be added during an upgrade.

Deleted Files (D)

Files that exist in your local version but have been removed in the latest version. These will be deleted during an upgrade.

Protected Files (-)

Files that are marked as protected and will never be modified by the CLI, regardless of changes in the remote version.

Important: If you've customized any managed files, they will be overwritten during upgrade. The diff helps you identify these cases.

Use Cases

Before Upgrading

Run diff to see what will change:

# Check what will change
npx @vexblocks/cli diff

# If satisfied, proceed with upgrade
npx @vexblocks/cli upgrade

Debugging Issues

If something isn't working after an upgrade, compare specific files:

npx @vexblocks/cli diff --file apps/cms/app/\[schema\]/page.tsx

Reviewing Customizations

See if you've accidentally modified managed files:

npx @vexblocks/cli diff --summary

Working with Git

The diff command is complementary to git. Use them together:

# See what VexBlocks would change
npx @vexblocks/cli diff

# See your local changes
git diff

# Upgrade and review combined changes
npx @vexblocks/cli upgrade
git diff

Best Practice: Always commit your changes to git before running upgrades. This gives you an easy way to review or rollback changes.

Exit Codes

The command uses these exit codes:

Code	Meaning
`0`	Success, no errors
`1`	Error occurred (missing manifest, network error, etc.)

Limitations

Only compares files, not npm package dependencies in package.json
Cannot diff binary files (images, etc.) - only shows if they changed
Requires network access to fetch remote versions

Troubleshooting

No Manifest File

If you see "No vexblocks.json found", initialize first:

npx @vexblocks/cli init

Network Errors

If you can't connect to GitHub, check your internet connection or try again later.

Too Much Output

If the diff is overwhelming, use --summary or filter by package:

npx @vexblocks/cli diff cms --summary

diff