neonctl 2.33.1 → 2.34.0

package/README.md

@@ -505,6 +505,50 @@ $ neon bootstrap . --template hono
 
 The target directory must be empty unless you pass `--force` (a lone `.git` is ignored, so a freshly `git init`ed folder is fine). Symlinks and executable bits in the template are preserved.
 
+## Snapshots (`snapshots`)
+
+`neon snapshots` (alias `neon snapshot`) manages **snapshots** — point-in-time backups of a branch that you can list, rename, expire, restore into a branch, or schedule automatically. Snapshots are a Beta Neon feature and were previously only available in the Console and REST API; this command group brings them to the CLI.
+
+Every sub-command resolves the project through the standard chain (`--project-id`, then the `.neon` context file, then a single-project auto-detect). Branch-scoped sub-commands (`create`, `schedule`) default to the branch pinned in `.neon`, falling back to the project's default branch, and accept `--branch <id|name>`. The `get`, `update`, `delete`, and `restore` sub-commands take a snapshot **id or name** as their positional argument (an id wins; an ambiguous name errors and asks you to use the id).
+
+```bash
+# Snapshot the head of the current/default branch
+neon snapshots create --name pre-migration
+
+# Snapshot a specific branch at a point in time (RFC 3339 timestamp OR LSN — mutually exclusive)
+neon snapshots create --branch main --timestamp 2025-01-01T00:00:00Z
+neon snapshots create --branch main --lsn 0/1F3C8A0 --expires-at 2025-12-31T23:59:59Z
+
+# List / inspect
+neon snapshots list
+neon snapshots get pre-migration
+
+# Rename or change expiration (omit both to error; --expires-at and --clear-expiration conflict)
+neon snapshots update snap-1234 --name nightly
+neon snapshots update snap-1234 --expires-at 2030-01-01T00:00:00Z
+neon snapshots update snap-1234 --clear-expiration      # keep indefinitely
+
+# Restore a snapshot to a NEW branch
+neon snapshots restore snap-1234 --name recovered
+
+# Restore ONTO an existing branch. Without --finalize the restore is left un-finalized
+# so you can inspect it first, then swap it in:
+neon snapshots restore snap-1234 --target-branch main
+neon snapshots finalize br-restored-1234                # commit the swap
+# …or do it in one step:
+neon snapshots restore snap-1234 --target-branch main --finalize
+
+# Delete
+neon snapshots delete snap-1234
+
+# Automatic snapshot (backup) schedule of a branch
+neon snapshots schedule get --branch main
+neon snapshots schedule set --branch main --frequency daily --hour 3 --retention 604800
+neon snapshots schedule set --branch main --schedule '[{"frequency":"hourly"},{"frequency":"daily","hour":3}]'
+```
+
+All sub-commands honor the [global options](#global-options), including `--output json|yaml|table`.
+
 ## Commands
 
 | Command                                                                    | Subcommands                                                                                                  | Description                        |
@@ -518,6 +562,7 @@ The target directory must be empty unless you pass `--force` (a lone `.git` is i
 | function                                                                   | `deploy`, `list`, `get`, `delete`                                                                            | Manage Neon Functions              |
 | [roles](https://neon.com/docs/reference/cli-roles)                         | `list`, `create`, `delete`                                                                                   | Manage roles                       |
 | [operations](https://neon.com/docs/reference/cli-operations)               | `list`                                                                                                       | Manage operations                  |
+| snapshots                                                                  | `list`, `get`, `create`, `update`, `delete`, `restore`, `finalize`, `schedule get`, `schedule set`           | Manage snapshots                   |
 | [connection-string](https://neon.com/docs/reference/cli-connection-string) |                                                                                                              | Get connection string              |
 | [psql](https://neon.com/docs/reference/cli-psql)                           |                                                                                                              | Connect to a database via psql     |
 | set-context                                                                |                                                                                                              | Deprecated; use `link`             |

package/dist/analytics.js

@@ -17,6 +17,7 @@ const hasCurrentBranchArgv = () => process.argv.includes("--current-branch");
 let client;
 let clientInitialized = false;
 let userId = "";
+let errorEventContext;
 /**
  * Phase 1: Run before validation so the Segment client exists if any
  * middleware (e.g. auth) fails. Enables sendError() in the fail handler.
@@ -34,6 +35,7 @@ export const initAnalyticsClientMiddleware = (args) => {
         return;
     }
     clientInitialized = true;
+    errorEventContext = getErrorAnalyticsEventContext(args);
     client = new Analytics({
         writeKey: WRITE_KEY,
         host: "https://track.neon.tech",
@@ -112,6 +114,18 @@ export const closeAnalytics = async (opts) => {
         log.debug("Flushed CLI analytics");
     }
 };
+export const getErrorAnalyticsEventProperties = (err, errCode, context) => {
+    const apiError = isNeonApiError(err) ? err : undefined;
+    const requestId = apiError?.headers?.["x-neon-ret-request-id"];
+    return {
+        ...context,
+        message: err.message,
+        stack: err.stack,
+        errCode,
+        statusCode: apiError?.status,
+        requestId,
+    };
+};
 export const sendError = (err, errCode) => {
     if (!client) {
         return;
@@ -124,13 +138,7 @@ export const sendError = (err, errCode) => {
     client.track({
         event: "CLI Error",
         userId: userId || "anonymous",
-        properties: {
-            message: err.message,
-            stack: err.stack,
-            errCode,
-            statusCode: apiError?.status,
-            requestId: requestId,
-        },
+        properties: getErrorAnalyticsEventProperties(err, errCode, errorEventContext),
     });
     log.debug("Sent CLI error event: %s", errCode);
 };
@@ -145,6 +153,10 @@ export const trackEvent = (event, properties) => {
     });
     log.debug("Sent CLI event: %s", event);
 };
+const getErrorAnalyticsEventContext = (_args) => ({
+    version: pkg.version,
+    ci: isCi(),
+});
 export const getAnalyticsEventProperties = (args) => ({
     version: pkg.version,
     command: args._.join(" "),

package/dist/api.js

@@ -423,6 +423,44 @@ export const getApiClient = ({ apiKey, apiHost }) => {
             path: { project_id: projectId },
             body: data,
         })),
+        // ─── Snapshots ───────────────────────────────────────────────────────
+        listSnapshots: (projectId) => call(() => raw.listSnapshots({
+            client,
+            path: { project_id: projectId },
+        })),
+        createSnapshot: (projectId, branchId, query) => call(() => raw.createSnapshot({
+            client,
+            path: { project_id: projectId, branch_id: branchId },
+            ...(query !== undefined ? { query } : {}),
+        })),
+        updateSnapshot: (projectId, snapshotId, data) => call(() => raw.updateSnapshot({
+            client,
+            path: { project_id: projectId, snapshot_id: snapshotId },
+            body: data,
+        })),
+        deleteSnapshot: (projectId, snapshotId) => call(() => raw.deleteSnapshot({
+            client,
+            path: { project_id: projectId, snapshot_id: snapshotId },
+        })),
+        restoreSnapshot: (projectId, snapshotId, data) => call(() => raw.restoreSnapshot({
+            client,
+            path: { project_id: projectId, snapshot_id: snapshotId },
+            ...(data !== undefined ? { body: data } : {}),
+        })),
+        finalizeRestoreBranch: (projectId, branchId, data) => call(() => raw.finalizeRestoreBranch({
+            client,
+            path: { project_id: projectId, branch_id: branchId },
+            ...(data !== undefined ? { body: data } : {}),
+        })),
+        getSnapshotSchedule: (projectId, branchId) => call(() => raw.getSnapshotSchedule({
+            client,
+            path: { project_id: projectId, branch_id: branchId },
+        })),
+        setSnapshotSchedule: (projectId, branchId, data) => call(() => raw.setSnapshotSchedule({
+            client,
+            path: { project_id: projectId, branch_id: branchId },
+            body: data,
+        })),
         // ─── Databases ───────────────────────────────────────────────────────
         listProjectBranchDatabases: (projectId, branchId) => call(() => raw.listProjectBranchDatabases({
             client,

package/dist/commands/index.js

@@ -23,6 +23,7 @@ import * as projects from "./projects.js";
 import * as psql from "./psql.js";
 import * as roles from "./roles.js";
 import * as setContext from "./set_context.js";
+import * as snapshots from "./snapshots.js";
 import * as status from "./status.js";
 import * as users from "./user.js";
 import * as vpcEndpoints from "./vpc_endpoints.js";
@@ -39,6 +40,7 @@ export default [
     databases,
     roles,
     operations,
+    snapshots,
     cs,
     psql,
     setContext,

package/dist/commands/snapshots.js

@@ -0,0 +1,448 @@
+import { retryOnLock } from "../api.js";
+import { log } from "../log.js";
+import { branchIdResolve, fillSingleProject, resolveBranchRef, } from "../utils/enrichers.js";
+import { looksLikeLSN, looksLikeTimestamp } from "../utils/formats.js";
+import { writer } from "../writer.js";
+import { BRANCH_FIELDS } from "./branches.js";
+export const SNAPSHOT_FIELDS = [
+    "id",
+    "name",
+    "source_branch_id",
+    "created_at",
+    "expires_at",
+];
+const SCHEDULE_FIELDS = [
+    "frequency",
+    "hour",
+    "day",
+    "month",
+    "retention_seconds",
+];
+const OPERATION_FIELDS = [
+    "id",
+    "action",
+    "status",
+];
+const SNAPSHOT_FREQUENCIES = [
+    "hourly",
+    "daily",
+    "weekly",
+    "monthly",
+    "yearly",
+];
+export const command = "snapshots";
+export const describe = "Manage snapshots";
+export const aliases = ["snapshot"];
+export const builder = (argv) => argv
+    .usage("$0 snapshots <sub-command> [options]")
+    .options({
+    "project-id": {
+        describe: "Project ID",
+        type: "string",
+    },
+})
+    .middleware(fillSingleProject)
+    .command("list", "List snapshots in the project", (yargs) => yargs, (args) => list(args))
+    .command("get <id>", "Get a snapshot by id or name", (yargs) => yargs, (args) => get(args))
+    .command("create", "Create a snapshot from a branch", (yargs) => yargs
+    .options({
+    branch: {
+        alias: "b",
+        describe: "Branch id or name to snapshot. Defaults to the branch in your context, or the project's default branch.",
+        type: "string",
+    },
+    name: {
+        describe: "A name for the snapshot",
+        type: "string",
+    },
+    timestamp: {
+        describe: "Take the snapshot at this point in time (RFC 3339, e.g. 2025-01-01T00:00:00Z). Must fall within the branch's restore window. Mutually exclusive with --lsn.",
+        type: "string",
+    },
+    lsn: {
+        describe: "Take the snapshot at this LSN (e.g. 0/1F3C8A0). Must fall within the branch's restore window. Mutually exclusive with --timestamp.",
+        type: "string",
+    },
+    "expires-at": {
+        describe: "When the snapshot is automatically deleted (RFC 3339, e.g. 2025-12-31T23:59:59Z). Omit to keep it indefinitely.",
+        type: "string",
+    },
+})
+    .conflicts("timestamp", "lsn")
+    .example([
+    [
+        "$0 snapshots create",
+        "Snapshot the head of the context/default branch",
+    ],
+    [
+        "$0 snapshots create --branch main --name pre-migration",
+        "Snapshot the head of main with a name",
+    ],
+    [
+        "$0 snapshots create --branch main --timestamp 2025-01-01T00:00:00Z",
+        "Snapshot main at a point in time",
+    ],
+    [
+        "$0 snapshots create --branch main --lsn 0/1F3C8A0 --expires-at 2025-12-31T23:59:59Z",
+        "Snapshot main at an LSN, auto-deleting at the given time",
+    ],
+]), (args) => create(args))
+    .command("update <id>", "Update a snapshot's name or expiration", (yargs) => yargs
+    .options({
+    name: {
+        describe: "Rename the snapshot",
+        type: "string",
+    },
+    "expires-at": {
+        describe: "Set when the snapshot expires (RFC 3339). Mutually exclusive with --clear-expiration.",
+        type: "string",
+    },
+    "clear-expiration": {
+        describe: "Clear the expiration so the snapshot is kept indefinitely.",
+        type: "boolean",
+    },
+})
+    .conflicts("expires-at", "clear-expiration"), (args) => update(args))
+    .command("delete <id>", "Delete a snapshot by id or name", (yargs) => yargs, (args) => deleteSnapshot(args))
+    .command("restore <id>", "Restore a snapshot into a branch", (yargs) => yargs
+    .options({
+    name: {
+        describe: "Name for the newly restored branch. Auto-generated when omitted.",
+        type: "string",
+    },
+    "target-branch": {
+        describe: "Branch id or name to restore the snapshot onto. Defaults to the snapshot's source branch. Recommended when you intend to finalize (replace an existing branch).",
+        type: "string",
+    },
+    finalize: {
+        describe: "Finalize the restore immediately: move computes onto the restored branch and swap it in for the target. Without this, the restore is left un-finalized so you can inspect it first, then run `snapshots finalize <branch>`.",
+        type: "boolean",
+        default: false,
+    },
+})
+    .example([
+    [
+        "$0 snapshots restore snap-1234 --name recovered",
+        "Restore a snapshot to a new branch named 'recovered'",
+    ],
+    [
+        "$0 snapshots restore snap-1234 --target-branch main --finalize",
+        "Restore onto main and swap it in immediately",
+    ],
+    [
+        "$0 snapshots restore snap-1234 --target-branch main",
+        "Restore onto main un-finalized to preview, then run `snapshots finalize`",
+    ],
+]), (args) => restore(args))
+    .command("finalize <branch>", "Finalize a previewed snapshot restore (swap the restored branch in)", (yargs) => yargs.options({
+    name: {
+        describe: "Name to give the replaced (old) branch. Auto-generated when omitted.",
+        type: "string",
+    },
+}), (args) => finalize(args))
+    .command("schedule", "Manage the automatic snapshot (backup) schedule of a branch", (yargs) => yargs
+    .usage("$0 snapshots schedule <sub-command> [options]")
+    .command("get", "Get a branch's automatic snapshot schedule", (yargs) => yargs.options({
+    branch: {
+        alias: "b",
+        describe: "Branch id or name. Defaults to the branch in your context, or the project's default branch.",
+        type: "string",
+    },
+}), (args) => scheduleGet(args))
+    .command("set", "Set a branch's automatic snapshot schedule", (yargs) => yargs
+    .options({
+    branch: {
+        alias: "b",
+        describe: "Branch id or name. Defaults to the branch in your context, or the project's default branch.",
+        type: "string",
+    },
+    frequency: {
+        describe: "How often to take snapshots. Builds a single-entry schedule together with --hour/--day/--month/--retention.",
+        choices: SNAPSHOT_FREQUENCIES,
+        type: "string",
+    },
+    hour: {
+        describe: "Hour of the day (0-23) to take the snapshot (used with --frequency).",
+        type: "number",
+    },
+    day: {
+        describe: "Day of the week/month (1-31) to take the snapshot (used with --frequency).",
+        type: "number",
+    },
+    month: {
+        describe: "Month of the year (1-12) to take the snapshot (used with --frequency).",
+        type: "number",
+    },
+    retention: {
+        describe: "How long to keep each snapshot, in seconds (min 3600). Omit to keep indefinitely.",
+        type: "number",
+    },
+    schedule: {
+        describe: 'Full schedule as JSON, for multi-entry schedules, e.g. \'[{"frequency":"daily","hour":3,"retention_seconds":604800}]\'. Overrides the single-entry flags.',
+        type: "string",
+    },
+})
+    .example([
+    [
+        "$0 snapshots schedule set --branch main --frequency daily --hour 3 --retention 604800",
+        "A daily 03:00 snapshot kept for 7 days",
+    ],
+    [
+        '$0 snapshots schedule set --branch main --schedule \'[{"frequency":"hourly"},{"frequency":"daily","hour":3}]\'',
+        "A multi-entry schedule via JSON",
+    ],
+]), (args) => scheduleSet(args))
+    .demandCommand(1, "Specify `get` or `set`."), () => { })
+    .demandCommand(1, "Specify a snapshots sub-command.");
+export const handler = (args) => {
+    return args;
+};
+/** Narrow an unknown parsed JSON value to a plain object without type casting. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Normalize a user-supplied date to an ISO 8601 string, or throw a friendly error. */
+const toIso = (value, flag) => {
+    const ms = Date.parse(value);
+    if (Number.isNaN(ms)) {
+        throw new Error(`Invalid ${flag} value: "${value}". Use an RFC 3339 timestamp, e.g. 2025-12-31T23:59:59Z.`);
+    }
+    return new Date(ms).toISOString();
+};
+/**
+ * Resolve a snapshot from an id **or** a name. Snapshot names are not guaranteed
+ * unique, so an id match wins; a name that resolves to more than one snapshot is a
+ * hard error asking the user to disambiguate by id.
+ */
+const resolveSnapshot = async (props) => {
+    const { data: { snapshots }, } = await props.apiClient.listSnapshots(props.projectId);
+    const byId = snapshots.find((s) => s.id === props.id);
+    if (byId) {
+        return byId;
+    }
+    const byName = snapshots.filter((s) => s.name === props.id);
+    if (byName.length === 1) {
+        return byName[0];
+    }
+    if (byName.length > 1) {
+        throw new Error(`Multiple snapshots are named "${props.id}". Re-run with the snapshot id:\n${byName
+            .map((s) => `  ${s.id}`)
+            .join("\n")}`);
+    }
+    throw new Error(`Snapshot "${props.id}" not found.\nAvailable snapshots: ${snapshots.map((s) => `${s.name} (${s.id})`).join(", ") ||
+        "none"}`);
+};
+const list = async (props) => {
+    const { data: { snapshots }, } = await props.apiClient.listSnapshots(props.projectId);
+    writer(props).end(snapshots, {
+        fields: SNAPSHOT_FIELDS,
+        title: "snapshots",
+        emptyMessage: "No snapshots found. Create one with:\n> neon snapshots create --help",
+        renderColumns: {
+            expires_at: (s) => s.expires_at || "never",
+        },
+    });
+};
+const get = async (props) => {
+    const snapshot = await resolveSnapshot(props);
+    writer(props).end(snapshot, {
+        fields: SNAPSHOT_FIELDS,
+        renderColumns: {
+            expires_at: (s) => s.expires_at || "never",
+        },
+    });
+};
+const create = async (props) => {
+    if (props.lsn !== undefined && !looksLikeLSN(props.lsn)) {
+        throw new Error(`Invalid --lsn value: "${props.lsn}". Expected an LSN like 0/1F3C8A0.`);
+    }
+    if (props.timestamp !== undefined && !looksLikeTimestamp(props.timestamp)) {
+        throw new Error(`Invalid --timestamp value: "${props.timestamp}". Use an RFC 3339 timestamp, e.g. 2025-01-01T00:00:00Z.`);
+    }
+    const { branchId } = await resolveBranchRef({
+        ...props,
+        branch: props.branch,
+    });
+    const { data } = await retryOnLock(() => props.apiClient.createSnapshot(props.projectId, branchId, {
+        name: props.name,
+        timestamp: props.timestamp,
+        lsn: props.lsn,
+        expires_at: props.expiresAt
+            ? toIso(props.expiresAt, "--expires-at")
+            : undefined,
+    }));
+    writer(props).end(data.snapshot, {
+        fields: SNAPSHOT_FIELDS,
+        title: "snapshot",
+        renderColumns: {
+            expires_at: (s) => s.expires_at || "never",
+        },
+    });
+};
+const update = async (props) => {
+    if (props.name === undefined &&
+        props.expiresAt === undefined &&
+        !props.clearExpiration) {
+        throw new Error("Nothing to update. Pass --name, --expires-at, or --clear-expiration.");
+    }
+    const snapshot = await resolveSnapshot(props);
+    // `undefined` fields are dropped by JSON serialization, so an omitted
+    // `expires_at` leaves the expiration unchanged while an explicit `null`
+    // clears it.
+    const expiresAt = props.clearExpiration
+        ? null
+        : props.expiresAt !== undefined
+            ? toIso(props.expiresAt, "--expires-at")
+            : undefined;
+    const { data } = await retryOnLock(() => props.apiClient.updateSnapshot(props.projectId, snapshot.id, {
+        snapshot: {
+            name: props.name,
+            expires_at: expiresAt,
+        },
+    }));
+    writer(props).end(data.snapshot, {
+        fields: SNAPSHOT_FIELDS,
+        renderColumns: {
+            expires_at: (s) => s.expires_at || "never",
+        },
+    });
+};
+const deleteSnapshot = async (props) => {
+    const snapshot = await resolveSnapshot(props);
+    await retryOnLock(() => props.apiClient.deleteSnapshot(props.projectId, snapshot.id));
+    // The delete endpoint returns the tracking operations (202), not the snapshot
+    // body, so echo the snapshot we just deleted for confirmation.
+    writer(props).end(snapshot, {
+        fields: SNAPSHOT_FIELDS,
+        renderColumns: {
+            expires_at: (s) => s.expires_at || "never",
+        },
+    });
+};
+const restore = async (props) => {
+    const snapshot = await resolveSnapshot(props);
+    const targetBranchId = props.targetBranch
+        ? await branchIdResolve({
+            branch: props.targetBranch,
+            projectId: props.projectId,
+            apiClient: props.apiClient,
+        })
+        : undefined;
+    const { data } = await retryOnLock(() => props.apiClient.restoreSnapshot(props.projectId, snapshot.id, {
+        name: props.name,
+        target_branch_id: targetBranchId,
+        finalize_restore: props.finalize,
+    }));
+    const out = writer(props).write(data.branch, {
+        fields: BRANCH_FIELDS,
+        title: "restored branch",
+    });
+    if (data.operations?.length) {
+        out.write(data.operations, {
+            fields: OPERATION_FIELDS,
+            title: "operations",
+        });
+    }
+    out.end();
+    if (!props.finalize) {
+        log.info(`Restore left un-finalized. Inspect branch ${data.branch.id}, then run:\n  neon snapshots finalize ${data.branch.id} --project-id ${props.projectId}`);
+    }
+};
+const finalize = async (props) => {
+    const branchId = await branchIdResolve({
+        branch: props.branch,
+        projectId: props.projectId,
+        apiClient: props.apiClient,
+    });
+    const { data } = await retryOnLock(() => props.apiClient.finalizeRestoreBranch(props.projectId, branchId, props.name ? { name: props.name } : undefined));
+    writer(props).end(data.operations ?? [], {
+        fields: OPERATION_FIELDS,
+        title: "operations",
+        emptyMessage: `Finalized restore for branch ${branchId}.`,
+    });
+};
+const scheduleGet = async (props) => {
+    const { branchId } = await resolveBranchRef({
+        ...props,
+        branch: props.branch,
+    });
+    const { data } = await props.apiClient.getSnapshotSchedule(props.projectId, branchId);
+    writer(props).end(data.schedule, {
+        fields: SCHEDULE_FIELDS,
+        title: "schedule",
+        emptyMessage: "No automatic snapshot schedule is configured.",
+    });
+};
+/**
+ * Validate an untrusted parsed value as a {@link BackupScheduleItem}[] without any
+ * type casting, throwing a clear error for the first invalid field it finds.
+ */
+const parseScheduleJson = (raw) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("--schedule must be valid JSON.");
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error('--schedule must be a JSON array of schedule entries, e.g. \'[{"frequency":"daily","hour":3}]\'.');
+    }
+    return parsed.map((entry, index) => {
+        if (!isRecord(entry)) {
+            throw new Error(`--schedule entry ${index} must be an object.`);
+        }
+        const record = entry;
+        const frequency = record.frequency;
+        if (typeof frequency !== "string") {
+            throw new Error(`--schedule entry ${index} is missing a string "frequency".`);
+        }
+        const item = { frequency };
+        for (const key of [
+            "hour",
+            "day",
+            "month",
+            "retention_seconds",
+        ]) {
+            const value = record[key];
+            if (value === undefined) {
+                continue;
+            }
+            if (typeof value !== "number") {
+                throw new Error(`--schedule entry ${index} field "${key}" must be a number.`);
+            }
+            item[key] = value;
+        }
+        return item;
+    });
+};
+const scheduleSet = async (props) => {
+    const { branchId } = await resolveBranchRef({
+        ...props,
+        branch: props.branch,
+    });
+    let schedule;
+    if (props.schedule) {
+        schedule = parseScheduleJson(props.schedule);
+    }
+    else if (props.frequency) {
+        const item = { frequency: props.frequency };
+        if (props.hour !== undefined)
+            item.hour = props.hour;
+        if (props.day !== undefined)
+            item.day = props.day;
+        if (props.month !== undefined)
+            item.month = props.month;
+        if (props.retention !== undefined)
+            item.retention_seconds = props.retention;
+        schedule = [item];
+    }
+    else {
+        throw new Error("Provide --frequency (optionally with --hour/--day/--month/--retention) or --schedule <json>.");
+    }
+    await retryOnLock(() => props.apiClient.setSnapshotSchedule(props.projectId, branchId, {
+        schedule,
+    }));
+    writer(props).end(schedule, {
+        fields: SCHEDULE_FIELDS,
+        title: "schedule",
+    });
+};

package/dist/utils/ai_gateway_notice.js

@@ -10,8 +10,8 @@ import { log } from "../log.js";
  *  - **Free plan** — credentials provision, but the gateway does not *serve* model requests.
  *    The account needs to upgrade to a paid plan.
  *  - **Reduced model set** — on a paid plan, an account still ramping up on the beta gets a
- *    trimmed model catalog (flagship models are missing from `/v1/models`). They can request
- *    access to more models.
+ *    trimmed model catalog (flagship models are listed but `enabled: false` on `/v1/models`).
+ *    They can request access to more models.
  *
  * This is deliberately phrased for the user: it never mentions account "verification" or any
  * other internal gating mechanism.
@@ -39,11 +39,11 @@ export const aiGatewayModelsUrl = (projectId, branchId) => `https://console.neon
 export const isFreePlan = (subscriptionType) => subscriptionType !== undefined &&
     FREE_SUBSCRIPTION_TYPES.has(subscriptionType);
 /**
- * Whether a model catalog includes at least one flagship model. Flagship models (Anthropic
- * Opus, OpenAI Codex / `*-pro`) are the first to be held back for an account still ramping
- * up on the beta, so their total absence from a non-empty catalog is the signal that the
- * account has a reduced model set. Matched by id substring so it survives model version
- * bumps (e.g. `claude-opus-4-8`).
+ * Whether the model catalog includes at least one flagship model enabled. Flagship models
+ * (Anthropic Opus, OpenAI Codex / `*-pro`) are the first to be held back for an account still
+ * ramping up on the beta, so their total absence from a non-empty enabled set is the signal
+ * that the account has a reduced model set. Matched by id substring so it survives model
+ * version bumps (e.g. `claude-opus-4-8`).
  */
 export const hasFlagshipModels = (modelIds) => modelIds.some((id) => id.includes("opus") || id.includes("codex") || id.endsWith("-pro"));
 /**
@@ -86,20 +86,27 @@ export const buildAiGatewayNotice = ({ subscriptionType, modelIds, upgradeUrl, m
     return null;
 };
 const isRecord = (value) => typeof value === "object" && value !== null;
-/** Pull the string `id`s out of an OpenAI-compatible `{ object: "list", data: [...] }` body. */
-const extractModelIds = (body) => {
+/**
+ * Pull the `id`s of enabled models out of an OpenAI-compatible
+ * `{ object: "list", data: [{ id, enabled, ... }] }` body. The gateway lists every model in
+ * the catalog but marks ones the account can't serve yet with `enabled: false`; only the
+ * enabled set is used to detect a reduced catalog.
+ */
+export const extractEnabledModelIds = (body) => {
     if (!isRecord(body) || !Array.isArray(body.data))
         return null;
     const ids = [];
     for (const entry of body.data) {
-        if (isRecord(entry) && typeof entry.id === "string") {
+        if (isRecord(entry) &&
+            typeof entry.id === "string" &&
+            entry.enabled === true) {
             ids.push(entry.id);
         }
     }
     return ids;
 };
 /**
- * `GET {baseUrl}/v1/models` → the served model ids, or `null` if the catalog can't be read
+ * `GET {baseUrl}/v1/models` → the enabled model ids, or `null` if the catalog can't be read
  * (network / HTTP / parse failure). Returning `null` keeps the notice silent rather than
  * risking a false "reduced models" warning. `/v1/models` is served only on the unified
  * dialect (the `/openai/v1` Responses dialect returns 404).
@@ -111,7 +118,7 @@ export const fetchGatewayModelIds = async (baseUrl, token) => {
         });
         if (!res.ok)
             return null;
-        return extractModelIds(await res.json());
+        return extractEnabledModelIds(await res.json());
     }
     catch {
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neonctl",
-  "version": "2.33.1",
+  "version": "2.34.0",
   "description": "CLI tool for Neon Serverless Postgres",
   "keywords": [
     "neon",
@@ -52,9 +52,9 @@
     "yaml": "^2.9.0",
     "yargs": "17.7.2",
     "@neon/sdk": "1.1.1",
+    "@neon/config": "0.9.4",
     "@neon/config-runtime": "0.9.4",
-    "@neon/env": "0.11.3",
-    "@neon/config": "0.9.4"
+    "@neon/env": "0.11.3"
   },
   "optionalDependencies": {
     "esbuild": "0.28.1"