netlify-cli-and-deploy
Guide for using the Netlify CLI and deploying sites. Use when installing the CLI, linking sites, deploying (Git-based or manual), managing environment variables, or running local development. Covers netlify dev, netlify deploy, Git vs non-Git workflows, and environment variable management.
- Installs
- 1K
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/netlify/context-and-tools --skill netlify-cli-and-deploy- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads netlify-cli-and-deploy automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Netlify CLI and Deployment
Installation
npm install -g netlify-cli # Global (for local dev)
npm install netlify-cli -D # Local (for CI)
Requires Node.js 18.14.0+.
Authentication
netlify login # Opens browser for OAuth
netlify status # Check auth + linked site status
For CI, set NETLIFY_AUTH_TOKEN environment variable instead.
CI also needs a site to target. NETLIFY_AUTH_TOKEN only authenticates you — it does not select which site a deploy publishes to. In CI there is no linked .netlify/state.json, so also set NETLIFY_SITE_ID (the site's API/Project ID, shown as Project ID in the site's configuration) as an environment variable so netlify deploy knows where to publish. Without it, a CI deploy has no site to target and fails or tries to prompt. Locally this is handled by netlify link, which writes the site ID into .netlify/state.json; CI has no such file.
Linking a Site
Check if already linked with netlify status. If not:
# Interactive
netlify link
# By Git remote (if using Git)
netlify link --git-remote-url https://github.com/org/repo
# Create new site
netlify init # With Git CI/CD setup
netlify init --manual # Without Git CI/CD
Site ID is stored in .netlify/state.json. Add .netlify to .gitignore.
Deploying
Git-Based Deploys (Continuous Deployment)
Set up with netlify init. Automatic deploys trigger on push/PR:
- Push to production branch → production deploy
- Open PR → deploy preview with unique URL
- Push to other branches → branch deploy only if branch deploys are enabled — they are off by default; turn them on (per branch or for all branches) in the site's build & deploy settings
Build runs on Netlify's servers. Configure build settings in netlify.toml.
netlify.toml overrides the UI. File-based configuration in netlify.toml takes precedence over the equivalent build settings configured in the Netlify UI. When the same option is set in both places, the committed netlify.toml wins — editing that setting in the dashboard has no effect until you change the file and redeploy. This surprises people who tweak the build command, publish directory, or base directory in the UI and watch the old committed value keep applying on every deploy.
Monorepo config discovery order. In a monorepo, Netlify searches for the netlify.toml in this order and uses the first one it finds: (1) the package directory, then (2) the base directory, then (3) the repository root. Put a site-specific netlify.toml in the package directory (the subdirectory that contains that site) so it takes precedence over any root-level config. A base directory set in a root-level netlify.toml also overrides the base directory configured in the UI.
Manual / Local Deploys (No Git Required)
Build locally, then upload:
netlify deploy # Draft deploy (preview URL)
netlify deploy --prod # Production deploy
netlify deploy --dir=dist # Specify output directory
This works without Git — useful for prototypes, local-only projects, or CI pipelines.
A manual --prod deploy is replaced by the next Git push. If the same site also has Git continuous deployment connected, the next push to the production branch triggers a new build that auto-publishes and replaces your manually shipped --prod deploy — the hand-shipped build silently disappears from production. To keep a specific deploy live, lock the published deploy ("Stop auto publishing") from the site's Deploys list in the UI: while locked, new pushes still build but do not auto-publish until you unlock or manually publish. Mixing manual --prod deploys with Git CD on the same production branch is otherwise a race the next commit wins.
Deploy URLs are public by link
Draft deploys (netlify deploy), Deploy Previews, branch deploys, and deploy permalinks each get a unique URL that anyone with the link can open — they are not private just because the URL is unguessable and unlisted. Don't treat a preview URL as a safe place for confidential or unreleased content on that basis alone. To actually restrict access, enable site protection in the UI (Password Protection, or Team/SSO protection); you can protect all deploys or only non-production deploys.
Local Development
Option 1: netlify dev
netlify dev
Wraps your framework's dev server and provides:
- Environment variable injection
- Functions and edge functions
- Redirects and headers processing
Option 2: Netlify Vite Plugin (Vite-based projects)
For projects using Vite (React SPA, TanStack Start, SvelteKit, Remix), the Vite plugin provides Netlify platform primitives directly in the framework's dev server:
npm install @netlify/vite-plugin
// vite.config.ts
import netlify from "@netlify/vite-plugin";
export default defineConfig({ plugins: [netlify()] });
Then run your normal dev command (npm run dev) — no netlify dev wrapper needed. This gives you access to Blobs, DB, Functions, and environment variables during development.
See the netlify-frameworks skill for framework-specific local dev guidance.
Environment Variables
CLI Management
# Set
netlify env:set API_KEY "value"
netlify env:set API_KEY "value" --secret # Hidden from logs
netlify env:set API_KEY "value" --context production # Context-specific
# Get
netlify env:get API_KEY
# List
netlify env:list
netlify env:list --plain > .env # Export to file
# Import from file
netlify env:import .env
# Delete
netlify env:unset API_KEY
Context Scoping
Variables can be scoped to deploy contexts:
netlify env:set API_URL "https://api.prod.com" --context production
netlify env:set API_URL "https://api.staging.com" --context deploy-preview
netlify env:set DEBUG "true" --context branch:feature-x
Accessing in Code
- Server-side (Functions): Use
Netlify.env.get("VAR")(preferred) orprocess.env.VAR - Client-side (Vite): Only
VITE_-prefixed vars viaimport.meta.env.VITE_VAR - Client-side (Astro): Only
PUBLIC_-prefixed vars viaimport.meta.env.PUBLIC_VAR
Never use VITE_ or PUBLIC_ prefix for secrets — these are exposed to the browser.
When a command fails, surface and stop
When a netlify command, a deploy, or netlify dev fails, report the failure to the user with the exact error, the deploy log URL (the CLI prints one), and the affected site/branch — and stop. Do not invent recovery commands or escalate to lower-level tools: do not curl https://api.netlify.com/..., do not run netlify api <method> as a recovery hatch, and do not read auth tokens off disk to force the operation through. If the documented happy path is broken, that's a platform-state problem the user needs to see.
Useful Commands
| Command | Description |
|---|---|
netlify status | Auth and site link status |
netlify dev | Start local dev server |
netlify build | Run build locally (mimics Netlify environment) |
netlify deploy | Draft deploy |
netlify deploy --prod | Production deploy |
netlify dev:exec <cmd> | Run command with Netlify environment loaded |
netlify env:list | List environment variables |
netlify clone org/repo | Clone, link, and set up in one step |
FAQ
What does the netlify-cli-and-deploy skill do?
Guide for using the Netlify CLI and deploying sites. Use when installing the CLI, linking sites, deploying (Git-based or manual), managing environment variables, or running local development. Covers netlify dev, netlify deploy, Git vs non-Git workflows, and environment variable management.
How do I install netlify-cli-and-deploy?
Run npx skills add https://github.com/netlify/context-and-tools --skill netlify-cli-and-deploy in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/netlify-cli-and-deploy/ (personal) or .claude/skills/netlify-cli-and-deploy/ (project).
Which AI agents can use netlify-cli-and-deploy?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is netlify-cli-and-deploy safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains netlify-cli-and-deploy?
It is published by netlify in netlify/context-and-tools. It has 1,041 recorded installs.
More from netlify/context-and-tools
netlify-deploy
netlify/context-and-tools
Create, configure, and manage Netlify deploys from code — reach for this when setting up Git continuous deployment, running netlify deploy or netlify deploy --prod from the CLI, writing netlify.toml deploy contexts, adding a Deploy to Netlify button, wiring build hooks, configuring Deploy Previews or branch deploys, locking or skipping deploys, fixing a failed or secrets-scanning deploy, or when someone asks to "deploy my site", "set up preview deploys", "add per-branch build config", "keep staging out of Google", or "add a deploy button to my README".
netlify-config
netlify/context-and-tools
Configure Netlify builds and routing via netlify.toml, redirects, and headers. Use when setting a build command or publish directory, adding redirects or rewrites or proxies, adding an SPA fallback rewrite, setting custom response headers or basic auth, managing environment variables and secrets, scoping vars per deploy context, marking a var as secret, disabling secret scanning, configuring functions bundling, ignoring builds, or wiring up a monorepo or JavaScript SPA on Netlify.
netlify-functions
netlify/context-and-tools
Write, configure, and deploy Netlify serverless functions in TypeScript, JavaScript, or Go. Use this when adding an API endpoint or backend route, adding a contact form handler, wiring auth or Identity signup/login hooks, identifying which Netlify user is calling a private or team-login-protected app, building streaming or AI-proxy responses, scheduling cron jobs, running long background jobs (batch processing/scraping), reacting to deploy or form events, setting up rate limiting or region/memory config, or reading environment variables and secrets inside a function. Covers file locations, the Request/Context/Response handler shape, path routing, config options, and local testing with netlify dev.
netlify-frameworks
netlify/context-and-tools
Deploy and configure web frameworks on Netlify — build settings and SSR/edge adapters plus local platform emulation and env vars. Use when setting up or fixing a framework deploy (Next.js / Astro / Nuxt / SvelteKit / Remix / React Router / TanStack Start / SolidStart / Gatsby / Angular / Vite / Express / Hydrogen / Hugo / Eleventy / Vue / React), adding SSR or edge functions or middleware wired to Netlify context, fixing SPA redirect and catch-all rules, setting a build command or publish directory, or debugging "why isn't my env var updating" and framework build failures.
netlify-edge-functions
netlify/context-and-tools
Write, route, cache, and debug Netlify Edge Functions, the Deno-based TypeScript or JavaScript handlers in netlify/edge-functions that run at the network edge in front of static files and serverless functions. Activate this skill whenever someone wants to add auth middleware or a login gate, redirect or rewrite visitors by country or cookie, localize or personalize a page with geolocation, run A/B testing, transform or inject HTML into a response, stream server-side rendering at the edge, or cache an edge response. Also use it when an edge function silently does nothing, runs in the wrong order, ignores its Cache-Control headers, or cannot read an environment variable.
netlify-forms
netlify/context-and-tools
Serverless form handling on Netlify-hosted sites — detects HTML forms at deploy time, stores submissions, filters spam, and sends notifications. Use when adding a contact form, lead-capture form, file-upload form, or newsletter signup to a Netlify site; wiring AJAX form submission; setting up a custom thank-you page; adding a honeypot or reCAPTCHA to a form; getting forms working in Next.js, Nuxt, SvelteKit, Astro, or Gatsby; reading form submissions via the Netlify API; setting up submission notifications or ChatGPT automations on form submission events; or debugging missing submissions and forms that silently fail to register.
Popular devops & cloud skills
microsoft-foundry
microsoft/azure-skills
Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent create, managed harness agent create, GitHub Copilot harness agent, create agent, update agent, add tool to agent, invoke agent, agent insights, evaluate agent, batch eval, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, optimize agent instructions, Agent Optimizer scaffold, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure
azure-diagnostics
microsoft/azure-skills
Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, container app 503 or target port mismatch, troubleshoot functions, function telemetry missing or stopped after a config/connection-string change, troubleshoot AKS, VM RDP, Linux SSH, VM black screen, can't connect to VM, reset VM password, NSG or firewall blocking, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, lock renewal during long-running processing, service bus dead letter.
azure-prepare
microsoft/azure-skills
Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure.
azure-ai
microsoft/azure-skills
Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.
azure-deploy
microsoft/azure-skills
Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: "run azd up", "run azd deploy", "execute deployment", "push to production", "push to cloud", "go live", "ship it", "bicep deploy", "terraform apply", "publish to Azure", "launch on Azure". DO NOT USE WHEN: "create and deploy", "build and deploy", "create a new app", "set up infrastructure", "create and deploy to Azure using Terraform" — use azure-prepare for these.
azure-validate
microsoft/azure-skills
Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis, validate Container Apps deployment.