polygres-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Polygres CLI

Operate a user's Polygres project through the installed

polygres

command. Treat the CLI as the operational and security boundary. Do not call private control-plane routes or infer undocumented request payloads.

通过已安装的

polygres

命令操作用户的Polygres项目。将CLI视为操作和安全边界。请勿调用私有控制平面路由或推断未文档化的请求负载。

Start safely

安全启动

Run
```
polygres --version
```
and
```
polygres --help
```
before live or end-to-end testing, and whenever availability or command compatibility is unknown.
If the command is missing, tell the user how to install
```
polygres-cli
```
and let them approve or perform the installation. Do not install packages silently.
For live tests from a Polygres source checkout, create an isolated test environment, reinstall both
```
polygres-cli
```
and
```
polygres-sdk
```
from that checkout under its dependency-installation policy, and verify their versions and import origins before testing. Do not substitute PyPI packages for the checkout under test.
Outside a source checkout, compare installed CLI and SDK versions with the versions required by the application or current skill compatibility record. Do not call an installation current merely because the command exists. Obtain approval before changing installed packages.
Run
```
polygres whoami
```
before a mutation when identity or active organization is uncertain. Use
```
polygres login
```
when authentication is required.
Resolve the project with
```
polygres projects list
```
, an explicit
```
--project
```
, or
```
polygres projects use <project>
```
. State the resolved project before a destructive, secret-producing, or schema-mutating operation.
Resolve
```
project_mode
```
. When it is
```
synced
```
, read
```
references/synced-projects.md
```
before choosing any command.
Prefer
```
polygres --json ...
```
for output the agent must parse. Treat stdout as the JSON channel and stderr as diagnostics.

If bundled examples differ from the installed

--help

, follow the installed command surface and explain the version mismatch. Never guess a replacement.

在进行实时测试或端到端测试前，以及每当可用性或命令兼容性未知时，运行
```
polygres --version
```
和
```
polygres --help
```
。
如果命令缺失，告知用户如何安装
```
polygres-cli
```
并让其批准或执行安装操作。请勿静默安装包。
从Polygres源码检出进行实时测试时，创建隔离测试环境，根据其依赖安装策略从该检出版本重新安装
```
polygres-cli
```
和
```
polygres-sdk
```
，并在测试前验证它们的版本和导入来源。请勿用PyPI包替代待测试的检出版本。
在源码检出环境外，将已安装的CLI和SDK版本与应用或当前技能兼容性记录要求的版本进行对比。不能仅因命令存在就认为安装是最新的。更改已安装包前需获得批准。
当身份或活跃组织不确定时，在执行变更操作前运行
```
polygres whoami
```
。需要身份验证时使用
```
polygres login
```
。
通过
```
polygres projects list
```
、显式的
```
--project
```
参数或
```
polygres projects use <project>
```
来确定项目。在执行破坏性、生成密钥或变更架构的操作前，说明已确定的项目。
确定
```
project_mode
```
。当模式为
```
synced
```
时，在选择任何命令前阅读
```
references/synced-projects.md
```
。
对于Agent需要解析的输出，优先使用
```
polygres --json ...
```
。将标准输出视为JSON通道，标准错误视为诊断信息通道。

如果捆绑示例与已安装命令的

--help

内容不符，请遵循已安装命令的接口并解释版本不匹配问题。切勿猜测替代命令。

Route the request

路由请求

Read only the references needed for the task:

User intent	Reference
Login, logout, identity, organization, project selection or status	`references/authentication-and-projects.md`
Synced-project creation, capabilities, lifecycle handoff, and permission boundaries	`references/synced-projects.md`
Environment, Postgres metadata, `psql` , Runtime API keys	`references/database-and-keys.md`
Dataset or backfill from CSV, TSV, a JSON array, or JSONL/NDJSON	`references/data-imports.md`
Validate, insert, upsert, or ignore one JSON object or runtime event	`references/rows.md`
Migration list/apply and SQL safety	`references/migrations.md`
Graph, text, existing vector configurations, and general retrieval readiness	`references/retrieval.md`
Polygres AI Context collections, filters, points, operations, and retrieval	`references/context.md`
JSON output, polling, exit codes, retry and recovery	`references/automation-and-errors.md`

仅阅读完成任务所需的参考文档：

用户意图	参考文档
登录、登出、身份验证、组织、项目选择或状态	`references/authentication-and-projects.md`
同步项目的创建、功能、生命周期交接和权限边界	`references/synced-projects.md`
环境、Postgres元数据、 `psql` 、Runtime API密钥	`references/database-and-keys.md`
从CSV、TSV、JSON数组或JSONL/NDJSON导入数据集或回填数据	`references/data-imports.md`
验证、插入、更新插入或忽略单个JSON对象或运行时事件	`references/rows.md`
迁移列表/应用及SQL安全性	`references/migrations.md`
图、文本、现有向量配置及通用检索就绪状态	`references/retrieval.md`
Polygres AI Context集合、过滤器、点、操作及检索	`references/context.md`
JSON输出、轮询、退出码、重试与恢复	`references/automation-and-errors.md`

Execute an operation

执行操作

Classify the request as read-only, mutating, destructive, schema-mutating, or secret-producing.
Load the relevant reference and validate local inputs.
Resolve authentication and project context.
Resolve project mode and stop any command that is unavailable for that mode.
For a mutation, show the target project, affected resource, important options, and reversibility.
Obtain explicit approval when required. Accept an existing consolidated pipeline approval when it names this exact project, source scope, action, and unchanged plan digest.
Run the narrowest documented command.
Retain project, job, migration, configuration, key, and request IDs from the result.
Report only the observed terminal state. If work is still running, say so and provide the status command.

将请求分类为只读、变更、破坏性、变更架构或生成密钥类型。
加载相关参考文档并验证本地输入。
确定身份验证和项目上下文。
确定项目模式，停止任何该模式下不支持的命令。
对于变更操作，展示目标项目、受影响的资源、重要选项及可逆性。
必要时获取明确批准。如果现有合并流水线批准明确指定了此项目、源范围、操作及未更改的计划摘要，则可接受该批准。
运行最窄范围的已文档化命令。
保留结果中的项目、任务、迁移、配置、密钥及请求ID。
仅报告观察到的最终状态。若任务仍在运行，需说明并提供状态查询命令。

Require consent

需获取同意

Obtain explicit user approval before:

```
replace_existing
```
imports;
applying a SQL migration;
creating or updating a text configuration, including a generated TSVector column or managed text index;
reindexing a text configuration;
revoking a Runtime API key;
deleting existing vector or text configurations;
every durable pgContext mutation, including collection create, update, set-default, vector addition, default-vector change, reindex, or delete; filter registration; point reconciliation; and operation cancellation or retry;
pgContext point upsert or delete when it will become a durable operation or when deleting mappings is destructive for the user's serving behavior;
any command that uses
```
--yes
```
;
any other operation that is destructive or difficult to reverse.

Add

--yes

only after approval for that exact operation and target. Do not add a second confirmation to an explicit

rows insert

rows upsert

, or

rows ignore

command that is already authorized by the user's command or a matching consolidated pipeline approval. Before approval for

add-column

new-table

collection creation, also show the preflight DDL, affected schema objects, and ownership boundaries.

在执行以下操作前需获取用户明确批准：

```
replace_existing
```
导入；
应用SQL迁移；
创建或更新文本配置，包括生成的TSVector列或托管文本索引；
重新索引文本配置；
撤销Runtime API密钥；
删除现有向量或文本配置；
所有持久化pgContext变更，包括集合创建、更新、设置默认值、添加向量、更改默认向量、重新索引或删除；过滤器注册；点协调；以及操作取消或重试；
当pgContext点更新插入或删除会成为持久化操作，或删除映射对用户的服务行为具有破坏性时；
任何使用
```
--yes
```
参数的命令；
任何其他具有破坏性或难以撤销的操作。

仅在获得该具体操作和目标的批准后添加

--yes

参数。对于已获用户命令或匹配的合并流水线批准授权的

rows insert

、

rows upsert

或

rows ignore

命令，无需添加二次确认。在批准

add-column

或

new-table

集合创建前，还需展示预检查DDL、受影响的架构对象及所有权边界。

Protect secrets

保护密钥

Never request, retrieve, store, log, or pass a native database password.
Never request, print, or place a synced source connection in an argument, generated file, or transcript. Prefer the CLI's hidden interactive URL prompt. For approved non-interactive work, reference a user-populated environment variable with
```
--connection-env
```
; never inspect its value.
Let
```
psql
```
prompt the user for the database password.
If an agent terminal cannot maintain an interactive TTY, give the user the passwordless command or ask them to run
```
polygres db psql
```
directly.
Never ask a user for
```
POLYGRES_ACCESS_TOKEN
```
. It is a development and test override, not a public authentication workflow.
Warn before
```
polygres keys create <name>
```
because the Runtime API-key secret is shown once and can enter terminal or agent history.
Offer to let the user run key creation in their own terminal so the secret does not enter the agent transcript.
Never place tokens, keys, or passwords in source files, examples, command arguments, logs, or final summaries.

切勿请求、检索、存储、记录或传递原生数据库密码。
切勿请求、打印或将同步源连接信息放入参数、生成文件或记录中。优先使用CLI的隐藏交互式URL提示。对于已批准的非交互式任务，使用
```
--connection-env
```
引用用户填充的环境变量；切勿查看其值。
让
```
psql
```
提示用户输入数据库密码。
如果Agent终端无法维持交互式TTY，提供无密码命令或让用户直接运行
```
polygres db psql
```
。
切勿向用户索要
```
POLYGRES_ACCESS_TOKEN
```
。它是开发和测试的覆盖项，并非公开身份验证工作流。
在运行
```
polygres keys create <name>
```
前发出警告，因为Runtime API密钥的密文仅显示一次，且可能进入终端或Agent历史记录。
建议用户在自己的终端中运行密钥创建操作，以免密文进入Agent记录。
切勿将令牌、密钥或密码放入源文件、示例、命令参数、日志或最终摘要中。

Prepare non-CSV data locally

本地准备非CSV数据

For TSV, JSON arrays, and JSONL/NDJSON datasets, read

references/data-imports.md

and use

scripts/prepare_import.py

. Route one JSON object intended as an individual write to

references/rows.md

instead. Resolve the script path from this skill directory instead of assuming the repository contains

scripts/

The converter is local-only and produces a reviewed CSV artifact. It does not call Polygres. Never silently flatten nested JSON, rename columns, or collapse null and empty-string values without explaining the result and obtaining the required approval.

Do not present SQL migrations as a generic row-import mechanism. Do not call the backend SQL-import or

pg_dump

routes because those commands are not in the current public CLI.

对于TSV、JSON数组和JSONL/NDJSON数据集，请阅读

references/data-imports.md

并使用

scripts/prepare_import.py

。若要写入单个JSON对象，请转而使用

references/rows.md

。从该技能目录中确定脚本路径，勿假设仓库包含

scripts/

目录。

转换器仅在本地运行并生成经过审核的CSV产物。它不会调用Polygres。未经解释结果并获得必要批准，切勿静默扁平化嵌套JSON、重命名列或合并null值与空字符串值。

请勿将SQL迁移作为通用行导入机制。请勿调用后端SQL导入或

pg_dump

路由，因为这些命令不在当前公开CLI范围内。

Handle failures

处理故障

Use

references/automation-and-errors.md

to interpret exit codes. In particular:

Fix validation before retrying exit
```
2
```
.
Reauthenticate on exit
```
3
```
.
Explain missing permission on exit
```
4
```
.
Resolve missing resources on exit
```
5
```
.
Resolve conflicts or ambiguous project selection on exit
```
6
```
.
Respect rate-limit guidance on exit
```
7
```
.
Treat exit
```
8
```
as remote failure or timeout.
Install or hand off a missing local dependency such as
```
psql
```
on exit
```
9
```
.

After an import or provisioning timeout, check the known resource or job status before resubmitting. A timed-out client does not prove the server operation failed.

使用

references/automation-and-errors.md

解读退出码。尤其注意：

退出码
```
2
```
：修复验证问题后再重试。
退出码
```
3
```
：重新进行身份验证。
退出码
```
4
```
：解释权限缺失问题。
退出码
```
5
```
：解决资源缺失问题。
退出码
```
6
```
：解决冲突或项目选择模糊问题。
退出码
```
7
```
：遵循速率限制指引。
退出码
```
8
```
：视为远程故障或超时。
退出码
```
9
```
：安装或移交缺失的本地依赖（如
```
psql
```
）。

导入或配置超时后，在重新提交前检查已知资源或任务状态。客户端超时并不代表服务器操作失败。