Netlify Deploy
Deploy web projects to Netlify with automatic framework detection, preview URLs, and production releases.
Overview
Automate the full Netlify deployment lifecycle: verify CLI authentication, link the local project to a Netlify site, detect the framework and build settings, run a preview deploy for validation, then promote to production when confirmed.
What it automates:
- Authentication checks and recovery via
npx netlify status/npx netlify login - Site linking by Git remote or interactive
npx netlify init - Framework-aware build configuration (Next.js, Vite, Astro, SvelteKit, static HTML)
- Preview deploys with unique draft URLs and production deploys with
--prod
Time saved: ~5-15 minutes per deployment cycle
Triggers
When to Run
This automation activates when the user:
- Asks to "deploy", "publish", "host", or "ship" to Netlify
- Wants a preview URL for a branch or PR
- Needs to set up a new Netlify site from a local project
- Asks to push changes to production on Netlify
Manual Invocation
/netlify-deploy [options]
| Option | Description |
|---|---|
--prod | Deploy directly to production (skip preview) |
--dir=path | Override publish directory |
--message="text" | Attach deploy message for audit trail |
Process
Step 1: Verify Authentication
Check that the Netlify CLI has a valid session:
npx netlify status
Authenticated output includes the logged-in email and linked site name.
Not authenticated shows Not logged in or an auth error.
If not authenticated, prompt the user to log in:
npx netlify login
This opens a browser for OAuth. After completion, re-run npx netlify status to confirm. If browser auth is unavailable, the user can set NETLIFY_AUTH_TOKEN as an environment variable with a personal access token from the Netlify dashboard.
Step 2: Check Site Link
From npx netlify status output, determine whether the project is linked to a Netlify site.
If linked: proceed to Step 3.
If not linked: attempt Git-based linking first:
npx netlify link --git-remote-url "$(git remote get-url origin)"
If that fails (no matching site), create a new site interactively:
npx netlify init
The init wizard walks through team selection, site name, build command, and publish directory.
Step 3: Detect Build Settings
Read package.json to identify the framework and infer build configuration:
| Framework | Build Command | Publish Dir |
|---|---|---|
| Next.js | npm run build | .next |
| Vite (React/Vue) | npm run build | dist |
| Astro | npm run build | dist |
| SvelteKit | npm run build | build |
| Static HTML | (none) | . |
If netlify.toml exists, the CLI uses it automatically. If it does not exist and the framework is detected, create one:
[build]
command = "npm run build"
publish = "dist"
[[redirects]]
from = "/*"
to = "/index.html"
status = 200
Ensure dependencies are installed before building:
npm install # or yarn install / pnpm install
Step 4: Deploy
Preview deploy (default, safe for testing):
npx netlify deploy
Returns a unique draft URL like https://507f1f77--my-app.netlify.app.
Production deploy (after preview is verified or when --prod is requested):
npx netlify deploy --prod
Returns the live production URL.
Add a deploy message for the audit log:
npx netlify deploy --prod --message="v1.2.0 release - fix auth redirect"
Step 5: Report Results
After deployment, report:
- Draft URL or Production URL (clickable)
- Deploy ID from CLI output
- Dashboard link:
npx netlify opento view in Netlify dashboard - Any build warnings or errors from the deploy log
Verification
Success Indicators
npx netlify deployexits with code 0- Output contains
Website draft URL:orWebsite URL:with a valid HTTPS link - The URL is accessible (HTTP 200) when fetched
Failure Handling
| Error | Cause | Resolution |
|---|---|---|
Not logged in | Auth token expired or missing | Run npx netlify login or set NETLIFY_AUTH_TOKEN |
No site linked | Project not connected to Netlify | Run npx netlify link or npx netlify init |
Build failed (exit code 1) | Build command errored | Run build locally (npm run build), fix errors, retry |
Publish directory not found | Build output missing | Verify publish dir in netlify.toml matches actual output |
Network timeout | Sandbox blocking outbound traffic | Rerun with sandbox_permissions=require_escalated |
Examples
Example 1: First-Time Deploy (New Project)
User: Deploy this React app to Netlify
[Runs: npx netlify status]
→ Not logged in
[Runs: npx netlify login]
→ Browser opens, user authenticates
[Runs: npx netlify status]
→ Logged in as user@example.com, no site linked
[Runs: npx netlify init]
→ Site created: my-react-app.netlify.app
[Runs: npm install && npx netlify deploy --prod]
→ Website URL: https://my-react-app.netlify.app
"Deployed to production: https://my-react-app.netlify.app"
Example 2: Preview Deploy on Existing Site
User: Push a preview of my changes
[Runs: npx netlify status]
→ Logged in, site: my-react-app
[Runs: npx netlify deploy]
→ Draft URL: https://6425ee--my-react-app.netlify.app
"Preview ready: https://6425ee--my-react-app.netlify.app
Run `npx netlify deploy --prod` to promote to production."
Example 3: Monorepo Subdirectory Deploy
User: Deploy the frontend package from packages/web
[Reads: packages/web/package.json → Vite detected]
[Writes: packages/web/netlify.toml with base = "packages/web"]
[Runs: cd packages/web && npm install && npx netlify deploy --prod]
→ Website URL: https://my-monorepo-web.netlify.app
Safety
Idempotency
Running npx netlify deploy multiple times is safe. Each deploy creates a new immutable snapshot with its own URL. Previous deploys remain accessible via their draft URLs.
Reversibility
Production deploys can be rolled back from the Netlify dashboard (Deploys tab) by publishing a previous deploy. The CLI does not have a direct rollback command.
Prerequisites
Before running, ensure:
- Node.js >= 16 is installed (
node --version) - The project has a
package.jsonor static HTML files - Git remote is configured if using Git-based site linking
- Network access is available (not blocked by sandbox)
Bundled References
- CLI Commands Reference -- Full command reference for
npx netlify - netlify.toml Configuration -- Build config, redirects, headers, and context overrides