Vercel CLI dry-run: check a deploy before you ship it

The Vercel CLI dry-run deployment feature lets you preview exactly what the CLI would upload before it actually creates a deployment. You run vercel deploy --dry from a linked project, and instead of shipping code, the CLI tells you which files it picked up, which it ignored, and which framework it detected. Nothing leaves your machine.

I read about it in Vercel's changelog post, and my first thought was not about speed. It was about the number of times I've deployed something on a shaky connection, waited for the upload, and only then found out I'd shipped a 200 MB folder I forgot to ignore. This closes that gap.

---

🔍 What a dry run actually shows you

The point of a dry run is to answer a simple question: if I deploy right now, what goes up? The CLI resolves that answer without uploading anything or creating a deployment.

For automation, you can ask for the full file manifest as JSON. According to the changelog, that JSON includes:

Field in the manifest	What it tells you
Detected framework	The preset Vercel thinks you're using
Included paths	Every file that would be uploaded
Ignored paths	What .vercelignore and defaults excluded
Directory size distribution	Where your bytes actually live
Largest files	The assets most likely to bloat a deploy
File modes	Permission bits, useful for catching odd executables
Content hashes	A fingerprint of each file's contents

Key takeaway: A dry run is a read-only preview of your deployment. You get the framework detection and the complete file list without spending a single byte of upload bandwidth.

One nice touch: piped or other non-TTY output automatically switches to JSON. So the same command behaves like a human report in your terminal and like structured data inside a script.

---

⚡ Why this matters on a Sri Lankan connection

If you're deploying from a home fibre line in Colombo or tethering off mobile data in Kandy, upload speed is the constraint, not download. A failed or bloated deploy is not just an annoyance, it's real minutes and real data.

Here's the workflow that changes for me:

1. Run vercel deploy --dry and read the included-files list.
2. Spot anything that shouldn't be there, like node_modules, a stray .env, or a huge design asset.
3. Fix .vercelignore or your project config.
4. Re-run the dry run until the manifest matches what you meant to ship.
5. Then deploy for real.

You verify before you commit bandwidth, instead of discovering the mistake after a slow upload. On a metered connection that's the difference between one clean deploy and three wasteful ones.

Bottom line: The dry run turns "deploy and hope" into "inspect, then deploy." That's a good trade when every megabyte uploaded costs you time or data.

---

🛠️ A pre-flight check for AI agents and CI

The changelog is explicit that this is built with automation in mind. An agent or a CI step can use the manifest as a pre-deployment gate and rerun the check until things look right, all without uploading code or creating a deployment.

Concretely, a script can:

• Verify framework detection — fail the build if Vercel guessed the wrong preset.
• Flag missing or unexpected files — catch a build output folder that didn't get generated.
• Catch oversized assets — block the deploy if a single file blows past your budget.
• Check file modes — spot a file that's executable when it shouldn't be.

Because the JSON is stable structured data, you can parse it, assert on it, and gate on it. If you're eyeballing that output while debugging a check, a formatter helps. I keep a browser tab on our free JSON formatter for exactly that: paste the manifest, expand the tree, find the file that shouldn't be there.

Warning: A dry run tells you what Vercel would upload, not whether your app works. It's a packaging check, not a test suite. Keep your linting, type-checks, and builds in the pipeline too.

---

💡 The bigger shift: deployments you can inspect

For years the deploy step was a black box. You typed a command, files went somewhere, and you found out what actually shipped by reading logs after the fact. Making the manifest inspectable before upload moves the deploy from something you trigger to something you can reason about.

That fits a pattern I like: tools that let you look before you leap. Content hashes mean you can diff two manifests and see precisely what changed between deploys. File-mode reporting means a security-conscious team can assert that nothing ships with the wrong permissions. None of this is glamorous, but it's the kind of detail that saves a bad afternoon.

To get it, the changelog says to update the Vercel CLI to v54.17.2 or later. If you're on an older version, vercel deploy --dry simply won't be there.

---

What this means for you

If you deploy to Vercel, add one habit: run the dry run before an important ship, especially your first deploy of a new project when framework detection and ignore rules are least certain.

• Solo builders and students: save upload time and data by catching bloat before it goes over the wire.
• Small teams: wire vercel deploy --dry --json into CI as a cheap pre-flight gate that never creates a deployment.
• Anyone on a slow line: stop paying the upload cost just to learn what you packaged.

It's a small feature with a clear payoff. Look at the manifest, fix your ignore rules, deploy once. On the connections most of us actually work on, deploying right the first time is worth more than deploying fast.