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]

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:

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 open to view in Netlify dashboard
• Any build warnings or errors from the deploy log

Verification

Success Indicators

• npx netlify deploy exits with code 0
• Output contains Website draft URL: or Website URL: with a valid HTTPS link
• The URL is accessible (HTTP 200) when fetched

Failure Handling

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 [email protected], 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.json or 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