neon 3.0.0 → 3.1.1

package/README.md

@@ -421,9 +421,9 @@ The human-readable summary line goes to stderr and the diff body to stdout, so `
 
 **What gets pulled**, in precedence order:
 
-1. **`--service`**, when you pass it — exactly those services, whatever else is on the branch and whatever a `neon.ts` says.
+1. **`--service` and/or `--env`**, when you pass either — their union is the complete selection, ignoring `neon.ts` and unselected branch variables. `--service` adds a service's complete variable bundle; `--env` adds only the individual variables you name.
 2. **`neon.ts`**, when the working directory has one — the policy is the source of truth, same as `neon dev` and `neon deploy`.
-3. **Everything the branch has** otherwise — Postgres, Neon Auth, the Data API, and object storage read back from the branch, plus the AI Gateway. The gateway has no branch-level state to read back (it is credential-gated, not provisioned), so a bare `env pull` asks for it rather than detecting it, which mints a branch credential. To leave it out, name the services you do want with `--service`.
+3. **Everything the branch has** otherwise — Postgres, Neon Auth, the Data API, and object storage read back from the branch, plus the AI Gateway. The gateway has no branch-level state to read back, so a bare `env pull` asks for it rather than detecting it and may mint a branch credential. To leave it out, name only what you do want with `--service` and/or `--env`.
 
 If the gateway can't be resolved, it is dropped with a warning and the rest of the pull still lands. Gateway variables already in your file for *this* branch are left alone — a pull that couldn't reach the gateway is no evidence the branch has stopped having one — while ones left over from a different branch are pruned like any other stale value.
 
@@ -440,6 +440,13 @@ neon env pull --service ai-gateway
 # Repeat the flag or comma-separate; -s, --service and --services are all accepted
 neon env pull -s postgres -s data-api
 neon env pull -s postgres,auth
+
+# Pull one exact variable; repeat -e or comma-separate for more
+neon env pull -e DATABASE_URL
+neon env pull -e DATABASE_URL,NEON_AUTH_BASE_URL
+
+# The selectors compose as a union: all Auth vars plus DATABASE_URL
+neon env pull -s auth -e DATABASE_URL
 ```
 
 Every services flag in the CLI takes those three spellings, the same value syntax, and the same service names — see [`config init --services`](#getting-a-neonts-config-init).
@@ -452,11 +459,15 @@ Every services flag in the CLI takes those three spellings, the same value synta
 | `object-storage` | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_ENDPOINT_URL_S3`, `AWS_REGION` |
 | `ai-gateway` | `NEON_AI_GATEWAY_TOKEN`, `NEON_AI_GATEWAY_BASE_URL` |
 
-`NEON_BRANCH` is written by every pull — it is branch identity, not a service.
+`-e, --env` accepts any variable in the table plus `NEON_BRANCH`. It is case-sensitive and rejects unknown names rather than silently widening the pull. `NEON_BRANCH` is written by unscoped and service-scoped pulls because it is branch identity, not a service; an env-only pull writes it only when you select it.
+
+`--env` never narrows `--service`: `neon env pull -s postgres -e DATABASE_URL` still pulls the complete Postgres bundle (`DATABASE_URL`, `DATABASE_URL_UNPOOLED`, and `NEON_BRANCH`). The two selectors always form a union.
+
+**A scoped pull is scoped in both directions.** An unscoped `env pull` owns the Neon-named variables: pointing a directory at a branch without Neon Auth prunes the stale `NEON_AUTH_*` lines. `--service` narrows that to the services you named, while `--env` narrows it to the exact keys you named, so `env pull -e DATABASE_URL` never touches `DATABASE_URL_UNPOOLED`. (`AWS_*` is never pruned by any pull: those names collide with credentials you may set yourself, so `env pull` only ever writes them.)
 
-**A scoped pull is scoped in both directions.** An unscoped `env pull` owns the Neon-named variables: pointing a directory at a branch without Neon Auth prunes the stale `NEON_AUTH_*` lines. `--service` narrows that to the services you named, so `env pull -s ai-gateway` never touches your `DATABASE_URL`. (`AWS_*` is never pruned by any pull: those names collide with credentials you may set yourself, so `env pull` only ever writes them.)
+**A scoped pull also never revokes a credential.** Where an unscoped pull revokes the credential it replaces, a scoped one leaves the old one live — it can't tell which other variables still use it. It says so when it happens; revoke it in the Neon Console if nothing does.
 
-**A scoped pull also never revokes a credential.** Where an unscoped pull revokes the credential it replaces, a scoped one leaves the old one live — it can't tell which other services still use it. It says so when it happens; revoke it in the Neon Console if nothing does.
+`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` must be selected together. Neon issues them as one object-storage credential; pulling only one would pair a fresh half with whatever old half remains in the file.
 
 Naming a service the branch does not have is an error, not an empty pull:
 
@@ -743,6 +754,59 @@ neon snapshots schedule set --branch main --schedule '[{"frequency":"weekly","da
 
 All sub-commands honor the [global options](#global-options), including `--output json|yaml|table`.
 
+## Logs (`logs`)
+
+`neon logs` reads the log records the services on a branch emit — Neon Functions, object storage, and Postgres computes. **Logs require Neon Platform Beta and are currently available only for projects in `aws-us-east-2`.**
+
+Every sub-command resolves the project through the standard chain (`--project-id`, then the `.neon` context file, then a single-project auto-detect), and takes `--branch <id|name>`, defaulting to the project's default branch. `logs query` searches the previous hour by default; `logs field-values` searches the previous six hours. The maximum time window is seven days.
+
+```bash
+# The last 30 minutes on the default branch
+neon logs query --since 30m
+
+# Postgres compute errors on main, oldest first
+neon logs query --branch main --source pg_endpoint --minimum-severity error --sort-order asc
+
+# An explicit window (--start-time replaces --since; --end-time works with either)
+neon logs query --start-time 2025-01-01T00:00:00Z --end-time 2025-01-01T01:00:00Z
+
+# One request trace, across every service that took part in it
+neon logs query --trace-id 4bf92f3577b34da6a3ce929d0e0e4736
+
+# What the structured filters cannot express: a raw LogQL selection. It replaces
+# them, but the window, --limit, --sort-order and --cursor still apply.
+neon logs query --since 1h --logql '{entity_type="function"} |= "timeout"'
+
+# Which fields this branch supports, and the values it has actually seen
+neon logs fields
+neon logs field-values service_name --since 6h --source function
+```
+
+A response holds at most `--limit` records (1–1000; default 100). When more matched, table output prints the `--cursor` to repeat the same query with; `--output json|yaml` returns `is_truncated` and `next_cursor` on the envelope instead, so nothing but the payload lands on stdout. Table output shows the common fields; use structured output for the complete records:
+
+```console
+$ neon logs query --since 24h --output json
+{
+  "logs": [
+    {
+      "timestamp": "2025-01-01T00:00:02.000Z",
+      "message": "GET /api/todos 200",
+      "source": "function",
+      "service_name": "api",
+      "severity_text": "INFO",
+      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
+      "attributes": { "http_status": 200 }
+    }
+  ],
+  "next_cursor": "eyJvZmZzZXQiOjEwMH0",
+  "is_truncated": true
+}
+```
+
+Two combinations are rejected before the request: `--since` with `--start-time`, and `--logql` with any of `--source`, `--service-name`, `--scope-name`, `--minimum-severity`, `--severity-text`, `--body-contains` or `--trace-id`. `--minimum-severity` and `--severity-text` are independent filters and combine with AND. If Neon reports that `--minimum-severity` is unsupported, use `--severity-text` instead; `neon logs field-values severity_text` lists the exact values present on a branch.
+
+`--body-contains` compares a case-sensitive substring against the rendered message. Structured bodies, including object storage records, are rendered as compact JSON, so match the JSON form (for example, `"http_status":200`).
+
 ## Profiles
 
 The CLI holds one Neon account by default. A profile adds another, and is nothing more than a pointer to a credentials file:
@@ -971,6 +1035,7 @@ API keys in org-7
 | 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                  |
+| logs                                                                       | `query`, `fields`, `field-values`                                                                            | Query branch logs (Beta)           |
 | 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     |

package/dist/_chunks/auth_selection-DGgq6ifc.js

@@ -0,0 +1,83 @@
+import "./profiles-Ir29rqns.js";
+//#region ../../internals/cli-core/dist/auth_selection.js
+/**
+* # Which credential an invocation authenticates with
+*
+* Four inputs can each answer "who am I": the `--api-key` flag, `NEON_API_KEY`, the
+* `--profile` flag, and `NEON_PROFILE`. This module decides between them, and it is pure so
+* the decision can be tested without a filesystem, a network, or a config directory.
+*
+* ## The rule
+*
+* **An explicit flag beats an ambient environment variable.** That single rule fixes the bug
+* this module exists for: before it, any API key — including one merely exported into the
+* shell — silently voided `--profile`, so `neon --profile work …` would quietly run as
+* whoever `NEON_API_KEY` belonged to and say nothing about it.
+*
+* | Given | What runs |
+* | --- | --- |
+* | `--api-key` and `--profile` | neither: contradictory explicit flags, so this throws |
+* | `--api-key` and `NEON_PROFILE` | the flag's key |
+* | `--profile` and `NEON_API_KEY` | the profile |
+* | `NEON_API_KEY` and `NEON_PROFILE` | the key, and the ignored profile is named in a warning |
+* | `--profile` or `NEON_PROFILE` alone | that profile |
+* | nothing | `DEFAULT` |
+*
+* Two explicit flags throw rather than picking a winner. They express different intents —
+* `--api-key` supplies a credential, `--profile` selects a stored one — so there is no
+* reading of the command that makes both true, and guessing is how the original bug behaved.
+*
+* When both are merely ambient, the key wins. That keeps CI exactly as it was: a pipeline
+* that injects `NEON_API_KEY` must not change behaviour because a `NEON_PROFILE` leaked into
+* the environment. It warns instead of staying silent, because a disregarded account
+* selection is precisely what nobody noticed last time.
+*
+* `auth` and the `profile` subcommands do not use any of this. They read the same flags with
+* different meanings — `neon auth --profile work` names where to *write* a credential, and
+* `neon profile create work --api-key …` names one to *store* — so their callers skip
+* selection entirely rather than passing exemptions down here.
+*/
+let inputs = {
+	apiKeyFlag: "",
+	apiKeyEnv: "",
+	profileEnv: ""
+};
+const recordCredentialInputs = (recorded) => {
+	inputs = recorded;
+};
+const credentialInputs = () => inputs;
+const selectCredential = ({ apiKeyFlag, profileFlag, apiKeyEnv, profileEnv }) => {
+	const flagKey = nonEmpty(apiKeyFlag);
+	const flagProfile = nonEmpty(profileFlag);
+	if (flagKey !== void 0 && flagProfile !== void 0) throw new Error("Pass either --api-key or --profile, not both. --api-key supplies a credential directly; --profile selects a stored one.");
+	if (flagKey !== void 0) return {
+		source: "explicit-api-key",
+		apiKey: flagKey
+	};
+	if (flagProfile !== void 0) return {
+		source: "profile",
+		profile: flagProfile,
+		explicit: true
+	};
+	const envKey = nonEmpty(apiKeyEnv);
+	const envProfile = nonEmpty(profileEnv);
+	if (envKey !== void 0) return {
+		source: "ambient-api-key",
+		apiKey: envKey,
+		...envProfile !== void 0 ? { ignoredProfile: envProfile } : {}
+	};
+	return {
+		source: "profile",
+		profile: envProfile ?? "DEFAULT",
+		explicit: envProfile !== void 0
+	};
+};
+/** The warning for an ambient key that displaced an ambient profile, or `null`. */
+const displacedProfileWarning = (selection) => selection.source === "ambient-api-key" && selection.ignoredProfile !== void 0 ? `NEON_API_KEY is set, so profile "${selection.ignoredProfile}" from NEON_PROFILE was ignored. Pass --profile ${selection.ignoredProfile} to use it instead.` : null;
+function nonEmpty(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : trimmed;
+}
+//#endregion
+export { selectCredential as i, displacedProfileWarning as n, recordCredentialInputs as r, credentialInputs as t };