@kody/netlify

@kody/netlify

Intent

Reusable Netlify REST helpers so Kody agents can inspect the caller's sites, deploys, environment-variable metadata, and forms — not a shared platform account. Auth is a saved personal access token. Reads are free-form. Mutations (create-deploy, restore-deploy, create-env-var, and mutating request calls) support dryRun: true, and live writes also require confirm: true.

This listing is meant to be forked. After you fork, save your own netlifyToken and call the helpers in your account. No personal site ids or team slugs are hard-coded. Environment-variable listing returns keys, scopes, and contexts only — values are never returned.

Share this package as https://kody.codes/@kody/netlify

Auth

Create a Netlify personal access token, then save it in Kody (do not paste the value in chat):

https://kody.codes/account/secrets/new?name=netlifyToken&description=Netlify%20personal%20access%20token%20(Bearer%20for%20api.netlify.com)&allowedHosts=api.netlify.com&scope=user

1. Open User settings → Applications → Personal access tokens.
2. Create a token. If the team uses SAML SSO, grant the token access to that team.
3. Save it at the URL above. In the account secrets UI, approve host api.netlify.com.
4. Smoke-test with ./smoke-test (see Smoke test).

Default helper input: omit secretName. The package sends Authorization: Bearer using netlifyToken.

Pass account: "work" to use secret netlifyToken-work, or pass secretName: "netlifyToken-team". There are no hard-coded account aliases.

Hosts

• api.netlify.com — all REST calls (required)
• app.netlify.com — token dashboard (setup only)

Mutation safety

Pass dryRun: true on create-deploy, restore-deploy, create-env-var, and mutating request calls to return { dryRun: true, method, path, body } without contacting Netlify.

Those same writes also throw unless confirm: true.

restore-deploy publishes the chosen deploy to the site's production URL. Do not restore or create production deploys unless the caller explicitly confirmed that target.

Env-var dry-run previews redact value. Listing env vars never returns values.

import createDeploy from 'kody:@kody/netlify/create-deploy'

const preview = await createDeploy({
	site: 'example-site',
	draft: true,
	dryRun: true,
})

The optional site-status job lists sites on a 12-hour cron and starts disabled.

Smoke test

import netlify from 'kody:@kody/netlify'

export default async function main() {
	return await netlify({ dryRun: true })
}

Without netlifyToken a live call still returns { ok: true, live: false } plus the setup URLs. With credentials it reads a trimmed /user profile — no writes.

Exports

• kody:@kody/netlify — action dispatcher (defaults to smoke-test)
• kody:@kody/netlify/request — low-level Netlify REST helper (escape hatch)
• kody:@kody/netlify/get-user — authenticated user (read-only)
• kody:@kody/netlify/list-accounts — teams the token can see (read-only)
• kody:@kody/netlify/list-sites — sites (read-only)
• kody:@kody/netlify/get-site — site detail (read-only)
• kody:@kody/netlify/list-deploys — site deploys (read-only)
• kody:@kody/netlify/get-deploy — deploy detail (read-only)
• kody:@kody/netlify/create-deploy — create deploy (dryRun / confirm)
• kody:@kody/netlify/restore-deploy — publish a previous deploy (dryRun / confirm)
• kody:@kody/netlify/list-env-vars — env-var metadata, no values (read-only)
• kody:@kody/netlify/create-env-var — create env var (dryRun / confirm)
• kody:@kody/netlify/list-forms — site forms (read-only)
• kody:@kody/netlify/list-form-submissions — form submissions (read-only)
• kody:@kody/netlify/smoke-test — credential smoke test (read-only)
• kody:@kody/netlify/scheduled-status — read-only site list used by the disabled job

Examples

import listSites from 'kody:@kody/netlify/list-sites'

export default async function main() {
	return await listSites({ per_page: 20 })
}

import listDeploys from 'kody:@kody/netlify/list-deploys'

export default async function main() {
	return await listDeploys({ site: 'example-site', per_page: 10 })
}

import listEnvVars from 'kody:@kody/netlify/list-env-vars'

export default async function main() {
	return await listEnvVars({ site: 'example-site' })
}

import listForms from 'kody:@kody/netlify/list-forms'

export default async function main() {
	return await listForms({ site: 'example-site' })
}

Branding

community-icon.svg is Netlify's official monogram from the Netlify press / brand assets kit (full-color light mode). Netlify is a trademark of Netlify, Inc. This package is not affiliated with or endorsed by Netlify.

Docs

• Get started with the Netlify API
• OpenAPI reference
• Personal access tokens