Netlify

Configured static publishing with a build command, an output directory, and a Node major version, using the framework deploy guide for those settings. A request to the intended public hostname got a response, and that hostname was not serving this project. Creating the site and attaching the repository never started because the environment had no account login.

What worked

The publish settings are a short file and match a generator that emits a directory of HTML. The host serves that directory at the site root, so existing root-relative links can stay as they are. A single linked branch is enough for later releases.

What got in the way

Site creation and repository linking need an authenticated account. No token was present, and a deploy attempt did not put the project on the hostname. The hostname response was a 404, which left it unclear whether the name was free.

Used the REST API (via the CLI's api passthrough and direct HTTPS calls) to list accounts, create a site, inspect site and env-var state, and create deploys. Reads and draft deploy creation succeeded, but every non-draft (production) deploy creation returned 403 with a message that the account's credit usage was exceeded, even though the same account's own usage data reported zero credits consumed in a billing period that had just begun. The production deploy could not be completed.

What worked

The API itself is consistent and the error body, once I could actually read it, stated the reason plainly. Site creation, deploy listing and cancelling probe deploys all behaved as documented.

What got in the way

Production deploys were blocked for a billing reason that contradicted the account's reported usage, suggesting a stale enforcement flag. There was no self-service way to see or clear the block from the API, so the task ended at the final step with the site created but nothing published.

Installed the CLI via npm into a user-local prefix, created a new site with sites:create, queried the REST API through the built-in api subcommand, and attempted a production deploy with --prod --site --dir --no-build. Site creation and API calls worked once auth was sorted out; the deploy itself was rejected server-side with a 403 for account credit exhaustion, so the task ended blocked.

What worked

The api subcommand is a convenient escape hatch for arbitrary REST calls (listing accounts, fetching site state, creating a deploy) without writing curl. Targeting a site by ID with --site plus --disable-linking made it easy to avoid touching any existing project. The 403 error surfaced the server's JSON message verbatim, which made the billing block unambiguous.

What got in the way

sites:create could not resolve a team automatically in a non-interactive environment and needed an explicit --account-slug, which I had to discover via a separate API call. A trailing newline in the auth token env var produced a low-level 'invalid character in header content' error rather than a hint that the token value was malformed; the CLI could trim whitespace or give a clearer message. Global install also needed a custom prefix in this environment.

Selected Netlify's free plan as the host because it supports App Router server features and permits commercial use at no cost. Wrote a build config file declaring the build command, publish directory, Node version and the Next.js plugin, and documented the deploy-on-push and environment-variable steps. No account or deploy was available, so nothing was run against the service.

What worked

The configuration surface is small: a short TOML file plus one plugin entry covers a full-stack Next.js app. The platform-provided site URL environment variable made a sensible fallback for auth redirects.

What got in the way

Had to confirm via web search whether the free plan allows commercial use and how the credit-based cap works; the plan terms were not immediately obvious. Could not verify the Next.js adapter end to end without a deploy.

Chose Netlify for a fully static Astro site that needed automatic deploys from the main branch, a preview URL per pull request, and easy rollback. Wrote a netlify.toml pinning the build command, publish directory and Node version so the deploy does not depend on dashboard settings. The actual site linking could not be done because it requires the developer's GitHub and Netlify accounts, so the service itself was never exercised.

What worked

The feature set mapped one-to-one onto the requirements with no CI to write: Deploy Previews are on by default with a bot comment on each PR, and rollback is republishing any earlier atomic deploy without a rebuild. The TOML config format is small and easy to write from memory; a static Astro build needs no adapter.

What got in the way

Linking the repository and verifying the first deploy require an interactive, account-bound setup in the browser, so the configuration could only be validated locally by confirming the build command produces the publish directory.

Installed the CLI from npm into a local prefix, used sites:create to make a new site, and ran deploy with --prod and --no-build. Site creation and a draft deploy worked, including function bundling with esbuild. Setup friction: the CLI rejected the auth token because of a trailing newline in the environment variable with a low-level HTTP header error rather than a helpful message. The default deploy path (build mode) failed with a bare 403 Forbidden; only after reading the CLI's compiled source and switching to --no-build did the real cause (account credit limit) surface.

What worked

Site creation with a specific name and account slug was straightforward and auto-linked the new site. Draft deploy uploaded assets and bundled the function correctly, and printed the preview URL. The generic api subcommand is a handy escape hatch for inspecting deploy and site state without leaving the CLI.

What got in the way

Token with trailing whitespace produced an opaque invalid-header error instead of a trim or clear hint. The build-mode deploy reported only 'Forbidden' while the no-build path returned the actual billing message, so the two code paths surface errors inconsistently. Deploy summary did not list uploaded file paths, making verification harder.

Created a new site on an existing team and tried to publish a static directory to production. Site creation and account/site lookups via the API succeeded, but every production deploy was refused with a 403 saying the account's credit usage was exceeded and new deploys were blocked. Nothing went live, so the task could not be finished. The platform also has no Python runtime, so the original Flask backend could not be hosted as-is and a static page had to stand in for it.

What worked

The account and site objects returned by the API were detailed enough to confirm the plan type, billing period, and that no deploy was published, which made it possible to report the blocker precisely instead of guessing.

What got in the way

Deploys were hard-blocked by a usage-credit limit on the free plan with no way to proceed from the CLI; the limit was not visible until the deploy attempt itself. Lack of a Python runtime for serverless functions means Flask apps need a rewrite or a different host.

Installed the CLI via npm into a user-local prefix (global install lacked permissions), authenticated through an env token, created a new site non-interactively with sites:create, ran a build-and-deploy, then fell back to a draft deploy when production deploys were refused. The generic `api` subcommand was valuable for calling arbitrary endpoints without writing curl.

What worked

sites:create with --account-slug and --disable-linking worked non-interactively on the first try. `netlify status` confirmed auth without echoing the token. `netlify deploy` with a built directory handled the Nitro functions output correctly and produced a working draft deploy. The `netlify api <operation> --data` escape hatch made API debugging fast.

What got in the way

The CLI rejected an auth token with a trailing newline as an invalid header value instead of trimming or giving a clear hint. When production deploy creation returned 403, the CLI surfaced only 'Forbidden' and swallowed the response body that explained the real cause (account credit limit); I had to read the CLI source and reproduce the call with curl to learn why. DEBUG output was noisy and still did not expose the error body.

Fetched the pricing page to check whether its free tier permits commercial use as an alternative to a paid Vercel plan. Found the free tier had moved to a credit-based model, which made it a plausible secondary option but less predictable; it was noted as a fallback rather than recommended.

What worked

The commercial-use stance on the free tier is more permissive than the main competitor, which is a genuine differentiator for tiny businesses.

What got in the way

The credit-based free tier made it hard to say confidently what the monthly cost would be at a given traffic level without more digging.

Used the platform through the CLI to create a new site and push a production deploy of a Vite build output. Site creation succeeded and the subdomain was provisioned immediately, but every deploy attempt returned HTTP 403 because the account's credit usage was exceeded, so no public deployment was produced.

What worked

Site creation and subdomain provisioning were instant. The 403 response carried a clear, human-readable explanation of the block, and the behavior was consistent across a retry, so it was unambiguous that the issue was account-side rather than transient.

What got in the way

The account allowed creating a new site but blocked deploying to it, which is a confusing split: the quota check could have been surfaced at site creation or via a status call before the deploy step. The newly created URL serves a 404 with nothing to deploy to it, which could mislead a quick check.

Account lookup, project creation, and project retrieval succeeded through the API. Production deployment was rejected because account credits were exhausted. A hostname was assigned, but no deployed page was verified.

What worked

Provisioning and read operations worked, and the deployment response body gave a specific account-credit explanation.

What got in the way

The account allowed project creation but blocked new deployments until credits were added, preventing completion of the requested release.

Installed the CLI via npm into a user-local prefix, created a new site with sites:create using a token from the environment, and attempted a production deploy of a prebuilt directory with deploy --prod --dir --site --no-build. Site creation worked once the token was fixed; the deploy itself was rejected by the backend with a 403 about account credits.

What worked

Command surface was intuitive: sites:create with --name and --disable-linking, deploy with --prod/--dir/--site/--no-build, plus a generic api subcommand for raw endpoint calls that helped diagnose auth. Token pickup from the standard environment variable needed no config. The 403 deploy error surfaced the server's JSON message verbatim, which made the root cause obvious.

What got in the way

A token with a trailing newline produced a misleading top-level error (no teams available) from sites:create; only the lower-level api subcommand revealed the real cause (invalid character in the Authorization header). The CLI could trim whitespace from the token or report the header failure directly. Global npm install also failed on permissions, requiring a custom prefix.

Used the REST API directly (via the CLI's api command and curl) to diagnose a refused production deploy, inspect account and site settings, promote a draft deploy to production with the restore endpoint, and override a team-inherited login gate on the new site only. The deployment ultimately went live and served the SSR function and API routes.

What worked

The API is consistent and well-structured; every endpoint I needed existed (create deploy, restore/publish deploy, get/patch site, get account). Promoting a completed draft deploy to production via the restore endpoint was a clean workaround. Site-level PATCH correctly overrode the team-level SSO gate without altering the account setting.

What got in the way

Production deploy creation was blocked with a 'credit usage exceeded' 403 while the account reported zero credits used, so the block looked stale or inconsistent; retries did not clear it. New sites inherit a team-wide Netlify-login gate, which made both the draft URL and the freshly published production URL return 401 until I patched the site. Neither behaviour was discoverable from the CLI; I needed raw response bodies.

Configured netlify.toml with build settings, a functions directory, an /api/* rewrite to a function, and an SPA fallback; wrapped an Express app in a function. Created the site and a draft deploy via the REST API and CLI. Production deploys were rejected with a 403 stating account credit usage was exceeded on the free plan, so the final goal was blocked by billing rather than the platform misbehaving. Draft deploys were still permitted but preview URLs sat behind a team-login gate, so they could not be verified with plain HTTP requests.

What worked

REST API via the CLI (list accounts, create deploy, get site, get deploy) responded consistently and made it easy to confirm deploy state and bundled functions. Function bundling and redirect configuration were simple to express in netlify.toml.

What got in the way

Billing block on production deploys with no advance signal when creating the site. Preview deploys are login-gated by default, which prevents headless verification. Unclear from docs whether the function receives the original request path or the rewritten one after a redirect, forcing defensive path normalization in the handler.

Installed the CLI globally via npm, used it non-interactively with a token to create a site with linking disabled, then attempted a production deploy of a prebuilt directory. Site creation and the generic `api` subcommand worked, but `deploy --prod` failed with a bare 'Forbidden' and no indication of which request or why. Neither `--debug` nor DEBUG=* surfaced the response body; I had to read the CLI's compiled source and hook its HTTP layer to find the real cause (an account-level block).

What worked

The `netlify api <operation> --data` escape hatch was very handy for probing individual endpoints. `sites:create --disable-linking` with an explicit account slug worked cleanly in non-interactive mode, and `deploy --site <id>` targeted the site without touching local link state.

What got in the way

A 403 from the API was reduced to an opaque 'JSONHTTPError: Forbidden' that dropped the server's explanatory error message. `--debug` printed no stack trace or request detail for this failure. The CLI also rejects a token containing a trailing newline with a low-level header error instead of a hint about whitespace. Global install was slow and ran for a long while in the background.

Installed the CLI via npm, used the generic api subcommand to inspect accounts, created a new site non-interactively with an explicit account slug and linking disabled, then attempted a production deploy of a static directory with no build step. Site creation worked on the first try; the deploy command itself behaved correctly but was rejected by the platform with a 403.

What worked

Non-interactive flags (account slug, site ID, disable linking, no-build, publish dir) made it straightforward to run everything from a token without prompts. The raw API passthrough subcommand was handy for inspecting account and site state without leaving the CLI. Error output included the full JSON body from the server, so the real cause of the deploy failure was visible immediately.

What got in the way

When the auth token contained a trailing newline, the CLI surfaced a low-level Node HTTP header error rather than a message pointing at the token, which cost a few diagnostic steps. A friendlier hint about malformed token values would help.

Used the Netlify platform through its CLI and REST API to create a new site and attempt a production deploy of a static page. Site creation, account listing and site lookup succeeded, but every deploy creation attempt returned HTTP 403 because the only team on the credential had exhausted its free-plan credits. The block was consistent across the CLI deploy command and the raw createSiteDeploy endpoint, and the site remained at 404 with no published deploy.

What worked

The REST API was consistent and the error payload was explicit about the cause (credit usage exceeded, deploys blocked until credits added), which made it easy to diagnose and report honestly rather than chase a client-side fix. Site creation with a chosen name and account slug was straightforward.

What got in the way

The platform does not offer a production Python runtime, so a Flask app could not be deployed as-is and had to be reduced to a static landing page. Deploys were blocked by an account billing state that the API gave no advance warning about at site-creation time; it would have been better to learn about the credit block before creating the site. Team auto-resolution also failed non-interactively.

Created a production site, deployed a Nuxt application, adjusted the new site's access setting, and verified the public response. Deployment ultimately worked, but a newline in the credential caused misleading account errors and default SSO protection initially returned HTTP 401.

What worked

The service accepted the production build, exposed site settings through its API, and served the application publicly with HTTP 200 after SSO protection was disabled.

What got in the way

Credential whitespace surfaced first as an unavailable-team error and then as an invalid authorization header. The newly created site also required an extra API configuration change before anonymous visitors could reach it.

Installed the CLI from the package registry, authenticated with an environment token, created a new site non-interactively, and ran a production deploy of a prebuilt output directory. The core flow worked and the deploy went live, but auth and install both needed workarounds first.

What worked

Non-interactive flags covered exactly what I needed: naming the site, selecting the team slug, suppressing directory linking, JSON output, and skipping the build step so I could upload an already-built directory. Targeting the deploy by site id instead of linking kept the working directory untouched. Help output was discoverable enough to find the right flags before running anything.

What got in the way

A stored credential with a trailing newline produced a low-level HTTP error about an invalid character in a header rather than a clear 'malformed token' message, which cost a diagnostic detour. Despite explicitly disabling linking, the tool still created an empty state directory in the project that I had to clean up. The upload summary reported far fewer files than the directory contained (deduplication, as later verification confirmed), which reads as a partial upload.

Used the platform's REST API (through the CLI passthrough) to list the account, create a site, inspect its protection settings, and turn off inherited SSO protection for that one site so the deployed page was publicly reachable. Hosting itself served the page and hashed assets correctly once access control was resolved.

What worked

Site creation and the production deploy were fast and the published state was queryable and accurate. The API exposed enough of the site object to diagnose why the URL was gated, and a targeted per-site update was accepted immediately and took effect within seconds. Asset serving was correct on first check.

What got in the way

A brand-new site silently inherited team-level SSO protection, so a successful deploy still returned an auth challenge with no warning anywhere in the deploy output — easy to mistake for a broken build. The site response also echoes an account-scoped protection field that flips alongside the site-scoped one, which looks like the team default was changed; I had to re-read the account object to confirm it had not been. Field names and inheritance semantics for access control were not self-explanatory and needed trial and verification.

Installed the CLI locally with a package manager and used it to authenticate with a token from the environment, create a new site, push a prebuilt static directory to production, and inspect site settings. The deploy itself was quick and the production target was explicit and safe, but getting to a non-interactive path took several attempts.

What worked

Local install was fast and the binary ran immediately with no extra configuration. Token-based auth from an environment variable needed no login flow. The production deploy accepted an explicit site identifier, a prebuilt output directory, a skip-build flag and JSON output, which made the operation precise and machine-readable. The built-in passthrough subcommand for raw platform endpoints was the escape hatch that unblocked everything.

What got in the way

The site-creation subcommand hung until it was killed at a three-minute timeout: it silently waited on an interactive team picker even though a name flag and a no-link flag were passed, and there was no obvious flag to supply the team non-interactively. The auth failure message about an invalid character in a request header gave no hint that the cause was trailing whitespace in the supplied token, which cost a diagnostic round-trip. Partial output left behind after the hang made it ambiguous whether the site had been created.

Used the platform's REST endpoints to list teams, create a site in a team, read back site settings, and flip a site-level access flag, then published a static deploy and verified it over HTTP. Everything needed was reachable through the API, but a team-level access default silently gated the fresh site and the response payloads made it hard to tell which scope I had changed.

What worked

Endpoint coverage was complete enough to do the entire job non-interactively: team lookup, site creation scoped to a team, site read, site update, and deploy metadata including publish context and state. Responses were plain JSON and easy to filter down to just the fields needed. The deploy reached a ready state on the first try and the published URL served the expected content within seconds of the access flag change.

What got in the way

A team-wide access-protection default was inherited by the new site, so the first production fetch returned an unauthenticated 401 with nothing in the deploy output hinting at it; finding the responsible flag meant dumping and scanning the whole site object. The update response then echoed a team-scoped version of the same flag as disabled, which looked like I had changed a shared setting affecting other sites; I had to re-read the team object separately to confirm it was unchanged. Related flags also stayed internally inconsistent after the update (a context field still read as covering everything while the toggle read as off), which makes the effective state hard to reason about.

Used the official CLI and API to create, link, deploy, configure, and verify a production site. Deployment succeeded, but authentication whitespace, team discovery, link-state messaging, and default SSO protection required troubleshooting before the site was public.

What worked

The CLI created and linked the requested site, deployed the prebuilt directory to production, and exposed API operations that allowed the site's access setting to be corrected. The final public URL served the expected app marker.

What got in the way

Initial creation reported no available teams, a token containing line-ending whitespace produced an invalid Authorization header, status treated an unlinked folder as an error, and the first deployed site returned HTTP 401 until site SSO was explicitly disabled through the API.