diff --git a/README.md b/README.md index 25e4c5b..c90fc07 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ It all starts with the `SKILL.md` file in the skill's directory. It's the entry [![neon](https://shieldcn.dev/skills/installs/neondatabase/agent-skills/neon.svg?variant=branded&size=xs&label=neon)](https://skills.sh/neondatabase/agent-skills/neon) -An overview of Neon for apps and agents — Lakebase Postgres, Auth, Data API, Object Storage, Compute Functions, and the AI Gateway — and how to get started. +An overview of Neon for apps and agents — Lakebase Postgres, Auth, Data API, Object Storage, Compute Functions, and the AI Gateway — and how to get started. Includes Claimable Neon for use with no Neon account. ### Neon Postgres @@ -40,12 +40,6 @@ For agent platforms, codegen tools, and multi-tenant SaaS products that provisio Choose and create the right Neon branch type for migration testing and isolated development workflows, including schema-only branches for sensitive data and reset-from-parent workflows to quickly realign child branches. -### Claimable Postgres - -[![claimable-postgres](https://shieldcn.dev/skills/installs/neondatabase/agent-skills/claimable-postgres.svg?variant=branded&size=xs&label=claimable-postgres)](https://skills.sh/neondatabase/agent-skills/claimable-postgres) - -Provision instant temporary Postgres databases via Claimable Postgres by Neon ([neon.new](https://neon.new)) with no login, signup, or credit card. Supports REST API, CLI, and SDK. - ### Neon Postgres Egress Optimizer [![neon-postgres-egress-optimizer](https://shieldcn.dev/skills/installs/neondatabase/agent-skills/neon-postgres-egress-optimizer.svg?variant=branded&size=xs&label=neon-postgres-egress-optimizer)](https://skills.sh/neondatabase/agent-skills/neon-postgres-egress-optimizer) diff --git a/plugins/neon-postgres/skills/claimable-postgres/SKILL.md b/plugins/neon-postgres/skills/claimable-postgres/SKILL.md deleted file mode 100644 index 3e16367..0000000 --- a/plugins/neon-postgres/skills/claimable-postgres/SKILL.md +++ /dev/null @@ -1,260 +0,0 @@ ---- -name: claimable-postgres -description: >- - Provision instant temporary Postgres databases via Claimable Postgres by Neon - (neon.new) with no login, signup, or credit card. Supports REST API, CLI, and - SDK. Use when users ask for a quick Postgres environment, a throwaway - DATABASE_URL for prototyping/tests, or "just give me a DB now". Triggers - include: "quick postgres", "temporary postgres", "no signup database", - "no credit card database", "instant DATABASE_URL", "npx neon-new", "neon.new", - "neon.new API", "claimable postgres API". -metadata: - parent: neon - source: https://github.com/neondatabase/agent-skills/tree/main/skills/claimable-postgres ---- - -**FIRST**: Use the parent `neon` skill for a Neon overview, getting started with Neon, Neon development best practices, and more. - -If the `neon` skill is not installed, fetch it from https://neon.com/docs/ai/skills/neon/SKILL.md or install it with: - -```bash -npx skills add neondatabase/agent-skills --skill neon -``` - -# Claimable Postgres - -Instant Postgres databases for local development, demos, prototyping, and test environments. No account required. Databases expire after 72 hours unless claimed to a Neon account. - -## Quick Start - -```bash -curl -s -X POST "https://neon.new/api/v1/database" \ - -H "Content-Type: application/json" \ - -d '{"ref": "agent-skills"}' -``` - -Parse `connection_string` and `claim_url` from the JSON response. Write `connection_string` to the project's `.env` as `DATABASE_URL`. - -For other methods (CLI, SDK, Vite plugin), see [Which Method?](#which-method) below. - -## Which Method? - -- **REST API**: Returns structured JSON. No runtime dependency beyond `curl`. Preferred when the agent needs predictable output and error handling. -- **CLI** (`npx neon-new@latest --yes`): Provisions and writes `.env` in one command. Convenient when Node.js is available and the user wants a simple setup. -- **SDK** (`neon-new/sdk`): Scripts or programmatic provisioning in Node.js. -- **Vite plugin** (`vite-plugin-neon-new`): Auto-provisions on `vite dev` if `DATABASE_URL` is missing. Use when the user has a Vite project. -- **Browser**: User cannot run CLI or API. Direct to https://neon.new. - -## Auto-provisioning - -If the agent needs a database to fulfill a task (e.g. "build me a todo app with a real database") and the user has not provided a connection string, provision one via the API and inform the user. Include the claim URL so they can keep it. - -## Agent Workflow - -### API path - -1. **Confirm intent:** If the request is ambiguous, confirm the user wants a temporary, no-signup database. Skip this if they explicitly asked for a quick or temporary database. -2. **Provision:** POST to `https://neon.new/api/v1/database` with `{"ref": "agent-skills"}`. -3. **Parse response:** Extract `connection_string`, `claim_url`, and `expires_at` from the JSON response. -4. **Write .env:** Write `DATABASE_URL=` to the project's `.env` (or the user's preferred file and key). Do not overwrite an existing key without confirmation. -5. **Seed (if needed):** If the user has a seed SQL file, run it against the new database: - ```bash - psql "$DATABASE_URL" -f seed.sql - ``` -6. **Report:** Cover every item in the [Output Checklist](#output-checklist). -7. **Optional:** Offer a quick connection test (e.g. `SELECT 1`). - -### CLI path - -1. **Check .env:** Check the target `.env` for an existing `DATABASE_URL` (or chosen key). If present, do not run. Offer remove, `--env`, or `--key` and get confirmation (see [Pre-run Check](#pre-run-check)). -2. **Confirm intent:** If the request is ambiguous, confirm the user wants a temporary, no-signup database. Skip this if they explicitly asked for a quick or temporary database. -3. **Gather options:** Use defaults unless context suggests otherwise (e.g., user mentions a custom env file, seed SQL, or logical replication). -4. **Run:** Execute with `@latest --yes` plus the confirmed options. Always use `@latest` to avoid stale cached versions. `--yes` skips interactive prompts that would stall the agent. - ```bash - npx neon-new@latest --yes --ref agent-skills --env .env.local --seed ./schema.sql - ``` -5. **Verify:** Confirm the connection string was written to the intended file. -6. **Report:** Cover every item in the [Output Checklist](#output-checklist). -7. **Optional:** Offer a quick connection test (e.g. `SELECT 1`). - -### Output Checklist - -Always report: - -- Where the connection string was written (e.g. `.env`) -- Which variable key was used (`DATABASE_URL` or custom key) -- The claim URL (from `.env` or API response) -- That unclaimed databases are temporary (72 hours): the database works now, and claiming within 72 hours keeps it permanently - -## Safety and UX Notes - -- Do not overwrite existing env vars. Check first, then use `--env` or `--key` (CLI) or skip writing (API) to avoid conflicts. -- Ask before running destructive seed SQL (`DROP`, `TRUNCATE`, mass `DELETE`). -- For production workloads, recommend standard Neon provisioning instead of temporary claimable databases. -- If users need long-term persistence, instruct them to open the claim URL right away. -- After writing credentials to an .env file, check that it's covered by .gitignore. If not, warn the user. Do not modify `.gitignore` without confirmation. - -## REST API - -**Base URL:** `https://neon.new/api/v1` - -### Create a database - -```bash -curl -s -X POST "https://neon.new/api/v1/database" \ - -H "Content-Type: application/json" \ - -d '{"ref": "agent-skills"}' -``` - -| Parameter | Required | Description | -| ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- | -| `ref` | Yes | Tracking tag that identifies who provisioned the database. Use `"agent-skills"` when provisioning through this skill. | -| `enable_logical_replication` | No | Enable logical replication (default: false, cannot be disabled once enabled) | - -The `connection_string` returned by the API is a pooled connection URL. For a direct (non-pooled) connection (e.g. Prisma migrations), remove `-pooler` from the hostname. The CLI writes both pooled and direct URLs automatically. - -**Response:** - -```json -{ - "id": "019beb39-37fb-709d-87ac-7ad6198b89f7", - "status": "UNCLAIMED", - "neon_project_id": "gentle-scene-06438508", - "connection_string": "postgresql://...", - "claim_url": "https://neon.new/claim/019beb39-...", - "expires_at": "2026-01-26T14:19:14.580Z", - "created_at": "2026-01-23T14:19:14.580Z", - "updated_at": "2026-01-23T14:19:14.580Z" -} -``` - -### Check status - -```bash -curl -s "https://neon.new/api/v1/database/{id}" -``` - -Returns the same response shape. Status transitions: `UNCLAIMED` -> `CLAIMING` -> `CLAIMED`. After the database is claimed, `connection_string` returns `null`. - -### Error responses - -| Condition | HTTP | Message | -| ---------------------- | ---- | -------------------------------- | -| Missing or empty `ref` | 400 | `Missing referrer` | -| Invalid database ID | 400 | `Database not found` | -| Invalid JSON body | 500 | `Failed to create the database.` | - -## CLI - -```bash -npx neon-new@latest --yes -``` - -Provisions a database and writes the connection string to `.env` in one step. Always use `@latest` and `--yes` (skips interactive prompts that would stall the agent). - -### Pre-run Check - -Check if `DATABASE_URL` (or the chosen key) already exists in the target `.env`. The CLI exits without provisioning if it finds the key. - -If the key exists, offer the user three options: - -1. Remove or comment out the existing line, then rerun. -2. Use `--env` to write to a different file (e.g. `--env .env.local`). -3. Use `--key` to write under a different variable name. - -Get confirmation before proceeding. - -### Options - -| Option | Alias | Description | Default | -| ----------------------- | ----- | --------------------------------------------------------------------- | -------------- | -| `--yes` | `-y` | Skip prompts, use defaults | `false` | -| `--env` | `-e` | .env file path | `./.env` | -| `--key` | `-k` | Connection string env var key | `DATABASE_URL` | -| `--prefix` | `-p` | Prefix for generated public env vars | `PUBLIC_` | -| `--seed` | `-s` | Path to seed SQL file | none | -| `--logical-replication` | `-L` | Enable logical replication | `false` | -| `--ref` | `-r` | Referrer id (use `agent-skills` when provisioning through this skill) | none | - -Alternative package managers: `yarn dlx neon-new@latest`, `pnpm dlx neon-new@latest`, `bunx neon-new@latest`, `deno run -A neon-new@latest`. - -### Output - -The CLI writes to the target `.env`: - -``` -DATABASE_URL=postgresql://... # pooled (use for application queries) -DATABASE_URL_DIRECT=postgresql://... # direct (use for migrations, e.g. Prisma) -PUBLIC_POSTGRES_CLAIM_URL=https://neon.new/claim/... -``` - -## SDK - -Use for scripts and programmatic provisioning flows. - -```typescript -import { instantPostgres } from "neon-new"; - -const { databaseUrl, databaseUrlDirect, claimUrl, claimExpiresAt } = - await instantPostgres({ - referrer: "agent-skills", - seed: { type: "sql-script", path: "./init.sql" }, - }); -``` - -Returns `databaseUrl` (pooled), `databaseUrlDirect` (direct, for migrations), `claimUrl`, and `claimExpiresAt` (Date object). The `referrer` parameter is required. - -## Vite Plugin - -For Vite projects, `vite-plugin-neon-new` auto-provisions a database on `vite dev` if `DATABASE_URL` is missing. Install with `npm install -D vite-plugin-neon-new`. See the [Claimable Postgres docs](https://neon.com/docs/reference/claimable-postgres#vite-plugin) for configuration. - -## Claiming - -Claiming is optional. The database works immediately without it. To optionally claim, the user opens the claim URL in a browser, where they sign in or create a Neon account to claim the database. - -- **API/SDK:** Give the user the `claim_url` from the create response. -- **CLI:** `npx neon-new@latest claim` reads the claim URL from `.env` and opens the browser automatically. - -Users cannot claim into Vercel-linked orgs; they must choose another Neon org. - -## Neon Infrastructure as Code (`neon.ts`) - -Claimable databases are deliberately throwaway and provisioned through `neon.new` (above), so they aren't managed by `neon.ts`. Once a user **claims** a database into a Neon account it becomes a normal Neon project — at which point `neon.ts`, Neon's infrastructure-as-code file, is how you manage it going forward (see the `neon` skill for the full reference): declare the services its branches should have, program per-branch compute, and get type-safe env vars. - -```bash -npm i @neon/config -``` - -```typescript -// neon.ts -import { defineConfig } from "@neon/config/v1"; - -export default defineConfig({ - auth: true, // Neon Auth, once you outgrow a bare connection string - dataApi: true, // Data API - branch: (branch) => (branch.exists ? {} : { ttl: "7d" }), // ephemeral non-default branches -}); -``` - -```bash -neon config apply # provision the declared services (neon deploy is an alias) -``` - -If a project needs branching, multiple services, or durable infrastructure tracked in version control, recommend claiming first and then adopting `neon.ts` — rather than re-provisioning throwaway claimable databases. - -## Defaults and Limits - -| Parameter | Value | -| --------- | --------- | -| Provider | AWS | -| Region | us-east-2 | -| Postgres | 17 | - -Region cannot be changed for claimable databases. Unclaimed databases have stricter quotas. Claiming resets limits to free plan defaults. - -| | Unclaimed | Claimed (Free plan) | -| ---------- | --------- | ------------------- | -| Storage | 100 MB | 512 MB | -| Transfer | 1 GB | ~5 GB | -| Branches | No | Yes | -| Expiration | 72 hours | None | diff --git a/plugins/neon-postgres/skills/neon/SKILL.md b/plugins/neon-postgres/skills/neon/SKILL.md index 013cb8b..afa8dc3 100644 --- a/plugins/neon-postgres/skills/neon/SKILL.md +++ b/plugins/neon-postgres/skills/neon/SKILL.md @@ -9,7 +9,12 @@ description: >- are the trigger: "object storage" or "S3", "buckets", "serverless functions", "AI gateway", "call an LLM", "logs", "branch logs", "query logs", "log export", "Loki", "Grafana", "observability", "telemetry", "postgres", - "database", or "backend". + "database", or "backend". Also use when there is no Neon account yet, the + user cannot sign in or provide an API key right now and needs a project they + can claim later, or the user asks for a throwaway DATABASE_URL, Claimable Neon, + Claimable Postgres, neon.new, claimable.neon.tech, instant Postgres, a no-signup + database, temporary postgres, quick postgres, a no credit card database, or + npx neon-new. metadata: source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon --- @@ -79,15 +84,14 @@ Neon provides a set of agent skills in addition to the official documentation. W The skills below live in the [`neondatabase/agent-skills`](https://github.com/neondatabase/agent-skills) repo: -| Skill | Use it for | -| --- | --- | -| `neon-postgres` | Working with databases, including connections, schemas, queries, and autoscaling: SQL development, schema design, performance optimization, and scaling decisions. | -| `neon-postgres-branches` | Choosing or creating the right branch type for dev, preview, test, or CI workflows. Use this skill as a slash command. | -| `neon-object-storage` | Storing and serving files (uploads, images, blobs), including branching them with the database. | -| `neon-functions` | Deploying long-running or streaming serverless functions — APIs, agents, SSE/WebSocket servers. | -| `neon-ai-gateway` | Calling an LLM or routing across model providers with one credential, including discovering the branch's servable models at runtime via the OpenAI-compatible `/v1/models` endpoint. | -| `claimable-postgres` | Provisioning instant, claimable temporary Postgres databases (for example, one per end user or demo). | -| `neon-postgres-egress-optimizer` | Diagnosing or fixing excessive Postgres egress (network data-transfer) costs in a codebase. | +| Skill | Use it for | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `neon-postgres` | Working with databases, including connections, schemas, queries, and autoscaling: SQL development, schema design, performance optimization, and scaling decisions. | +| `neon-postgres-branches` | Choosing or creating the right branch type for dev, preview, test, or CI workflows. Use this skill as a slash command. | +| `neon-object-storage` | Storing and serving files (uploads, images, blobs), including branching them with the database. | +| `neon-functions` | Deploying long-running or streaming serverless functions — APIs, agents, SSE/WebSocket servers. | +| `neon-ai-gateway` | Calling an LLM or routing across model providers with one credential, including discovering the branch's servable models at runtime via the OpenAI-compatible `/v1/models` endpoint. | +| `neon-postgres-egress-optimizer` | Diagnosing or fixing excessive Postgres egress (network data-transfer) costs in a codebase. | For guidance on agent platforms that provision and operate Lakebase Postgres on Neon at scale, use `neon-postgres-agent-platforms`, which lives in a separate repo: [`neondatabase/neon-for-agent-platforms`](https://github.com/neondatabase/neon-for-agent-platforms). @@ -121,6 +125,15 @@ Use the same method that was used to install them. With the `skills` CLI, run th ## Getting Started with Neon +Before `npx neon@latest init --agent`, check whether the CLI is already authenticated: + +- `NEON_API_KEY` is set +- `npx neon@latest profile list -o json` lists a profile whose `account` is not `-` + +A `DEFAULT` row with `account: "-"` and `file: "missing"` is not an account. If `neon` is not installed, or `npx neon@latest profile list` cannot run, that is not an account. + +If none of those hold, follow [Starting without a Neon account](#starting-without-a-neon-account). + The easiest way to get started with Neon is to use our CLI and the project bootstrap wizard: ```bash @@ -168,6 +181,16 @@ Useful MCP tools to initialize a project: - `create_project` — Creates a new Neon project in your Neon account. A project acts as a container for branches, databases, roles, and computes. - `get_connection_string` — Returns your database connection string. +## Starting without a Neon account + +If the Getting Started account check found credentials, use them. If a command waits on a browser (`Awaiting authentication in web browser`) or authentication fails, stop and ask the user to sign in (`neon auth`) or mint an API key. Prefer that over Claimable Neon unless they say otherwise. + +If they cannot sign in or provide a key right now, ask before using Claimable Neon. Continue only after they say yes. That is a temporary workaround. + +If there is no Neon account yet, follow [references/claimable-neon.md](https://neon.com/docs/ai/skills/neon/references/claimable-neon.md). Do not run `neon init --agent` or `neon auth` on this path; those need a human Neon account. If `neon claim` is missing, the reference has the REST fallback. + +Requests for neon.new, Claimable Postgres, claimable.neon.tech, instant Postgres, or a no-signup database are the same path. + ## Neon Infrastructure as Code `neon.ts` is Neon's branch config and infrastructure-as-code file: declare which Neon services your project's branches should have, get type-safe env vars, and program branch settings — all in TypeScript. It's the config layer for your Neon services, and it composes with the branch-first loop below. Add it with `@neon/config`: @@ -208,12 +231,8 @@ export default defineConfig({ auth: true, dataApi: true, preview: { - functions: { - /* ... */ - }, // see the neon-functions skill - buckets: { - /* ... */ - }, // see the neon-object-storage skill + functions: {}, + buckets: {}, aiGateway: true, // see the neon-ai-gateway skill }, }); @@ -395,7 +414,11 @@ for await (const record of neon.logs.query(projectId, branchId, { } const { data: fields } = await neon.logs.fields(projectId, branchId); -const { data: serviceNames } = await neon.logs.fieldValues(projectId, branchId, "service_name"); +const { data: serviceNames } = await neon.logs.fieldValues( + projectId, + branchId, + "service_name", +); ``` `query`'s iterator always throws on error, but `fields` and `fieldValues` follow the client's `throwOnError`, which defaults to `false` and hands back `{ data, error }`. `fieldValues` resolves to the whole response, not a bare array: read `serviceNames.values`, and treat them as an arbitrary subset whenever `serviceNames.is_truncated` is true. diff --git a/plugins/neon-postgres/skills/neon/references/claimable-neon.md b/plugins/neon-postgres/skills/neon/references/claimable-neon.md new file mode 100644 index 0000000..e67c63c --- /dev/null +++ b/plugins/neon-postgres/skills/neon/references/claimable-neon.md @@ -0,0 +1,91 @@ +# Claimable Neon + +Claimable Neon provisions a temporary Neon project — Lakebase Postgres, and optionally the Data API and Managed Better Auth — before a human creates an account. The agent holds an identity assertion, not a Neon API key. A human can later claim the project into their organization. + +This flow follows the [auth.md](https://claimable.neon.tech/auth.md) protocol. Fetch `https://claimable.neon.tech/auth.md` for request and response fields. REST is on `https://claimable.neon.tech`. Use the table below; do not invent other identity paths. + +Use this after the neon skill account check found no account. + +## Path + +1. Install the CLI: `npm i -g neon@latest` +2. If `neon claim --help` does not list `create`, skip to [If neon claim is missing](#if-neon-claim-is-missing). +3. Write a `neon.ts` that declares the services you need, or skip the file and pass `--service` on create. Postgres is always requested. +4. Create the project: `neon claim create --env-pull` (add `--service data-api --service auth` if there is no `neon.ts`) +5. If create did not write env, pull it: `neon env pull` +6. Use the `neon-postgres` skill for connections, schemas, and queries. Install it if it is missing: `neon skills -s neon-postgres` + +Do not run `neon init --agent` or `neon auth` on this path; those need a human Neon account. `--api-key` and `--profile` are refused on `neon claim`. + +```bash +npm i -g neon@latest +neon claim --help +``` + +If that help lists `create` and you need Auth or the Data API, `npm i @neon/config` and write `neon.ts`. Then `neon claim create --env-pull`. + +```typescript +import { defineConfig } from "@neon/config/v1"; + +export default defineConfig({ + auth: true, + dataApi: true, +}); +``` + +`neon claim create` reads `neon.ts` when it is present. It writes provisioned vars to an existing `.env`, otherwise `.env.local`, and gitignores that file. If `.env` or `.env.local` already has a `DATABASE_URL` (or other Neon-managed keys), pass `--file ` or `--no-env-pull`. The identity assertion is the pre-claim credential. + +Before claim, Postgres is always granted; Auth and the Data API are granted when requested. Functions, Object Storage, and AI Gateway come back with `granted: false` and `reason: "requires_claim"`. The CLI prints those as `denied_capabilities`. Report what you were given. Do not retry or strip them. + +After create, report the `project_id`, `project_expires_at`, and any denied capabilities. Do not invent the window. + +## Claim + +Do not mint a claim URL until the human is ready. Opening the URL does not freeze access. Continuing to Neon starts the transfer and rotates `DATABASE_URL`. Existing access tokens are revoked. Auth and the Data API stay enabled when they were granted. + +When `reconciled` is true, the pre-claim `DATABASE_URL` no longer works. Auth and Data API URLs stay. The human signs in with `neon auth`. Then the agent runs `neon link --agent` and `neon env pull` to write the new `DATABASE_URL`. `neon link --agent` discovers the project after that sign-in. + +### With the CLI + +When the human is ready, run `neon claim accept --no-open`. Bare `neon claim accept` opens a browser. Report the `verification_url`, `user_code`, and `expires_in_seconds` the CLI printed (HTTP names: `verification_uri_complete`, `user_code`, `expires_in`). If the code expires, run `neon claim accept --no-open` again. Poll with `neon claim status`. The CLI re-exchanges the assertion; do not call the token endpoint yourself. + +```bash +neon claim accept --no-open +neon claim status +``` + +Permanently delete the unclaimed project (this does not cancel a claim): + +```bash +neon claim delete --yes +``` + +### With REST + +An agent must not complete the claim. Do not `POST /v1/projects/{id}/claim` until the human is ready. The human opens `verification_uri_complete` and accepts the transfer. If the claim code expires, `POST /v1/projects/{id}/claim` again. The live claim response also includes `user_code` and `expires_in`. `auth.md` documents `verification_uri_complete` and the polling `interval`. + +After the human continues to Neon, existing access tokens are revoked: re-exchange the identity assertion, then poll `GET /v1/projects/{id}/claim` with that token at the interval `auth.md` returns. `claim_in_progress` means keep polling with the post-redemption token, not the token from create. Report `verification_uri_complete`, `user_code`, and `expires_in`. + +When `error.code` is `capability_requires_claim`, preserve the denied capability and give the human a claim link instead of retrying or silently omitting it. + +Only `invalid_grant`, `project_expired`, and `project_claimed` mean the stored identity assertion is dead. `token_expired` means re-exchange the assertion. + +## If neon claim is missing + +Fall back to the REST API. Fetch `https://claimable.neon.tech/auth.md` for request and response fields. The claimable resource is `/v1/projects/{id}` on `https://claimable.neon.tech`, not `/v1/databases/{id}`. Follow [Claim](#claim) for when to mint, what rotates, and what to do after `reconciled`. + +```http +POST https://claimable.neon.tech/v1/agent/identity +POST https://claimable.neon.tech/v1/oauth2/token +GET https://claimable.neon.tech/v1/projects/{id}/credentials +POST https://claimable.neon.tech/v1/projects/{id}/claim +GET https://claimable.neon.tech/v1/projects/{id}/claim +DELETE https://claimable.neon.tech/v1/projects/{id} +``` + +| CLI | REST | +| ----------------------------- | ------------------------------------------------------------------------------------------------- | +| `neon claim create` | `POST /v1/agent/identity`, then `POST /v1/oauth2/token`, then `GET /v1/projects/{id}/credentials` | +| `neon claim accept --no-open` | `POST /v1/projects/{id}/claim` | +| `neon claim status` | `GET /v1/projects/{id}/claim` | +| `neon claim delete --yes` | `DELETE /v1/projects/{id}` | diff --git a/skills.sh.json b/skills.sh.json index 9a80fa8..fab97ee 100644 --- a/skills.sh.json +++ b/skills.sh.json @@ -5,28 +5,17 @@ { "title": "Core", "description": "Start here: the core skill for all things Neon, plus Neon's Lakebase Postgres offering.", - "skills": [ - "neon", - "neon-postgres" - ] + "skills": ["neon", "neon-postgres"] }, { "title": "Database Workflows", - "description": "Provision, branch, and optimize Lakebase Postgres projects on Neon.", - "skills": [ - "claimable-postgres", - "neon-postgres-branches", - "neon-postgres-egress-optimizer" - ] + "description": "Branch and optimize Lakebase Postgres projects on Neon.", + "skills": ["neon-postgres-branches", "neon-postgres-egress-optimizer"] }, { "title": "Neon Services", "description": "Use Neon services beyond Lakebase Postgres.", - "skills": [ - "neon-ai-gateway", - "neon-functions", - "neon-object-storage" - ] + "skills": ["neon-ai-gateway", "neon-functions", "neon-object-storage"] } ] } diff --git a/skills/claimable-postgres/SKILL.md b/skills/claimable-postgres/SKILL.md deleted file mode 100644 index 3e16367..0000000 --- a/skills/claimable-postgres/SKILL.md +++ /dev/null @@ -1,260 +0,0 @@ ---- -name: claimable-postgres -description: >- - Provision instant temporary Postgres databases via Claimable Postgres by Neon - (neon.new) with no login, signup, or credit card. Supports REST API, CLI, and - SDK. Use when users ask for a quick Postgres environment, a throwaway - DATABASE_URL for prototyping/tests, or "just give me a DB now". Triggers - include: "quick postgres", "temporary postgres", "no signup database", - "no credit card database", "instant DATABASE_URL", "npx neon-new", "neon.new", - "neon.new API", "claimable postgres API". -metadata: - parent: neon - source: https://github.com/neondatabase/agent-skills/tree/main/skills/claimable-postgres ---- - -**FIRST**: Use the parent `neon` skill for a Neon overview, getting started with Neon, Neon development best practices, and more. - -If the `neon` skill is not installed, fetch it from https://neon.com/docs/ai/skills/neon/SKILL.md or install it with: - -```bash -npx skills add neondatabase/agent-skills --skill neon -``` - -# Claimable Postgres - -Instant Postgres databases for local development, demos, prototyping, and test environments. No account required. Databases expire after 72 hours unless claimed to a Neon account. - -## Quick Start - -```bash -curl -s -X POST "https://neon.new/api/v1/database" \ - -H "Content-Type: application/json" \ - -d '{"ref": "agent-skills"}' -``` - -Parse `connection_string` and `claim_url` from the JSON response. Write `connection_string` to the project's `.env` as `DATABASE_URL`. - -For other methods (CLI, SDK, Vite plugin), see [Which Method?](#which-method) below. - -## Which Method? - -- **REST API**: Returns structured JSON. No runtime dependency beyond `curl`. Preferred when the agent needs predictable output and error handling. -- **CLI** (`npx neon-new@latest --yes`): Provisions and writes `.env` in one command. Convenient when Node.js is available and the user wants a simple setup. -- **SDK** (`neon-new/sdk`): Scripts or programmatic provisioning in Node.js. -- **Vite plugin** (`vite-plugin-neon-new`): Auto-provisions on `vite dev` if `DATABASE_URL` is missing. Use when the user has a Vite project. -- **Browser**: User cannot run CLI or API. Direct to https://neon.new. - -## Auto-provisioning - -If the agent needs a database to fulfill a task (e.g. "build me a todo app with a real database") and the user has not provided a connection string, provision one via the API and inform the user. Include the claim URL so they can keep it. - -## Agent Workflow - -### API path - -1. **Confirm intent:** If the request is ambiguous, confirm the user wants a temporary, no-signup database. Skip this if they explicitly asked for a quick or temporary database. -2. **Provision:** POST to `https://neon.new/api/v1/database` with `{"ref": "agent-skills"}`. -3. **Parse response:** Extract `connection_string`, `claim_url`, and `expires_at` from the JSON response. -4. **Write .env:** Write `DATABASE_URL=` to the project's `.env` (or the user's preferred file and key). Do not overwrite an existing key without confirmation. -5. **Seed (if needed):** If the user has a seed SQL file, run it against the new database: - ```bash - psql "$DATABASE_URL" -f seed.sql - ``` -6. **Report:** Cover every item in the [Output Checklist](#output-checklist). -7. **Optional:** Offer a quick connection test (e.g. `SELECT 1`). - -### CLI path - -1. **Check .env:** Check the target `.env` for an existing `DATABASE_URL` (or chosen key). If present, do not run. Offer remove, `--env`, or `--key` and get confirmation (see [Pre-run Check](#pre-run-check)). -2. **Confirm intent:** If the request is ambiguous, confirm the user wants a temporary, no-signup database. Skip this if they explicitly asked for a quick or temporary database. -3. **Gather options:** Use defaults unless context suggests otherwise (e.g., user mentions a custom env file, seed SQL, or logical replication). -4. **Run:** Execute with `@latest --yes` plus the confirmed options. Always use `@latest` to avoid stale cached versions. `--yes` skips interactive prompts that would stall the agent. - ```bash - npx neon-new@latest --yes --ref agent-skills --env .env.local --seed ./schema.sql - ``` -5. **Verify:** Confirm the connection string was written to the intended file. -6. **Report:** Cover every item in the [Output Checklist](#output-checklist). -7. **Optional:** Offer a quick connection test (e.g. `SELECT 1`). - -### Output Checklist - -Always report: - -- Where the connection string was written (e.g. `.env`) -- Which variable key was used (`DATABASE_URL` or custom key) -- The claim URL (from `.env` or API response) -- That unclaimed databases are temporary (72 hours): the database works now, and claiming within 72 hours keeps it permanently - -## Safety and UX Notes - -- Do not overwrite existing env vars. Check first, then use `--env` or `--key` (CLI) or skip writing (API) to avoid conflicts. -- Ask before running destructive seed SQL (`DROP`, `TRUNCATE`, mass `DELETE`). -- For production workloads, recommend standard Neon provisioning instead of temporary claimable databases. -- If users need long-term persistence, instruct them to open the claim URL right away. -- After writing credentials to an .env file, check that it's covered by .gitignore. If not, warn the user. Do not modify `.gitignore` without confirmation. - -## REST API - -**Base URL:** `https://neon.new/api/v1` - -### Create a database - -```bash -curl -s -X POST "https://neon.new/api/v1/database" \ - -H "Content-Type: application/json" \ - -d '{"ref": "agent-skills"}' -``` - -| Parameter | Required | Description | -| ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- | -| `ref` | Yes | Tracking tag that identifies who provisioned the database. Use `"agent-skills"` when provisioning through this skill. | -| `enable_logical_replication` | No | Enable logical replication (default: false, cannot be disabled once enabled) | - -The `connection_string` returned by the API is a pooled connection URL. For a direct (non-pooled) connection (e.g. Prisma migrations), remove `-pooler` from the hostname. The CLI writes both pooled and direct URLs automatically. - -**Response:** - -```json -{ - "id": "019beb39-37fb-709d-87ac-7ad6198b89f7", - "status": "UNCLAIMED", - "neon_project_id": "gentle-scene-06438508", - "connection_string": "postgresql://...", - "claim_url": "https://neon.new/claim/019beb39-...", - "expires_at": "2026-01-26T14:19:14.580Z", - "created_at": "2026-01-23T14:19:14.580Z", - "updated_at": "2026-01-23T14:19:14.580Z" -} -``` - -### Check status - -```bash -curl -s "https://neon.new/api/v1/database/{id}" -``` - -Returns the same response shape. Status transitions: `UNCLAIMED` -> `CLAIMING` -> `CLAIMED`. After the database is claimed, `connection_string` returns `null`. - -### Error responses - -| Condition | HTTP | Message | -| ---------------------- | ---- | -------------------------------- | -| Missing or empty `ref` | 400 | `Missing referrer` | -| Invalid database ID | 400 | `Database not found` | -| Invalid JSON body | 500 | `Failed to create the database.` | - -## CLI - -```bash -npx neon-new@latest --yes -``` - -Provisions a database and writes the connection string to `.env` in one step. Always use `@latest` and `--yes` (skips interactive prompts that would stall the agent). - -### Pre-run Check - -Check if `DATABASE_URL` (or the chosen key) already exists in the target `.env`. The CLI exits without provisioning if it finds the key. - -If the key exists, offer the user three options: - -1. Remove or comment out the existing line, then rerun. -2. Use `--env` to write to a different file (e.g. `--env .env.local`). -3. Use `--key` to write under a different variable name. - -Get confirmation before proceeding. - -### Options - -| Option | Alias | Description | Default | -| ----------------------- | ----- | --------------------------------------------------------------------- | -------------- | -| `--yes` | `-y` | Skip prompts, use defaults | `false` | -| `--env` | `-e` | .env file path | `./.env` | -| `--key` | `-k` | Connection string env var key | `DATABASE_URL` | -| `--prefix` | `-p` | Prefix for generated public env vars | `PUBLIC_` | -| `--seed` | `-s` | Path to seed SQL file | none | -| `--logical-replication` | `-L` | Enable logical replication | `false` | -| `--ref` | `-r` | Referrer id (use `agent-skills` when provisioning through this skill) | none | - -Alternative package managers: `yarn dlx neon-new@latest`, `pnpm dlx neon-new@latest`, `bunx neon-new@latest`, `deno run -A neon-new@latest`. - -### Output - -The CLI writes to the target `.env`: - -``` -DATABASE_URL=postgresql://... # pooled (use for application queries) -DATABASE_URL_DIRECT=postgresql://... # direct (use for migrations, e.g. Prisma) -PUBLIC_POSTGRES_CLAIM_URL=https://neon.new/claim/... -``` - -## SDK - -Use for scripts and programmatic provisioning flows. - -```typescript -import { instantPostgres } from "neon-new"; - -const { databaseUrl, databaseUrlDirect, claimUrl, claimExpiresAt } = - await instantPostgres({ - referrer: "agent-skills", - seed: { type: "sql-script", path: "./init.sql" }, - }); -``` - -Returns `databaseUrl` (pooled), `databaseUrlDirect` (direct, for migrations), `claimUrl`, and `claimExpiresAt` (Date object). The `referrer` parameter is required. - -## Vite Plugin - -For Vite projects, `vite-plugin-neon-new` auto-provisions a database on `vite dev` if `DATABASE_URL` is missing. Install with `npm install -D vite-plugin-neon-new`. See the [Claimable Postgres docs](https://neon.com/docs/reference/claimable-postgres#vite-plugin) for configuration. - -## Claiming - -Claiming is optional. The database works immediately without it. To optionally claim, the user opens the claim URL in a browser, where they sign in or create a Neon account to claim the database. - -- **API/SDK:** Give the user the `claim_url` from the create response. -- **CLI:** `npx neon-new@latest claim` reads the claim URL from `.env` and opens the browser automatically. - -Users cannot claim into Vercel-linked orgs; they must choose another Neon org. - -## Neon Infrastructure as Code (`neon.ts`) - -Claimable databases are deliberately throwaway and provisioned through `neon.new` (above), so they aren't managed by `neon.ts`. Once a user **claims** a database into a Neon account it becomes a normal Neon project — at which point `neon.ts`, Neon's infrastructure-as-code file, is how you manage it going forward (see the `neon` skill for the full reference): declare the services its branches should have, program per-branch compute, and get type-safe env vars. - -```bash -npm i @neon/config -``` - -```typescript -// neon.ts -import { defineConfig } from "@neon/config/v1"; - -export default defineConfig({ - auth: true, // Neon Auth, once you outgrow a bare connection string - dataApi: true, // Data API - branch: (branch) => (branch.exists ? {} : { ttl: "7d" }), // ephemeral non-default branches -}); -``` - -```bash -neon config apply # provision the declared services (neon deploy is an alias) -``` - -If a project needs branching, multiple services, or durable infrastructure tracked in version control, recommend claiming first and then adopting `neon.ts` — rather than re-provisioning throwaway claimable databases. - -## Defaults and Limits - -| Parameter | Value | -| --------- | --------- | -| Provider | AWS | -| Region | us-east-2 | -| Postgres | 17 | - -Region cannot be changed for claimable databases. Unclaimed databases have stricter quotas. Claiming resets limits to free plan defaults. - -| | Unclaimed | Claimed (Free plan) | -| ---------- | --------- | ------------------- | -| Storage | 100 MB | 512 MB | -| Transfer | 1 GB | ~5 GB | -| Branches | No | Yes | -| Expiration | 72 hours | None | diff --git a/skills/neon/SKILL.md b/skills/neon/SKILL.md index 013cb8b..afa8dc3 100644 --- a/skills/neon/SKILL.md +++ b/skills/neon/SKILL.md @@ -9,7 +9,12 @@ description: >- are the trigger: "object storage" or "S3", "buckets", "serverless functions", "AI gateway", "call an LLM", "logs", "branch logs", "query logs", "log export", "Loki", "Grafana", "observability", "telemetry", "postgres", - "database", or "backend". + "database", or "backend". Also use when there is no Neon account yet, the + user cannot sign in or provide an API key right now and needs a project they + can claim later, or the user asks for a throwaway DATABASE_URL, Claimable Neon, + Claimable Postgres, neon.new, claimable.neon.tech, instant Postgres, a no-signup + database, temporary postgres, quick postgres, a no credit card database, or + npx neon-new. metadata: source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon --- @@ -79,15 +84,14 @@ Neon provides a set of agent skills in addition to the official documentation. W The skills below live in the [`neondatabase/agent-skills`](https://github.com/neondatabase/agent-skills) repo: -| Skill | Use it for | -| --- | --- | -| `neon-postgres` | Working with databases, including connections, schemas, queries, and autoscaling: SQL development, schema design, performance optimization, and scaling decisions. | -| `neon-postgres-branches` | Choosing or creating the right branch type for dev, preview, test, or CI workflows. Use this skill as a slash command. | -| `neon-object-storage` | Storing and serving files (uploads, images, blobs), including branching them with the database. | -| `neon-functions` | Deploying long-running or streaming serverless functions — APIs, agents, SSE/WebSocket servers. | -| `neon-ai-gateway` | Calling an LLM or routing across model providers with one credential, including discovering the branch's servable models at runtime via the OpenAI-compatible `/v1/models` endpoint. | -| `claimable-postgres` | Provisioning instant, claimable temporary Postgres databases (for example, one per end user or demo). | -| `neon-postgres-egress-optimizer` | Diagnosing or fixing excessive Postgres egress (network data-transfer) costs in a codebase. | +| Skill | Use it for | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `neon-postgres` | Working with databases, including connections, schemas, queries, and autoscaling: SQL development, schema design, performance optimization, and scaling decisions. | +| `neon-postgres-branches` | Choosing or creating the right branch type for dev, preview, test, or CI workflows. Use this skill as a slash command. | +| `neon-object-storage` | Storing and serving files (uploads, images, blobs), including branching them with the database. | +| `neon-functions` | Deploying long-running or streaming serverless functions — APIs, agents, SSE/WebSocket servers. | +| `neon-ai-gateway` | Calling an LLM or routing across model providers with one credential, including discovering the branch's servable models at runtime via the OpenAI-compatible `/v1/models` endpoint. | +| `neon-postgres-egress-optimizer` | Diagnosing or fixing excessive Postgres egress (network data-transfer) costs in a codebase. | For guidance on agent platforms that provision and operate Lakebase Postgres on Neon at scale, use `neon-postgres-agent-platforms`, which lives in a separate repo: [`neondatabase/neon-for-agent-platforms`](https://github.com/neondatabase/neon-for-agent-platforms). @@ -121,6 +125,15 @@ Use the same method that was used to install them. With the `skills` CLI, run th ## Getting Started with Neon +Before `npx neon@latest init --agent`, check whether the CLI is already authenticated: + +- `NEON_API_KEY` is set +- `npx neon@latest profile list -o json` lists a profile whose `account` is not `-` + +A `DEFAULT` row with `account: "-"` and `file: "missing"` is not an account. If `neon` is not installed, or `npx neon@latest profile list` cannot run, that is not an account. + +If none of those hold, follow [Starting without a Neon account](#starting-without-a-neon-account). + The easiest way to get started with Neon is to use our CLI and the project bootstrap wizard: ```bash @@ -168,6 +181,16 @@ Useful MCP tools to initialize a project: - `create_project` — Creates a new Neon project in your Neon account. A project acts as a container for branches, databases, roles, and computes. - `get_connection_string` — Returns your database connection string. +## Starting without a Neon account + +If the Getting Started account check found credentials, use them. If a command waits on a browser (`Awaiting authentication in web browser`) or authentication fails, stop and ask the user to sign in (`neon auth`) or mint an API key. Prefer that over Claimable Neon unless they say otherwise. + +If they cannot sign in or provide a key right now, ask before using Claimable Neon. Continue only after they say yes. That is a temporary workaround. + +If there is no Neon account yet, follow [references/claimable-neon.md](https://neon.com/docs/ai/skills/neon/references/claimable-neon.md). Do not run `neon init --agent` or `neon auth` on this path; those need a human Neon account. If `neon claim` is missing, the reference has the REST fallback. + +Requests for neon.new, Claimable Postgres, claimable.neon.tech, instant Postgres, or a no-signup database are the same path. + ## Neon Infrastructure as Code `neon.ts` is Neon's branch config and infrastructure-as-code file: declare which Neon services your project's branches should have, get type-safe env vars, and program branch settings — all in TypeScript. It's the config layer for your Neon services, and it composes with the branch-first loop below. Add it with `@neon/config`: @@ -208,12 +231,8 @@ export default defineConfig({ auth: true, dataApi: true, preview: { - functions: { - /* ... */ - }, // see the neon-functions skill - buckets: { - /* ... */ - }, // see the neon-object-storage skill + functions: {}, + buckets: {}, aiGateway: true, // see the neon-ai-gateway skill }, }); @@ -395,7 +414,11 @@ for await (const record of neon.logs.query(projectId, branchId, { } const { data: fields } = await neon.logs.fields(projectId, branchId); -const { data: serviceNames } = await neon.logs.fieldValues(projectId, branchId, "service_name"); +const { data: serviceNames } = await neon.logs.fieldValues( + projectId, + branchId, + "service_name", +); ``` `query`'s iterator always throws on error, but `fields` and `fieldValues` follow the client's `throwOnError`, which defaults to `false` and hands back `{ data, error }`. `fieldValues` resolves to the whole response, not a bare array: read `serviceNames.values`, and treat them as an arbitrary subset whenever `serviceNames.is_truncated` is true. diff --git a/skills/neon/references/claimable-neon.md b/skills/neon/references/claimable-neon.md new file mode 100644 index 0000000..e67c63c --- /dev/null +++ b/skills/neon/references/claimable-neon.md @@ -0,0 +1,91 @@ +# Claimable Neon + +Claimable Neon provisions a temporary Neon project — Lakebase Postgres, and optionally the Data API and Managed Better Auth — before a human creates an account. The agent holds an identity assertion, not a Neon API key. A human can later claim the project into their organization. + +This flow follows the [auth.md](https://claimable.neon.tech/auth.md) protocol. Fetch `https://claimable.neon.tech/auth.md` for request and response fields. REST is on `https://claimable.neon.tech`. Use the table below; do not invent other identity paths. + +Use this after the neon skill account check found no account. + +## Path + +1. Install the CLI: `npm i -g neon@latest` +2. If `neon claim --help` does not list `create`, skip to [If neon claim is missing](#if-neon-claim-is-missing). +3. Write a `neon.ts` that declares the services you need, or skip the file and pass `--service` on create. Postgres is always requested. +4. Create the project: `neon claim create --env-pull` (add `--service data-api --service auth` if there is no `neon.ts`) +5. If create did not write env, pull it: `neon env pull` +6. Use the `neon-postgres` skill for connections, schemas, and queries. Install it if it is missing: `neon skills -s neon-postgres` + +Do not run `neon init --agent` or `neon auth` on this path; those need a human Neon account. `--api-key` and `--profile` are refused on `neon claim`. + +```bash +npm i -g neon@latest +neon claim --help +``` + +If that help lists `create` and you need Auth or the Data API, `npm i @neon/config` and write `neon.ts`. Then `neon claim create --env-pull`. + +```typescript +import { defineConfig } from "@neon/config/v1"; + +export default defineConfig({ + auth: true, + dataApi: true, +}); +``` + +`neon claim create` reads `neon.ts` when it is present. It writes provisioned vars to an existing `.env`, otherwise `.env.local`, and gitignores that file. If `.env` or `.env.local` already has a `DATABASE_URL` (or other Neon-managed keys), pass `--file ` or `--no-env-pull`. The identity assertion is the pre-claim credential. + +Before claim, Postgres is always granted; Auth and the Data API are granted when requested. Functions, Object Storage, and AI Gateway come back with `granted: false` and `reason: "requires_claim"`. The CLI prints those as `denied_capabilities`. Report what you were given. Do not retry or strip them. + +After create, report the `project_id`, `project_expires_at`, and any denied capabilities. Do not invent the window. + +## Claim + +Do not mint a claim URL until the human is ready. Opening the URL does not freeze access. Continuing to Neon starts the transfer and rotates `DATABASE_URL`. Existing access tokens are revoked. Auth and the Data API stay enabled when they were granted. + +When `reconciled` is true, the pre-claim `DATABASE_URL` no longer works. Auth and Data API URLs stay. The human signs in with `neon auth`. Then the agent runs `neon link --agent` and `neon env pull` to write the new `DATABASE_URL`. `neon link --agent` discovers the project after that sign-in. + +### With the CLI + +When the human is ready, run `neon claim accept --no-open`. Bare `neon claim accept` opens a browser. Report the `verification_url`, `user_code`, and `expires_in_seconds` the CLI printed (HTTP names: `verification_uri_complete`, `user_code`, `expires_in`). If the code expires, run `neon claim accept --no-open` again. Poll with `neon claim status`. The CLI re-exchanges the assertion; do not call the token endpoint yourself. + +```bash +neon claim accept --no-open +neon claim status +``` + +Permanently delete the unclaimed project (this does not cancel a claim): + +```bash +neon claim delete --yes +``` + +### With REST + +An agent must not complete the claim. Do not `POST /v1/projects/{id}/claim` until the human is ready. The human opens `verification_uri_complete` and accepts the transfer. If the claim code expires, `POST /v1/projects/{id}/claim` again. The live claim response also includes `user_code` and `expires_in`. `auth.md` documents `verification_uri_complete` and the polling `interval`. + +After the human continues to Neon, existing access tokens are revoked: re-exchange the identity assertion, then poll `GET /v1/projects/{id}/claim` with that token at the interval `auth.md` returns. `claim_in_progress` means keep polling with the post-redemption token, not the token from create. Report `verification_uri_complete`, `user_code`, and `expires_in`. + +When `error.code` is `capability_requires_claim`, preserve the denied capability and give the human a claim link instead of retrying or silently omitting it. + +Only `invalid_grant`, `project_expired`, and `project_claimed` mean the stored identity assertion is dead. `token_expired` means re-exchange the assertion. + +## If neon claim is missing + +Fall back to the REST API. Fetch `https://claimable.neon.tech/auth.md` for request and response fields. The claimable resource is `/v1/projects/{id}` on `https://claimable.neon.tech`, not `/v1/databases/{id}`. Follow [Claim](#claim) for when to mint, what rotates, and what to do after `reconciled`. + +```http +POST https://claimable.neon.tech/v1/agent/identity +POST https://claimable.neon.tech/v1/oauth2/token +GET https://claimable.neon.tech/v1/projects/{id}/credentials +POST https://claimable.neon.tech/v1/projects/{id}/claim +GET https://claimable.neon.tech/v1/projects/{id}/claim +DELETE https://claimable.neon.tech/v1/projects/{id} +``` + +| CLI | REST | +| ----------------------------- | ------------------------------------------------------------------------------------------------- | +| `neon claim create` | `POST /v1/agent/identity`, then `POST /v1/oauth2/token`, then `GET /v1/projects/{id}/credentials` | +| `neon claim accept --no-open` | `POST /v1/projects/{id}/claim` | +| `neon claim status` | `GET /v1/projects/{id}/claim` | +| `neon claim delete --yes` | `DELETE /v1/projects/{id}` |