Neon CLI

Neon CLI 已迁移。 开发工作现已转移至 neondatabase/neon-pkgs monorepo 中的 packages/cli。请在那里提交新的 issue 和 pull request。

Neon CLI 是一个命令行界面，可让你直接在终端中管理 Neon Serverless Postgres。完整文档请参阅 Neon CLI。

安装 Neon CLI

npm

npm i -g neonctl

需要 Node.js 18.0 或更高版本。

Howebrew

brew install neonctl

二进制文件（macOS、Linux、Windows）

在此处下载二进制文件。

升级

npm

npm update -g neonctl

需要 Node.js 18.0 或更高版本。

Howebrew

brew upgrade neonctl

二进制文件（macOS、Linux、Windows）

要升级二进制文件版本，请按上述说明下载最新的二进制文件，并用新文件替换旧文件。

连接

运行以下命令以通过身份验证连接到 Neon：

neonctl auth

auth 命令会打开浏览器窗口，你可以在其中授权 Neon CLI 访问你的 Neon 账户。如果运行 Neon CLI 命令时未通过 neonctl auth 进行身份验证，系统会自动启动浏览器身份验证流程。

或者，运行 Neon CLI 命令时，可以使用 --api-key 选项通过 Neon API 密钥进行身份验证。例如，以下 neonctl projects list 命令使用了 API 密钥：

neonctl projects list --api-key <neon_api_key>

有关如何获取 Neon API 密钥的信息，请参阅 _Neon API 参考_中的身份验证。

使用 psql 连接

psql 命令

neonctl psql [branch] 会打开一个连接到某个分支的 psql 会话。它会构建该分支的连接字符串并启动 psql，是 neonctl connection-string --psql 的快捷方式。完整参考请参阅 Neon CLI 命令 — psql。

neonctl psql                                    # default branch
neonctl psql main                               # a specific branch
neonctl psql main@2024-01-01T00:00:00Z          # point-in-time (branch@timestamp or branch@lsn)
neonctl psql --pooled                           # use the pooled connection

-- 后的参数会传递给 psql：

neonctl psql main -- -c "SELECT version()"
neonctl psql main -- -f script.sql --csv

选项：--project-id、--role-name、--database-name、--pooled、--endpoint-type（read_only | read_write）、--ssl，以及全局选项。

--psql 标志

其他几个命令也接受 --psql 标志，可打开一个连接到已解析端点的 psql 会话：

neonctl connection-string --psql --project-id <id>
neonctl projects create --psql
neonctl branches create --psql

-- 后的所有参数都会传递给 psql，例如：

neonctl cs --psql --project-id <id> -- -c "SELECT version()"
neonctl cs --psql --project-id <id> -- -f script.sql --csv

内嵌 psql 回退方案

如果系统的 $PATH 中安装了 psql，--psql 仍会启动原生二进制文件；现有用户的使用行为不会改变。

如果在 $PATH 中找不到 psql，neonctl 现在会回退到内嵌的 TypeScript 实现。无需安装或配置任何内容；该实现已随 neonctl 一同提供。这解决了机器（以及 CI 运行器）未安装 PostgreSQL 客户端工具时遇到的“找不到 psql 二进制文件”问题。

自动回退是预期的使用方式——通常无需设置任何标志。也可以强制选择内嵌实现（主要用于测试和 CI，例如，即使存在原生 psql，也要运行测试验证该实现）：

• --fallback — 在 connection-string、projects create 和 branches create 上强制使用内嵌实现。此选项会有意从 --help 中隐藏：它是用于测试/CI 的参数，并非面向用户的选项（上文所述的自动回退才是受支持的行为）。
• NEONCTL_PSQL_FALLBACK=1 — 效果与 --fallback 相同的环境变量。适用于脚本和 CI。

内嵌实现已通过一致性测试套件验证。该套件会将其行为与真实 PostgreSQL（14–18）以及上游 psql 回归测试和 TAP 测试进行比较。

可用功能

REPL 和脚本

• 交互式 REPL，配备手工实现的 VT100 行编辑器（无原生绑定）；vi 和 emacs 编辑模式（VI_MODE psql 变量）
• 持久化命令历史记录（~/.psql_history，libreadline 格式）
• 自动加载 ~/.psqlrc（包括 $PGSYSCONFDIR/psqlrc 和带版本后缀的变体）
• 脚本模式：-c "SQL"、-f script.sql 和标准输入；--single-transaction、ON_ERROR_STOP、ECHO、--echo-all
• SINGLELINE（-S）、\timing、\watch（命名标志 c=/i=/m=，不设上限的连续模式）

反斜杠命令

• 所有输出格式：aligned、unaligned、wrapped、csv、json、html、asciidoc、latex、latex-longtable、troff-ms（\a \H \t \x \pset \f \C …）
• 所有 \d* 描述命令，与上游完整一致（列、索引、外键、触发器、视图定义、序列、RLS、副本标识、分区、表空间、访问方法、继承、FDW、统计对象、发布、订阅、每列 FDW 选项、TOAST 所有者）
• \copy 支持从文件、PROGRAM、STDIN、STDOUT 复制或导出（包括 \. EOF 标记）；\g / \gx / \gset / \gdesc / \gexec 和 \g | program 管道
• 扩展查询和管道模式（\bind、\bind_named、\startpipeline、\parse、\sendpipeline）
• \crosstabview、\lo_* 大型对象、\e/\edit（外部编辑器）、\s（历史记录）、\?/\h 帮助、\if/\elif/\else/\endif、\set/\unset、\connect、\encoding（实时执行 SET client_encoding）、\!、\cd、\prompt（包括不回显的 -）、\password
• Tab 补全（约 88 条规则，包括实时查询 pg_settings GUC、深入补全 ALTER 子操作、JOIN 子句、窗口 OVER）

连接和身份验证

• 与 libpq 等效的查找优先级：argv 标志 > URI > PG* 环境变量 > ~/.pgpass > pg_service.conf > libpq 默认值
• SCRAM-SHA-256 / SCRAM-SHA-256-PLUS，支持 tls-server-end-point 通道绑定（channel_binding）；MD5 和明文；require_auth
• 多主机故障转移和负载均衡：target_session_attrs（any / read-write / read-only / primary / standby / prefer-standby）、load_balance_hosts、DNS 扇出、hostaddr
• Unix 域套接字（以 / 开头的主机）；TCP 保活（keepalives、keepalives_idle）

TLS

• sslmode 支持从 disable 到 verify-full；通过 sslcert / sslkey 使用 PEM 或 DER 格式的客户端证书（加密密钥使用 sslpassword，并进行 libpq 的组/全局可读密钥检查）
• 信任配置：sslrootcert（包括通过 SSL_CERT_FILE / SSL_CERT_DIR 使用 =system）、默认客户端证书发现（~/.postgresql/postgresql.{crt,key}）、sslcertmode
• CRL：sslcrl 和 sslcrldir；ssl_min_protocol_version / ssl_max_protocol_version；sslsni
• 直接 SSL 协商（sslnegotiation=direct，PostgreSQL 17+，通过 ALPN）

不支持的功能

• GSSAPI / SSPI（gssencmode、Kerberos/SSPI 身份验证、requirepeer）。GSS 传输加密需要原生 Kerberos 绑定，而内嵌的 psql 刻意避免了这类绑定（纯 TypeScript、零原生依赖——行编辑器采用手工实现也是出于同样的原因）。node-postgres 也不支持，Neon 也不会使用它。接受 gssencmode=disable / prefer；若设置 gssencmode=require，则会明确报错拒绝。requirepeer 会被解析，但设置该选项的 Unix 套接字连接会被拒绝（Node 不提供对端凭据 API——不会静默忽略该选项）。
• keepalives_interval / keepalives_count — Node 的套接字 API 只提供启用保活和设置初始延迟的功能，因此会接受这些参数，但不会应用。

已知限制

• TLS 密码套件取决于运行时。 协商出的 TLS 1.3 密码套件由主机运行时的 TLS 库从与 libpq 字节完全相同的候选列表中选出。在 Node（OpenSSL）下为 TLS_AES_256_GCM_SHA384，与标准 psql 一致；在 Bun（BoringSSL）下为 TLS_AES_128_GCM_SHA256。两者都是 TLS 1.3 AEAD 密码套件，实际安全性没有差异，而且这两个运行时都未提供客户端设置来控制选择结果。

配置自动补全

Neon CLI 支持自动补全，只需几个简单步骤即可配置。请参阅 Neon CLI 命令 — completion 获取说明。

链接项目

neonctl link 是一个 Vercel 风格的命令，可将当前目录关联到 Neon 项目。它会选择（或创建）一个组织和项目，并写入 .neon 文件（{ "orgId", "projectId", "branch" }）。之后，在此目录（或任意子目录）中运行的命令会自动读取该文件。

link 会解析所有可解析的信息，并在写入前验证你传入的每个标识符，因此不会留下只写入一部分内容或指向不存在对象的 .neon 文件：

• org 会根据项目推断（因此只需传入 --project-id）；仅当项目没有组织（个人账户）时才会省略。
• project 取自 --project-id（或通过交互方式／--agent 选择）。
• branch 需要通过显式的 neonctl checkout <branch> 指定——link 不会悄悄固定项目的默认分支（否则后续命令可能会在不知情的情况下指向生产环境）。只有在传入 --branch、同一项目已有固定分支（保留该设置）、在交互式选择器中选择分支，或创建全新项目（其唯一分支没有歧义）时，它才会记录分支。

固定分支后，link 还会运行 env pull，将该分支的 Neon 环境变量（DATABASE_URL，……）写入本地 .env。如果没有固定分支，就没有可拉取的内容，因此 link 会提示你运行 neonctl checkout。传入 --no-env-pull 可跳过拉取（例如，通过 neon-env run 或 neonctl dev 在运行时注入环境变量）。

从 set-context 迁移？ 推荐使用 link，set-context 已弃用（见下文）。目前它仍会像以前一样正常工作（直接写入），只是会打印弃用警告。.neon 中的 branchId 字段也已由 branch 取代（已知时存储分支名称）；旧的 branchId 文件仍会被读取，并在下次 link／checkout 写入上下文时升级为 branch。

共有三种模式：

交互式（默认） — 为用户提供引导式提示：

$ neonctl link
? Which organization would you like to link? › Personal Org (org-abc123)
? Which project would you like to link? › ＋ Create new project…
? Name for the new project: › my-app
? Which region should the new project run in? › AWS US East (Ohio) (aws-us-east-2)
Created project polished-snowflake-12345678 ("my-app") in aws-us-east-2.
Linked .neon:
  orgId:     org-abc123
  projectId: polished-snowflake-12345678
  branch:    main

链接包含多个分支的现有项目时，交互流程会增加最后一步，让你选择要固定的分支——使用与 neonctl checkout 相同的 ＋ Create a new branch… + 列表选择器（单分支项目会自动固定，不会提示）。非交互式的 link --project-id … 不会提示你选择分支，也不会默认选择分支；它只会链接组织和项目，分支选择留给 neonctl checkout：

? Which organization would you like to link? › Personal Org (org-abc123)
? Which project would you like to link? › my-app (polished-snowflake-12345678)
? Which branch would you like to link? › [default] main (br-main-branch-87654321)

非交互式（标志或 --params JSON） — 适用于脚本和 CI：

# Link to an existing project (org is inferred from the project; no branch pinned)
neonctl link --project-id polished-snowflake-12345678

# Same, but also pin a branch (name or id — resolved and stored as its name)
neonctl link --project-id polished-snowflake-12345678 --branch main

# Pin/switch the branch in the already-linked project
neonctl link --branch main          # alias: --branch-id

# Create a new project and link it (pins the new project's default branch)
neonctl link --org-id org-abc123 --project-name my-app --region-id aws-us-east-2

# Same payload, one JSON blob
neonctl link --params '{"orgId":"org-abc123","projectName":"my-app","regionId":"aws-us-east-2"}'

# Record just the default org (preserves any existing project/branch)
neonctl link --org-id org-abc123

# Forget the current context
neonctl link --clear

# Offline write — no API calls, no verification (see --no-checks below)
neonctl link --no-checks --org-id org-abc123 --project-id polished-snowflake-12345678

写入任何内容前，都会检查每个提供的标识符，并给出可执行的错误提示，例如：Project '…' not found、You don't have access to project '…'、Organization '…' not found, or your API key doesn't have access to it、Project '…' belongs to organization 'A', not 'B'，或 Branch '…' not found in project '…'. Available branches: …。

Agent 模式（--agent） — 专为 AI 编码助手设计的 JSON 状态机。每次调用都会返回一个 JSON 对象，其中包含用于说明下一步操作的 status 判别字段、可用选项，以及需要运行的精确后续命令。

$ neonctl link --agent
{
  "status": "needs_org",
  "instruction": "Ask the user which of these 2 organizations they want to link the current directory to. After they pick one, re-run the next_command_template with the chosen --org-id value.",
  "options": [
    { "id": "org-abc123", "name": "Personal Org" },
    { "id": "org-team",   "name": "Team Org" }
  ],
  "next_command_template": "neonctl link --agent --org-id <org_id>"
}

$ neonctl link --agent --org-id org-abc123
{
  "status": "needs_project",
  "instruction": "Ask the user whether to link to one of these 1 existing projects (use next_command_template with --project-id) or create a new project (use create_option.next_command_template).",
  "options": [
    { "id": "polished-snowflake-12345678", "name": "my-app" }
  ],
  "create_option": {
    "instruction": "To create a new project, ask the user for a project name. The region can be omitted to receive a follow-up needs_project_details response that lists available regions.",
    "next_command_template": "neonctl link --agent --org-id org-abc123 --project-name <name> --region-id <region_id>"
  },
  "next_command_template": "neonctl link --agent --org-id org-abc123 --project-id <project_id>"
}

$ neonctl link --agent --org-id org-abc123 --project-id polished-snowflake-12345678
{
  "status": "linked",
  "context_file": "/path/to/cwd/.neon",
  "context": {
    "orgId": "org-abc123",
    "projectId": "polished-snowflake-12345678"
  },
  "project": { "id": "polished-snowflake-12345678" },
  "message": "Linked /path/to/cwd/.neon to project polished-snowflake-12345678 (org org-abc123). No branch pinned — run `neonctl checkout <branch>` (omit the branch to list options) to pin one and pull its env vars."
}

除非已固定分支（通过 --branch、已有的固定设置或创建项目时），linked 响应不会包含 branch；传入 --branch <name|id> 可将其包含在内。Agent 流程也会处理项目创建：如果 Agent 发送 --project-name 而未发送 --region-id，下一条响应会是 needs_project_details，并附上受支持区域的列表。

组织级 API 密钥（在组织级而非用户级创建的密钥）无法列出用户组织，也无法调用区域端点。link 会透明地处理此情况：

• 如果 API 密钥的作用范围是组织级别，且该组织中已存在至少一个项目，CLI 会从第一个项目自动检测 org_id。在交互模式下，它会打印一条提示信息；在 --agent 模式下，它会直接跳转到 needs_project。
• 如果 API 密钥的作用范围是组织级别，且该组织中还没有项目，--agent 会返回 needs_org 响应，其中 options: []，并提示用户在 Neon Console 中查找组织 ID。交互模式则会打印一条错误信息，提示使用 --org-id。
• 如果 regions 端点不允许访问，link 会回退到内置的静态区域列表。

Agent 错误约定：在 --agent 模式下，任何意外失败都会以 JSON 格式输出到 stdout，并以退出代码 1 退出，因此 Agent 始终可以解析响应：

{
  "status": "error",
  "code": "CLIENT_ERROR",
  "message": "user has no access to projects"
}

离线写入（--no-checks）——写入 .neon，完全不调用 API：不推断组织、不验证是否存在或是否有访问权限，也不拉取环境变量。由于离线时无法解析任何信息，因此必须同时提供 --org-id 和 --project-id（--branch 可选，会按原样存储）。适用于脚本/CI 设置，或根据已有可信值重新创建 .neon：

neonctl link --no-checks --org-id org-abc123 --project-id polished-snowflake-12345678 --branch main

set-context 已弃用

set-context 已弃用，推荐使用 link。它会打印弃用警告（输出到 stderr，因此不会污染 stdout 或脚本）。为保持向后兼容，其行为保持不变：它仍会原样离线写入你传入的字段（不推断组织、不做验证、不拉取环境变量），而不带参数的 set-context 仍会清空文件。目前不会造成任何影响，但新工作应使用 link，且 set-context 将在未来的主要版本中移除。

当前 set-context 用法与 link 的对应关系：

set-context（已弃用）	推荐的 link 等效用法
neonctl set-context --project-id <id>	neonctl link --project-id <id>（推断组织并验证；通过 checkout 指定分支）
neonctl set-context --org-id <id>	neonctl link --org-id <id>
neonctl set-context --branch-id <id>	neonctl link --branch <name|id>
neonctl set-context（清除）	neonctl link --clear
原始本地写入（不联网）	neonctl link --no-checks --org-id <id> --project-id <id>

关键区别在于：link 会在写入前解析并验证（因此不会留下写入不完整或过期的 .neon），而 set-context 会将你提供的内容原样写入。与旧版原始写入最接近的替代方式是 link --no-checks。

checkout

checkout [id|name] 会在本地上下文中固定一个分支，使后续命令都以该分支为目标；对于常见的“切换到我正在使用的分支”场景，它是 link 的专用搭档（link 解析组织和项目；checkout 固定分支）。它会根据名称或 ID 在项目中解析分支，然后修复 .neon 文件：始终（重新）写入 projectId、branch，以及（当项目有组织时）orgId，因此缺少字段或内容已漂移的 .neon 文件最终都会完整且一致。已知分支名称时，会以其名称存储（与 link 一致）。如果尚未获知 orgId（通过 --org-id 或现有的 .neon），则会从项目本身查找。

分支参数为可选：在交互式终端中，不带分支运行 neonctl checkout，即可获取项目的分支并从列表中选择。在非交互式上下文（CI 或没有 TTY）中，必须显式传入分支。

系统会自动判断分支参数是 ID 还是名称（br-… 形式的值会被视为 ID）：

• ID — 严格按 ID 匹配。不存在的 ID 会导致明确的“未找到”错误（ID 由服务分配，因此 checkout 从不创建 ID）。
• 名称 — 按名称匹配。如果名称不存在，交互式终端中的 checkout 会提供创建该分支的选项（等同于 neonctl branch create --name <name>：从项目的默认分支创建，并使用读写计算资源），然后检出该分支。在非交互式上下文中，名称不存在时会显示常见的“未找到”错误。

项目通过标准的 neonctl 链解析，按以下顺序逐项尝试，优先使用靠前的项：

1. --project-id <id> 标志
2. 最近的 .neon 文件中的 projectId（从当前目录向上查找；见下文“.neon 文件的位置”）
3. 如果仍未解析到项目，且 API 密钥恰好对应一个项目，则自动检测该项目（行为与 branches 和 connection-string 相同）

如果这些方式都无法解析项目，checkout 会输出一条说明上述解析链的错误信息。在交互式终端中，它随后会提供选项，让你在当前文件夹运行 neonctl link，以便立即选择（或创建）项目；链接完成后，它会继续操作并固定请求的分支。在非交互式上下文（CI 或没有 TTY）中，它会以非零退出码退出，并显示相同的指引，而不会提示交互。

随后，解析出的分支会以名称形式写入 link 使用的同一个 .neon 文件：

$ neonctl checkout main --project-id polished-snowflake-12345678
INFO: Checked out branch br-main-branch-87654321 on project polished-snowflake-12345678. Updated /path/to/cwd/.neon.

$ cat .neon
{
  "orgId": "org-abc123",
  "projectId": "polished-snowflake-12345678",
  "branch": "main"
}

固定分支后，checkout 默认还会运行 env pull，将该分支的 Neon 环境变量写入本地 .env，让你可以立即开始构建；先分支再开发的流程只需 link + checkout。传入 --no-env-pull 可跳过此步骤（例如，环境变量在运行时通过 neon-env run / neonctl dev 注入，或你想避免机密信息进入工作树时）。拉取失败不会撤销 checkout：分支仍会保持固定状态，并显示警告，指引你运行 neonctl env pull（如果缺少由 neon.ts 声明的服务，则运行 neonctl deploy）。

env pull

env pull 会将已关联分支的 Neon 环境变量写入本地 dotenv 文件：如果已有 .env，则写入该文件；否则写入 .env.local（使用 --file <path> 覆盖）。只会写入由 Neon 管理的键（DATABASE_URL、DATABASE_URL_UNPOOLED，以及在启用相应服务时的 Neon Auth / Data API URL）；文件中的其他行都会保留。分支根据最近的 .neon 文件确定，因此无需指定 --branch（传入 --branch <id|name> 可指定其他分支）。

link 和 checkout 会自动调用 env pull（见上文），因此通常只需在手动刷新变量或将其他分支拉取到指定文件时运行：

# Refresh the linked branch's vars in place
neonctl env pull

# Pull a specific branch into a specific file
neonctl env pull --branch preview --file .env.preview

如果你不想将环境变量保存在磁盘上，可以改为在运行时注入：使用 neon-env run -- <your dev command>（来自 @neondatabase/env）或 neonctl dev，并向 link / checkout 传入 --no-env-pull。

.neon 的位置：默认情况下，link 会在当前工作目录中写入 .neon。如果在任何父目录中找到现有的 .neon，则会重用该文件，因此从已关联项目的子目录运行命令时，也会沿用项目上下文。若要明确指定位置，请传入 --context-file <path>。

.gitignore 脚手架：首次创建 .neon 时，CLI 还会确保其所在目录中有一个 .gitignore，并在其中列出 .neon。如果 .gitignore 不存在，则会创建一个只包含 .neon 行的文件；如果已存在，则仅在缺少 .neon 时追加（不会重复，也不会改动其他条目）。后续更新现有 .neon 时，不会改动 .gitignore — 因此，如果你有意取消对 .neon 的忽略（例如，为了提交共享上下文），该条目不会在每次运行命令时重新添加。

以代码管理配置（config / deploy）

在 neon.ts 策略中描述分支的期望状态，并通过 CLI 协调状态 — 相当于 Neon 版的 terraform status / plan / apply。策略分为静态存在性集合 — 顶层的 auth / dataApi 开关和 beta preview 块（Functions、存储桶、AI Gateway），用于决定哪些内容_存在_ — 以及动态的 branch 闭包，该闭包会根据正在评估的分支（name、isDefault、…）调整各分支设置（计算资源设置、TTL、保护状态、parent）：

// neon.ts
import { defineConfig } from '@neondatabase/config/v1';

export default defineConfig({
  // Static: what exists on every branch (drives the typed env).
  auth: true,
  // Dynamic: per-branch tuning only — cannot add/remove services.
  branch: (branch) => {
    if (branch.isDefault) {
      return { protected: true };
    }
    return { parent: 'main', ttl: '7d' };
  },
});

通过三个子命令和一个顶层别名来驱动：

# Inspect the branch's live Neon state (read-only — never mutates)
neon config status

# Dry-run diff: show exactly what `apply` would change
neon config plan

# Reconcile the policy against the branch
neon config apply

# `neon deploy` is an alias for `neon config apply`
neon deploy

项目和分支解析遵循 CLI 其余部分使用的相同顺序，前一项优先于后一项：

1. --project-id <id> 标志
2. 最近的 .neon 文件中的 projectId（从当前目录向上查找 — 见上文“.neon 的位置”）
3. 如果仍无法解析，且 API 密钥恰好对应一个项目，则自动检测该项目

使用 --branch <id|name> 选择分支；如果不指定，则使用项目的默认分支。策略文件会从当前目录向上查找 neon.ts；也可以传入 --config <path> 显式指定文件。

仅适用于 apply 的标志（deploy 也可使用）：

• --update-existing — 自动确认覆盖分支上现有的远程设置。如果不指定，远程已存在的设置（计算资源、TTL、protected）出现偏差时会报告为冲突，在解决冲突或传入此标志之前，apply 不会做出任何更改。
• --allow-protected — 自动确认将更改应用于 Neon 标记为受保护的分支。如果不指定，apply 会拒绝更改受保护的分支。

输出：status 会打印项目、分支和反向推导出的配置；plan / apply 会以表格形式打印计划或已应用的更改以及任何冲突。传入 --output json（或 --output yaml）可输出完整的机器可读结果（PushResult），以便通过管道传递给其他工具或 CI。

# CI gate: fail the build if the branch has drifted from the policy
neon config plan --project-id polished-snowflake-12345678 --output json

# Reconcile a feature branch, overriding any manual tweaks made in the console
neon deploy --branch my-feature --update-existing

在 preview.functions 下声明的 Function 部署由 neonctl 自带的 esbuild 辅助工具打包，并作为 apply 的一部分上传，因此策略可保持声明式，而打包后的 CLI 无需嵌入 esbuild 的原生二进制文件。

搭建项目（bootstrap）

neonctl bootstrap 会将 Neon 入门模板复制到新的目录或当前目录中——概念上类似于 degit，但它只会从我们在公开的 neondatabase/examples 仓库中维护的一小组模板拉取内容。无需登录 Neon：它只会从 GitHub 下载文件。

传入目标目录（当前目录则传入 .）。在交互式终端中，你可以从列表中选择模板；在 CI 或非交互式环境中，请传入 --template <id>。

# Pick a template interactively and scaffold it into ./my-app
$ neonctl bootstrap my-app

# Scaffold a specific template into the current directory (no prompts)
$ neonctl bootstrap . --template hono

除非传入 --force，否则目标目录必须为空（单独存在的 .git 会被忽略，因此刚执行过 git init 的文件夹也可以）。模板中的符号链接和可执行权限位会得到保留。

命令

命令	子命令	描述
auth		进行身份验证
projects	list, create, update, delete, get	管理项目
ip-allow	list, add, remove, reset	管理 IP 允许列表
me		显示当前用户
branches	list, create, rename, add-compute, set-default, set-expiration, delete, get	管理分支
databases	list, create, delete	管理数据库
function	deploy, list, get, delete	管理 Neon 函数
roles	list, create, delete	管理角色
operations	list	管理操作
connection-string		获取连接字符串
psql		通过 psql 连接到数据库
set-context		已弃用；请使用 link
env	pull	管理分支的环境变量
checkout		在 .neon 中固定一个分支
link		将目录链接到项目
config	status, plan, apply	根据 neon.ts 驱动分支
deploy		config apply 的别名
bootstrap		根据模板搭建项目
bucket	create, list, delete, object list, object get, object put, object delete (incl. --recursive)	管理存储桶及其对象
completion		生成补全脚本

全局选项

所有 Neon CLI 命令均支持全局选项。

选项	描述	类型	默认值
-o, --output	设置 Neon CLI 输出格式（json、yaml 或 table）	string	table
--config-dir	Neon CLI 配置目录的路径	string	/home/<user>/.config/neonctl
--api-key	Neon API 密钥	string	""
--analytics	管理分析功能	boolean	true
-v, --version	显示 Neon CLI 版本号	boolean	-
-h, --help	显示 Neon CLI 帮助	boolean	-

• -o, --output

  设置输出格式。支持的选项为 json、yaml 和 table。默认值为 table。表格输出可能不完整。json 和 yaml 输出格式会显示所有数据。

  neonctl me --output json
  

• --config-dir

  指定 neonctl 配置目录的路径。若要查看包含 credentials.json 文件的默认配置目录，请运行 neonctl --help。使用 neonctl auth 命令进行身份验证时会创建凭据文件。只有在将 neonctl 配置文件移至默认位置以外的其他位置时，才需要使用此选项。

  neonctl projects list --config-dir /home/dtprice/.config/neonctl
  

• --api-key

  指定你的 Neon API 密钥。运行 Neon CLI 命令时，可以使用 Neon API 密钥进行身份验证，而无需使用 neonctl auth。有关如何获取 Neon API 密钥的信息，请参阅 Neon API Reference 中的身份验证。

  neonctl <command> --api-key <neon_api_key>
  

• --analytics

  默认情况下会启用分析功能，以收集客户使用的 CLI 命令和选项相关信息。这些数据有助于我们提供支持，并更好地了解典型使用模式，从而改善用户体验。Neon 不会收集用户定义的数据，例如项目 ID 或命令负载。若要选择退出分析数据收集，请指定 --no-analytics 或 --analytics false。

• -v, --version

  显示 Neon CLI 版本号。

  $ neonctl --version
  1.15.0
  

• -h, --help

  显示 neonctl 命令行帮助。你可以查看 neonctl、neonctl 命令或 neonctl 子命令的帮助，如下例所示：

  neonctl --help
  
  neonctl branches --help
  
  neonctl branches create --help
  

参与贡献

此仓库使用 pnpm。所需版本固定在 .tool-versions 和 package.json 的 packageManager 字段中。获取正确版本的最简单方法是使用 mise：mise install 会读取 .tool-versions 并安装 Node 和 pnpm。其他方式：npm install -g [email protected]，或使用 Corepack（corepack enable pnpm）。

进行更改后，运行构建命令即可在本地运行 CLI：

pnpm install
pnpm run build

持续开发：

pnpm run watch

若要运行本地构建中的命令，请将 neonctl 命令替换为 node dist；例如：

node dist branches --help

内嵌 psql 测试

内嵌的 TypeScript psql 实现拥有独立的一致性测试套件。该套件会使用内嵌 psql 和参考 psql 二进制文件运行相同的脚本，然后对比输出。

bun run test:conformance         # run against $PSQL_BINARY (defaults to the system psql)
bun run test:conformance:matrix  # run across PG 14/15/16/17/18 locally (requires Docker)

发布

维护者：请参阅 RELEASING.md，了解两阶段发布流程。