neon 2.42.0 → 2.43.0

package/README.md

@@ -650,12 +650,12 @@ The CLI holds one Neon account by default. A profile adds another, and is nothin
 
 ```bash
 neon auth --profile work     # create it, or sign in again
-neon profile list
-neon profile remove work
+neon profiles list
+neon profiles remove work
 ```
 
 ```console
-$ neon profile list
+$ neon profiles list
 Profiles
 ┌────────┬─────────┬──────────────────────┬──────────┬──────────────────────────────────────┐
 │ Active │ Name    │ Account              │ SignedIn │ Credentials                          │
@@ -680,14 +680,87 @@ Entries in `profiles.json` are paths, and a path may point anywhere — which is
 }
 ```
 
-`neon profile remove` revokes the refresh token at the authorization server, not just locally. It deletes the credentials file only when the CLI created it: an adopted path like the one above is unlinked and left on disk, and the command says so. Removing the last named profile deletes `profiles.json`, returning you to the single-account layout. `neon profile remove DEFAULT` signs you out.
+`neon profiles remove` revokes the refresh token at the authorization server, not just locally. It deletes the credentials file only when the CLI created it: an adopted path like the one above is unlinked and left on disk, and the command says so. Removing the last named profile deletes `profiles.json`, returning you to the single-account layout. `neon profiles remove DEFAULT` signs you out.
+
+## API keys (`api-keys`)
+
+```bash
+neon api-keys list                                        # your account's keys
+neon api-keys list --org-id org-…                         # an organization's, with scope shown
+
+neon api-keys create --name ci                            # account key
+neon api-keys create --name ci    --org-id org-…          # organization key
+neon api-keys create --name agent --project-id frosty-…   # can access only that project
+
+neon api-keys revoke <id> [--org-id org-…]
+```
+
+The key is returned once, on create, and cannot be retrieved again. It prints on its own line below the table, so it can be selected in one gesture regardless of terminal width — and `… | tail -1` on stdout yields exactly the key, since both notices go to stderr.
+
+```console
+$ neon api-keys create --name agent --project-id proj-in-org
+API key
+┌─────┬───────┬─────────────┐
+│ Id  │ Name  │ Project     │
+├─────┼───────┼─────────────┤
+│ 303 │ agent │ proj-in-org │
+└─────┴───────┴─────────────┘
+
+napi_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+WARNING: Store this key now: it is not shown again.
+INFO: Limited to proj-in-org: it cannot create projects, mint API keys, or read any other project. It can still change and delete everything inside that project.
+```
+
+`--org-id` and `--project-id` are mutually exclusive. A project-scoped key *is* an organization key, and its organization is looked up from the project rather than chosen separately. With neither flag you get an account key.
+
+### Project-scoped keys
+
+A key created with `--project-id` bounds what it can reach to one project. Verified against a real scoped key:
+
+| Attempt | Result |
+| --- | --- |
+| Read and write its own project | works |
+| Read any other project | `project not found` — not even an existence oracle |
+| `neon projects create` | `project-scoped keys are not allowed to create projects` |
+| `neon projects list` | refused |
+| `neon api-keys create` / `list` | refused (true of any organization key, not only scoped ones) |
+| `neon orgs list` | **works** — it can see the id, name and handle of the organization it belongs to |
+| Anything else about that organization (`GET /organizations/{id}`, members) | refused |
+
+It is **not** read-only. Inside its one project it can do everything the API allows, including deleting branches and the project itself — `neon deploy` working at all is proof of that. What it bounds is *reach*, which is what lets you hand it to an agent or a CI job without handing over your account:
+
+```bash
+neon link --project-id frosty-…       # once, as yourself — writes .neon
+NEON_API_KEY=napi_… neon deploy       # then the agent, reaching only that project
+```
+
+`neon link` needs `--project-id` explicitly when using a scoped key: the interactive picker lists your projects, which a scoped key cannot do.
+
+`api-keys` deliberately ignores the `.neon` context file, unlike every other project command. Otherwise `neon api-keys create --name ci` inside a linked directory would silently mint a key scoped to that project instead of the account key you asked for. How far a credential reaches comes only from a flag you typed.
+
+### Seeing what is scoped
+
+```console
+$ neon api-keys list --org-id org-7
+API keys in org-7
+┌─────┬──────────┬────────────────┬──────────────────────┬──────────────────────┬─────────────────────┐
+│ Id  │ Name     │ Project        │ Created At           │ Last Used At         │ Last Used From Addr │
+├─────┼──────────┼────────────────┼──────────────────────┼──────────────────────┼─────────────────────┤
+│ 301 │ scoped   │ proj-in-org    │ 2026-01-02T00:00:00Z │                      │                     │
+├─────┼──────────┼────────────────┼──────────────────────┼──────────────────────┼─────────────────────┤
+│ 302 │ org-wide │ (all projects) │ 2026-01-03T00:00:00Z │ 2026-02-03T00:00:00Z │ 203.0.113.9         │
+└─────┴──────────┴────────────────┴──────────────────────┴──────────────────────┴─────────────────────┘
+```
+
+`last_used_at` and `last_used_from_addr` are how you spot a key worth revoking.
 
 ## Commands
 
 | Command                                                                    | Subcommands                                                                                                  | Description                        |
 | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------- |
 | [auth](https://neon.com/docs/reference/cli-auth)                           |                                                                                                              | Authenticate                       |
-| profile                                                                    | `list`, `remove`                                                                                             | Manage named sets of credentials   |
+| profiles                                                                   | `list`, `remove`                                                                                             | Manage named sets of credentials   |
+| api-keys                                                                   | `list`, `create`, `revoke`                                                                                   | Manage API keys                    |
 | [projects](https://neon.com/docs/reference/cli-projects)                   | `list`, `create`, `update`, `delete`, `get`                                                                  | Manage projects                    |
 | [ip-allow](https://neon.com/docs/reference/cli-ip-allow)                   | `list`, `add`, `remove`, `reset`                                                                             | Manage IP Allow                    |
 | [me](https://neon.com/docs/reference/cli-me)                               |                                                                                                              | Show current user                  |

package/dist/api.js

@@ -111,9 +111,44 @@ function headersToObject(headers) {
     });
     return out;
 }
+/**
+ * Raised by {@link makeTimedFetch} when the CLI's own request timeout fires. Owning the
+ * type is what makes the timeout recognisable further up: `@neon/sdk` reports every
+ * transport failure as a `NeonNetworkError`, so matching on names or codes cannot tell a
+ * timeout from a reset connection.
+ */
+class RequestTimeoutError extends Error {
+    constructor(timeoutMs, reason) {
+        super(`Request timed out after ${timeoutMs}ms`);
+        this.name = "RequestTimeoutError";
+        this.reason = reason;
+    }
+}
+/**
+ * Whether a failure was a request timeout rather than a connectivity problem.
+ *
+ * Walks the `cause` chain, because the SDK wraps whatever `fetch` threw. Before this, the
+ * check only looked at the top-level error's `name` — which is `NeonNetworkError` on every
+ * SDK path — so a timeout fell through to the connectivity branch and the user was told to
+ * check an internet connection that was working.
+ */
 function isAbortError(err) {
-    return (err instanceof Error &&
-        (err.name === "AbortError" || err.name === "TimeoutError"));
+    let current = err;
+    for (let depth = 0; depth < 6 && current != null; depth++) {
+        if (current instanceof RequestTimeoutError)
+            return true;
+        if (current instanceof Error &&
+            (current.name === "AbortError" || current.name === "TimeoutError")) {
+            return true;
+        }
+        // `@neon/sdk` classifies its own deadlines and cancellations by kind; the CLI
+        // does not set them today, but reading them keeps this correct if it ever does.
+        const kind = current.kind;
+        if (kind === "timeout" || kind === "aborted")
+            return true;
+        current = current.cause;
+    }
+    return false;
 }
 /**
  * Walk an error's `cause` chain to find the underlying socket/DNS `code` (e.g.
@@ -182,17 +217,53 @@ function networkError(err) {
  * and lightweight debug logging of the request line + response status — the
  * fetch-native replacement for the old `axios-debug-log` wiring.
  */
-const timedFetch = async (input, init) => {
-    const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+/**
+ * The largest delay a timer can represent. Above it Node warns
+ * (`TimeoutOverflowWarning`) and fires after 1ms instead.
+ */
+const MAX_TIMER_MS = 2 ** 31 - 1;
+/**
+ * Reject a timeout `AbortSignal.timeout` would refuse or silently mistreat.
+ *
+ * Without this the bad value surfaces as the very failure this classification exists to
+ * prevent: `-1`, `NaN`, `Infinity`, fractions and anything above `4294967295` throw
+ * `ERR_OUT_OF_RANGE` from inside the fetch wrapper, which is then wrapped as a
+ * `NeonNetworkError` and reported as a broken internet connection.
+ *
+ * `0`, and the band from {@link MAX_TIMER_MS} + 1 up to `4294967295`, are worse still:
+ * both are accepted, and both make every request time out immediately — `0` by asking for
+ * it, the band because a timer above the signed 32-bit ceiling collapses to 1ms.
+ */
+function validateRequestTimeout(ms) {
+    if (!Number.isInteger(ms) || ms < 1 || ms > MAX_TIMER_MS) {
+        throw new Error(`requestTimeoutMs must be a whole number of milliseconds between 1 and ${MAX_TIMER_MS}; received ${ms}.`);
+    }
+    return ms;
+}
+const makeTimedFetch = (requestTimeoutMs) => async (input, init) => {
+    const timeout = AbortSignal.timeout(requestTimeoutMs);
     const signal = init?.signal
         ? AbortSignal.any([init.signal, timeout])
         : timeout;
     const method = init?.method ?? (input instanceof Request ? input.method : "GET");
     const url = input instanceof Request ? input.url : String(input);
     log.debug("%s %s", method.toUpperCase(), url);
-    const response = await fetch(input, { ...init, signal });
-    log.debug("%d %s", response.status, response.statusText);
-    return response;
+    try {
+        const response = await fetch(input, { ...init, signal });
+        log.debug("%d %s", response.status, response.statusText);
+        return response;
+    }
+    catch (err) {
+        // Our own timeout fired, and we are the only code that knows that: by the
+        // time this reaches `networkError` the SDK has wrapped it as a
+        // `NeonNetworkError`, and neither its name nor its `cause` chain carries a
+        // string code to recognise. Raise something we own instead of leaving the
+        // classification to guess.
+        if (timeout.aborted && !init?.signal?.aborted) {
+            throw new RequestTimeoutError(requestTimeoutMs, err);
+        }
+        throw err;
+    }
 };
 const RETRY_COUNT = 5;
 const RETRY_DELAY = 3000;
@@ -246,12 +317,15 @@ async function readJsonBody(response) {
         return text;
     }
 }
-export const getApiClient = ({ apiKey, apiHost }) => {
+export const getApiClient = ({ apiKey, apiHost, requestTimeoutMs = REQUEST_TIMEOUT_MS, }) => {
     const baseUrl = apiHost ?? DEFAULT_API_HOST;
+    // Shared by the generated client and the low-level `request()` escape hatch, so both
+    // paths get the same timeout and the same timeout classification.
+    const fetchWithTimeout = makeTimedFetch(validateRequestTimeout(requestTimeoutMs));
     const client = createClient(createConfig({
         auth: () => apiKey,
         baseUrl,
-        fetch: timedFetch,
+        fetch: fetchWithTimeout,
         headers: { "User-Agent": USER_AGENT },
     }));
     /** Await a raw call, unwrap to a `{ data, status, headers }` envelope, or throw {@link NeonApiError}. */
@@ -306,7 +380,7 @@ export const getApiClient = ({ apiKey, apiHost }) => {
         }
         let response;
         try {
-            response = await timedFetch(url, {
+            response = await fetchWithTimeout(url, {
                 method: params.method,
                 headers,
                 ...(payload !== undefined ? { body: payload } : {}),
@@ -346,6 +420,20 @@ export const getApiClient = ({ apiKey, apiHost }) => {
         getCurrentUserOrganizations: () => call(() => raw.getCurrentUserOrganizations({ client })),
         getAuthDetails: () => call(() => raw.getAuthDetails({ client })),
         getActiveRegions: () => call(() => raw.getActiveRegions({ client })),
+        // ─── API keys ────────────────────────────────────────────────────────
+        // Account keys reach everything the account can. Org keys can additionally be
+        // narrowed to a single project via `project_id`, which is the only way to mint a
+        // least-privilege credential — so the org endpoints are not merely the org
+        // equivalent of the account ones.
+        listApiKeys: () => call(() => raw.listApiKeys({ client })),
+        createApiKey: (body) => call(() => raw.createApiKey({ client, body })),
+        revokeApiKey: (keyId) => call(() => raw.revokeApiKey({ client, path: { key_id: keyId } })),
+        listOrgApiKeys: (orgId) => call(() => raw.listOrgApiKeys({ client, path: { org_id: orgId } })),
+        createOrgApiKey: (orgId, body) => call(() => raw.createOrgApiKey({ client, path: { org_id: orgId }, body })),
+        revokeOrgApiKey: (orgId, keyId) => call(() => raw.revokeOrgApiKey({
+            client,
+            path: { org_id: orgId, key_id: keyId },
+        })),
         // ─── Projects ────────────────────────────────────────────────────────
         listProjects: (query = {}) => call(() => raw.listProjects({ client, query })),
         listSharedProjects: (query = {}) => call(() => raw.listSharedProjects({

package/dist/commands/api_keys.js

@@ -0,0 +1,397 @@
+import { isNeonApiError } from "../api.js";
+import { log } from "../log.js";
+import { writer } from "../writer.js";
+const ACCOUNT_FIELDS = [
+    "id",
+    "name",
+    "created_at",
+    "last_used_at",
+    "last_used_from_addr",
+];
+/**
+ * Table view of an org listing. `project` is the rendered column; the raw `project_id` is
+ * what structured output keeps. See {@link list} for why the two differ.
+ */
+const ORG_TABLE_FIELDS = [
+    "id",
+    "name",
+    "project",
+    "created_at",
+    "last_used_at",
+    "last_used_from_addr",
+];
+const ORG_FIELDS = [
+    "id",
+    "name",
+    "project_id",
+    "created_at",
+    "last_used_at",
+    "last_used_from_addr",
+];
+const CREATE_FIELDS = ["id", "name", "key"];
+/** Metadata only: the secret is printed separately so it can be copied cleanly. */
+const CREATE_TABLE_FIELDS = ["id", "name"];
+const CREATE_TABLE_FIELDS_SCOPED = ["id", "name", "project"];
+const CREATE_FIELDS_SCOPED = ["id", "name", "project_id", "key"];
+/** Rendered for an org key that was not narrowed to a project. Table output only. */
+const ALL_PROJECTS = "(all projects)";
+/**
+ * "This key should carry no project scope."
+ *
+ * A symbol rather than a string, because project ids are `^[a-z0-9-]{1,60}$` — any sentinel
+ * spelled as a string is a legal project id, and a project genuinely called that would have
+ * its correctly-scoped key rejected and revoked.
+ */
+const NO_PROJECT = Symbol("no-project");
+/**
+ * A flag is either absent, or exactly one non-empty string. Anything else is an error.
+ *
+ * Every rejected shape otherwise ends the same way: the flag reads as falsy, the scope check
+ * falls through, and an **account** key is minted instead of the narrow one asked for — the
+ * worst thing this command can do, so none of them get a lenient reading.
+ *
+ * - `--project-id ""` — an unset shell variable; empty string, which is falsy.
+ * - `--no-project-id` — yargs boolean negation; `false`, which is falsy.
+ * - `--project-id a --project-id b` — an array, which would reach the API as `a,b`.
+ *
+ * A misspelled flag never binds and cannot be seen here; `.strict()` rejects it. Anything
+ * after a `--` terminator is handled by {@link noPassthrough}.
+ */
+const single = (name, { required = false } = {}) => (value) => {
+    if (value === undefined)
+        return undefined;
+    if (Array.isArray(value)) {
+        throw new Error(`--${name} was given more than once. Pass it at most once.`);
+    }
+    // `--no-x` is the negation form and yields `false`, so name it rather than telling
+    // the user their value was empty when they never gave one.
+    if (value === false) {
+        throw new Error(required
+            ? `--no-${name} is not valid: --${name} is required.`
+            : `--no-${name} is not a valid way to skip --${name}. Omit the flag entirely.`);
+    }
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(required
+            ? `--${name} needs a value.`
+            : `--${name} needs a value. Pass one, or omit the flag entirely.`);
+    }
+    return value;
+};
+/**
+ * Refuse arguments after a `--` terminator.
+ *
+ * The CLI sets `populate--`, so everything past `--` lands in `argv["--"]` where `.strict()`
+ * never looks — `create --name x -- --project-id p` would parse cleanly and mint an account
+ * key from a line that names the scope flag. No `api-keys` subcommand takes passthrough
+ * arguments, so their presence is always a mistake.
+ */
+const noPassthrough = (argv) => {
+    const rest = argv["--"];
+    if (Array.isArray(rest) && rest.length > 0) {
+        throw new Error(`api-keys takes no arguments after \`--\`, and options placed there are ignored rather than applied. Remove the \`--\`.`);
+    }
+    return true;
+};
+export const command = "api-keys";
+export const aliases = ["api-key"];
+export const describe = "Manage API keys";
+export const builder = (argv) => argv
+    .usage("$0 api-keys <sub-command> [options]")
+    .command("list", "List API keys for your account, or for an organization", (yargs) => yargs
+    .options({
+    "org-id": {
+        describe: "List the organization's keys instead of your account's",
+        type: "string",
+        coerce: single("org-id"),
+    },
+})
+    .strict()
+    .check(noPassthrough), async (args) => await list(args))
+    .command("create", "Create an API key. The key is shown once and cannot be retrieved again", (yargs) => yargs
+    .options({
+    name: {
+        describe: "A name to identify the key later",
+        type: "string",
+        demandOption: true,
+        coerce: single("name", { required: true }),
+    },
+    "org-id": {
+        describe: "Create a key for this organization instead of your account",
+        type: "string",
+        coerce: single("org-id"),
+    },
+    "project-id": {
+        describe: "Create a key that can access only this project. Its organization is looked up from the project",
+        type: "string",
+        coerce: single("project-id"),
+    },
+})
+    // A key scoped to a project is already an organization key, so naming
+    // both is contradictory rather than redundant — the org is derived from
+    // the project and cannot be chosen independently.
+    .conflicts("org-id", "project-id")
+    .strict()
+    .check(noPassthrough), async (args) => await create(args))
+    .command("revoke <id>", "Revoke an API key. Anything using it stops working immediately", (yargs) => yargs
+    .positional("id", {
+    describe: "The API key id, from `api-keys list`",
+    // Deliberately not `type: "number"`. That coerces before `coerce`
+    // runs, so an unparseable id arrives as NaN and the error can only
+    // echo `NaN` — a JavaScript artifact the user never typed. Taking
+    // the raw string lets the message name what they actually passed,
+    // and stops NaN reaching the API, which answers "not found" and
+    // blames the key rather than the input.
+    type: "string",
+    demandOption: true,
+    coerce: (value) => {
+        // Digits only, checked before Number(): `Number("0x65")` is 101
+        // and `Number("1e3")` is 1000, so either would revoke a key the
+        // user never named while the message promises "a numeric id".
+        const id = Number(value);
+        if (typeof value !== "string" ||
+            !/^\d+$/.test(value.trim()) ||
+            !Number.isSafeInteger(id) ||
+            id <= 0) {
+            throw new Error(`api-keys revoke needs a numeric key id, from \`neon api-keys list\`. Got \`${String(value)}\`.`);
+        }
+        return id;
+    },
+})
+    .options({
+    "org-id": {
+        describe: "Revoke an organization key instead of an account key",
+        type: "string",
+        coerce: single("org-id"),
+    },
+})
+    .strict()
+    .check(noPassthrough), async (args) => await revoke(args))
+    .demandCommand(1, "Run `neon api-keys --help` to see the subcommands.");
+export const handler = (args) => args;
+const list = async (props) => {
+    const out = writer(props);
+    if (props.orgId) {
+        const { data } = await props.apiClient.listOrgApiKeys(props.orgId);
+        // `writeTable` drops any column empty in every row, so an all-absent `project_id`
+        // would take the whole column with it — hiding the answer exactly when it is "none
+        // of them are scoped". Fill it in for the table, but leave structured output alone:
+        // json/yaml serialize the whole object, so a synthetic field there would change the
+        // machine-readable shape and duplicate `project_id` under a second name.
+        if (props.output === "table") {
+            out.write(data.map((key) => ({
+                ...key,
+                project: key.project_id ?? ALL_PROJECTS,
+            })), {
+                fields: ORG_TABLE_FIELDS,
+                title: `API keys in ${props.orgId}`,
+                emptyMessage: `No API keys in ${props.orgId}.`,
+            });
+        }
+        else {
+            out.write(data, {
+                fields: ORG_FIELDS,
+                title: `API keys in ${props.orgId}`,
+                emptyMessage: `No API keys in ${props.orgId}.`,
+            });
+        }
+        out.end();
+        return;
+    }
+    const { data } = await props.apiClient.listApiKeys();
+    out.write(data, {
+        fields: ACCOUNT_FIELDS,
+        title: "Account API keys",
+        emptyMessage: "You have no account API keys.",
+    });
+    out.end();
+    // Organization keys live on a different endpoint, so a heading of plain "API keys"
+    // would claim to be everything while showing only half.
+    if (props.output === "table") {
+        log.info("Organization keys are listed separately: neon api-keys list --org-id <org> (see `neon orgs list`).");
+    }
+};
+const create = async (props) => {
+    const { name, projectId, orgId } = props;
+    // Neither flag: an account key, matching `POST /api_keys`. `api-keys` is exempt from
+    // `.neon` enrichment (see `isApiKeysCommand`), so reaching this branch means the user
+    // really did ask for account scope rather than inheriting a checked-out project.
+    if (!projectId && !orgId) {
+        const { data } = await props.apiClient.createApiKey({ key_name: name });
+        await assertUsable(props, data, { orgId: null, expect: NO_PROJECT });
+        report(props, data, CREATE_FIELDS, CREATE_TABLE_FIELDS);
+        // The only key here that reaches everything, and the only one that used to say
+        // nothing about its reach.
+        log.warning("This key reaches everything your account can, in every organization. Pass --org-id or --project-id to narrow it.");
+        return;
+    }
+    if (!projectId && orgId) {
+        const { data } = await props.apiClient.createOrgApiKey(orgId, {
+            key_name: name,
+        });
+        await assertUsable(props, data, { orgId, expect: NO_PROJECT });
+        report(props, data, CREATE_FIELDS, CREATE_TABLE_FIELDS);
+        log.warning("This key reaches every project in %s, including ones created later. Pass --project-id instead to restrict it to one.", orgId);
+        return;
+    }
+    const scopeTo = projectId;
+    // Project-scoped keys exist only on the organization endpoint, so an org is required.
+    // Resolve it from the project rather than asking for both: `--project-id` alone would
+    // otherwise fail for a reason that isn't visible from the command line.
+    const resolvedOrgId = await orgIdForProject(props, scopeTo);
+    const { data } = await props.apiClient.createOrgApiKey(resolvedOrgId, {
+        key_name: name,
+        project_id: scopeTo,
+    });
+    // `project_id` is optional on the response. Printing a key and calling it scoped
+    // without checking would hand over a credential whose reach we never confirmed — the
+    // one thing this command must not get wrong.
+    await assertUsable(props, data, {
+        orgId: resolvedOrgId,
+        expect: scopeTo,
+    });
+    report(props, data, CREATE_FIELDS_SCOPED, CREATE_TABLE_FIELDS_SCOPED);
+    log.info("Limited to %s: it cannot create projects, mint API keys, or read any other project. It can still change and delete everything inside that project.", scopeTo);
+};
+/**
+ * Print the issued key.
+ *
+ * In a terminal the secret goes on its own line rather than into a table cell: `cli-table`
+ * neither wraps nor truncates, so a 50-odd character key makes the row wider than most
+ * terminals and the wrapped remainder ends up beside box-drawing characters. Since this is
+ * the only time the key is ever shown, it has to be selectable in one gesture. Structured
+ * output keeps the key in the object, where a script expects it.
+ */
+const report = (props, data, fields, tableFields) => {
+    const out = writer(props);
+    if (props.output === "table") {
+        // `project` mirrors the column name `list` uses. Added here rather than by the
+        // caller so structured output keeps the API's own `project_id` and gains no
+        // duplicate under a second name.
+        const row = typeof data.project_id === "string"
+            ? { ...data, project: data.project_id }
+            : data;
+        out.write(row, {
+            fields: tableFields,
+            title: "API key",
+        });
+        out.end();
+        // Blank line so the key is visually detached from the table border, and so
+        // `| tail -1` on stdout yields exactly the key (both notices go to stderr).
+        out.text(`\n${data.key}\n`);
+    }
+    else {
+        out.write(data, { fields: fields, title: "API key" });
+        out.end();
+    }
+    log.warning("Store this key now: it is not shown again.");
+};
+/**
+ * Refuse to report a key that isn't what we asked for, and take it back.
+ *
+ * Two ways a 2xx can still be wrong: no `key` in the body, which leaves a live credential
+ * the user can never see or use; and a `project_id` that doesn't match the requested
+ * project, which would mean announcing a scope the key does not have. Both withdraw the key
+ * before throwing.
+ *
+ * The thrown message states whether the withdrawal actually succeeded. Saying "the key has
+ * been revoked" when the revoke itself failed would be worse than saying nothing — it would
+ * leave an unverified credential live while telling the user it is gone.
+ */
+const assertUsable = async (props, data, scope) => {
+    // `expect` is always stated, never inferred from a missing field: "no project" has to be
+    // checked as deliberately as an exact project, or a key that came back narrower than
+    // requested would be reported as reaching the whole organization.
+    const wanted = scope.expect === NO_PROJECT ? undefined : scope.expect;
+    const problem = typeof data.key !== "string" || data.key.trim() === ""
+        ? "Neon returned no key."
+        : data.project_id !== wanted
+            ? `Neon returned a key scoped to ${data.project_id ?? "nothing"} rather than ${wanted ?? "the whole organization"}.`
+            : null;
+    if (!problem)
+        return;
+    const withdrawn = await withdraw(props, scope.orgId, data.id);
+    throw new Error(`${problem} ${withdrawn
+        ? "The key has been revoked; nothing was issued."
+        : `The key could NOT be revoked and may still be live${data.id === undefined
+            ? ""
+            : `. Remove it with \`neon api-keys revoke ${data.id}${scope.orgId
+                ? ` --org-id ${scope.orgId}`
+                : ""}\``}.`}`);
+};
+/**
+ * Revoke, turning the most likely mistake into a usable message.
+ *
+ * Account and organization keys live on different endpoints, and `api-keys list --org-id X`
+ * shows ids that the account endpoint cannot see. Copying one and forgetting the flag — or
+ * leaving it on for an account key — is the easy error, and a bare "API key not found" sends
+ * the user looking for a deleted key rather than a misplaced flag.
+ *
+ * Only the key id is worth second-guessing here: an org id that is wrong or not yours does
+ * not reach this path at all, because the API answers "not an organization member" (verified
+ * against production) rather than a 404.
+ */
+const revokeOrExplain = async (props) => {
+    try {
+        return props.orgId
+            ? await props.apiClient.revokeOrgApiKey(props.orgId, props.id)
+            : await props.apiClient.revokeApiKey(props.id);
+    }
+    catch (err) {
+        if (isNeonApiError(err) && err.status === 404) {
+            throw new Error(props.orgId
+                ? `No API key with id ${props.id} in ${props.orgId}. If it is one of your account's own keys, drop --org-id.`
+                : `No account API key with id ${props.id}. If it belongs to an organization, pass --org-id. Organization keys are not visible to your account.`);
+        }
+        throw err;
+    }
+};
+/** Best-effort withdrawal of a key we are refusing to report. Never throws. */
+const withdraw = async (props, orgId, keyId) => {
+    if (!Number.isSafeInteger(keyId) || keyId <= 0)
+        return false;
+    try {
+        const { data } = orgId
+            ? await props.apiClient.revokeOrgApiKey(orgId, keyId)
+            : await props.apiClient.revokeApiKey(keyId);
+        // Check which key the response names: a `revoked: true` for some other id is not
+        // evidence that the one we issued is gone.
+        return data.revoked === true && data.id === keyId;
+    }
+    catch (err) {
+        log.error("Failed to revoke API key %d: %s", keyId, err instanceof Error ? err.message : String(err));
+        return false;
+    }
+};
+const revoke = async (props) => {
+    const out = writer(props);
+    const { data } = await revokeOrExplain(props);
+    out.write(data, {
+        fields: ["id", "name", "revoked", "last_used_at"],
+        title: "API key",
+    });
+    out.end();
+};
+/**
+ * The organization a project belongs to. A project outside any organization cannot have a
+ * scoped key — the endpoint that accepts `project_id` is org-only — so that case fails here
+ * with the reason, rather than as a 404 from a URL the user never typed.
+ */
+const orgIdForProject = async (props, projectId) => {
+    let orgId;
+    try {
+        const { data: { project }, } = await props.apiClient.getProject(projectId);
+        orgId = project.org_id;
+    }
+    catch (err) {
+        if (isNeonApiError(err) && err.status === 404) {
+            throw new Error(projectId.startsWith("org-")
+                ? `Project ${projectId} not found. That looks like an organization id. Pass it as --org-id instead.`
+                : `Project ${projectId} not found. Check the id with \`neon projects list\`.`);
+        }
+        throw err;
+    }
+    if (!orgId) {
+        throw new Error(`Project ${projectId} does not belong to an organization, so it cannot have a project-scoped API key. Create an account key by omitting --project-id.`);
+    }
+    return orgId;
+};

package/dist/commands/index.js

@@ -1,4 +1,5 @@
 import * as api from "./api.js";
+import * as apiKeys from "./api_keys.js";
 import * as auth from "./auth.js";
 import * as bootstrap from "./bootstrap.js";
 import * as branches from "./branches.js";
@@ -32,6 +33,7 @@ import * as vpcEndpoints from "./vpc_endpoints.js";
 export default [
     auth,
     profile,
+    apiKeys,
     api,
     users,
     orgs,

package/dist/commands/profile.js

@@ -6,11 +6,11 @@ import { isCi } from "../env.js";
 import { log } from "../log.js";
 import { DEFAULT_PROFILE, listProfiles, onlyDefaultRemains, profilesFilePath, readProfiles, resolveProfile, selectProfileName, } from "../profiles.js";
 import { writer } from "../writer.js";
-export const command = "profile";
-export const aliases = ["profiles"];
+export const command = "profiles";
+export const aliases = ["profile"];
 export const describe = "Manage named sets of Neon credentials";
 export const builder = (argv) => argv
-    .usage("$0 profile <sub-command> [options]")
+    .usage("$0 profiles <sub-command> [options]")
     .command("list", "List profiles, the account each holds, and where its credentials live", (y) => y, async (args) => await list(args))
     .command("remove <name>", "Revoke a profile's token and remove it", (y) => y
     .positional("name", {
@@ -24,7 +24,7 @@ export const builder = (argv) => argv
     type: "boolean",
     default: false,
 }), async (args) => await remove(args))
-    .demandCommand(1, "Run `neon profile --help` to see the subcommands.");
+    .demandCommand(1, "Run `neon profiles --help` to see the subcommands.");
 export const handler = (_args) => {
     /* subcommands only */
 };

package/dist/context.js

@@ -49,6 +49,11 @@ export const isConfigInit = (args) => args._[0] === "config" &&
  * access has already lapsed is the main reason to remove one.
  */
 export const isProfileCommand = (args) => args._[0] === "profile" || args._[0] === "profiles";
+/**
+ * `neon api-keys …`, under either spelling. Exempts the group from context enrichment: how
+ * far a credential reaches must come from an explicit flag, never from `.neon`.
+ */
+export const isApiKeysCommand = (args) => args._[0] === "api-keys" || args._[0] === "api-key";
 const CONTEXT_FILE = ".neon";
 const GITIGNORE_FILE = ".gitignore";
 const canAccessFile = (file) => {
@@ -116,6 +121,13 @@ export const enrichFromContext = (args) => {
     if (args._[0] === "link" || args._[0] === "set-context") {
         return;
     }
+    // `api-keys` mints credentials, and how far a credential reaches must be something the
+    // user typed — never something inherited from whichever project happens to be checked
+    // out. Enriched here, `api-keys create --name ci` in a linked directory would quietly
+    // produce a key scoped to that project instead of the account key it asked for.
+    if (isApiKeysCommand(args)) {
+        return;
+    }
     const context = readContextFile(args.contextFile);
     if (!args.orgId) {
         args.orgId = context.orgId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "2.42.0",
+  "version": "2.43.0",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -55,10 +55,10 @@
     "which": "3.0.1",
     "yaml": "^2.9.0",
     "yargs": "17.7.2",
-    "@neon/sdk": "1.4.1",
-    "@neon/config": "0.13.1",
-    "@neon/config-runtime": "0.12.2",
-    "@neon/env": "0.13.2",
+    "@neon/sdk": "1.5.0",
+    "@neon/config": "0.13.2",
+    "@neon/config-runtime": "0.12.3",
+    "@neon/env": "0.13.3",
     "neon-init": "0.20.6"
   },
   "optionalDependencies": {