planetscale-pscale-cli-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PlanetScale CLI automation

PlanetScale CLI自动化

Purpose

用途

Teach agents how to invoke

pscale

non-interactively. This skill covers CLI conventions only. Operational workflows (inventory, safety review, schema recommendations) use the other skills in this repo — start with

../00-safe-orchestrator/SKILL.md

for a full assessment.

指导代理如何以非交互方式调用

pscale

。本技能仅涵盖CLI约定。操作工作流（清单、安全审查、架构建议）需使用本仓库中的其他技能——如需完整评估，请从

../00-safe-orchestrator/SKILL.md

开始。

Two AGENTS.md files (do not confuse them)

两个AGENTS.md文件（请勿混淆）

Document	Where	Purpose
CLI agent guide	Shipped with `pscale` ( `AGENTS.md` in the CLI repo, or `pscale agent-guide` )	How to call `pscale` : auth, `--format json` , flag placement, `pscale sql`
Project agent guide	Your application repository's `AGENTS.md`	Which org, database, branch, engine, prod branch, MCP scope, approval rules

Do not edit project

AGENTS.md

without operator approval (see

../09-mcp-agent-operating-model/SKILL.md

文档	位置	用途
CLI代理指南	随 `pscale` 发布（CLI仓库中的 `AGENTS.md` ，或通过 `pscale agent-guide` 命令获取）	如何调用 `pscale` ：身份验证、 `--format json` 、参数位置、 `pscale sql`
项目代理指南	应用程序仓库中的 `AGENTS.md`	指定组织、数据库、分支、引擎、生产分支、MCP范围、审批规则

未经操作员批准，请勿编辑项目的

AGENTS.md

（详见

../09-mcp-agent-operating-model/SKILL.md

）。

Bootstrap (always start here)

初始化（始终从此处开始）

bash

pscale agent-guide --format json
pscale auth check --format json

auth check

returns

"status": "action_required"

, follow

issues

and

next_steps

in the JSON. For login, the human may need to approve in the browser; use

pscale auth login --format json

bash

pscale agent-guide --format json
pscale auth check --format json

如果

auth check

"status": "action_required"

，请遵循JSON中的

issues

和

next_steps

字段。如需登录，用户可能需要在浏览器中进行批准；使用

pscale auth login --format json

命令。

Conventions

约定

Always pass --format json
for automation.
Put --org <org>
on resource subcommands (
```
database
```
,
```
branch
```
,
```
sql
```
,
```
api
```
, …) — not on root
```
pscale
```
.
Put positional arguments before flags (
```
pscale sql mydb main --org bb …
```
).
Use pscale sql
, not
```
pscale shell
```
(shell requires a TTY).
Default SQL role is reader; pass
```
--role admin
```
(or writer/readwriter) for writes. Match
```
pscale shell
```
semantics for
```
--role
```
and
```
--replica
```
.

--force
is per subcommand only (e.g.

database delete … --force

pscale sql … --force

). There is no global

--force

PSCALE_FORCE

--format json
alone never skips confirmations — add
```
--force
```
on the destructive subcommand after explicit user approval.

自动化时始终传递**
```
--format json
```
**参数。
将**
```
--org <org>
```
**参数放在资源子命令（
```
database
```
、
```
branch
```
、
```
sql
```
、
```
api
```
等）中——而非根命令
```
pscale
```
。
将位置参数放在标志之前（例如
```
pscale sql mydb main --org bb …
```
）。
使用**
```
pscale sql
```
**，而非
```
pscale shell
```
（shell需要TTY）。
默认SQL角色为reader；如需写入操作，请传递
```
--role admin
```
（或writer/readwriter）。
```
--role
```
和
```
--replica
```
的语义与
```
pscale shell
```
保持一致。
**
```
--force
```
**仅适用于子命令（例如
```
database delete … --force
```
、
```
pscale sql … --force
```
）。不存在全局
```
--force
```
或
```
PSCALE_FORCE
```
环境变量。
仅
--format json
不会跳过确认步骤——在获得用户明确批准后，需在破坏性子命令中添加
```
--force
```
参数。

Typical workflow

典型工作流

bash

pscale auth check --format json
pscale org list --format json
pscale database list --org <org> --format json
pscale branch list <database> --org <org> --format json
pscale sql <database> <branch> --org <org> --format json --query "SELECT 1"

MySQL uses

@primary

by default (same as

pscale shell

); pass

--keyspace

only for multi-keyspace databases.

bash

pscale auth check --format json
pscale org list --format json
pscale database list --org <org> --format json
pscale branch list <database> --org <org> --format json
pscale sql <database> <branch> --org <org> --format json --query "SELECT 1"

MySQL默认使用

@primary

（与

pscale shell

相同）；仅在多键空间数据库中需传递

--keyspace

参数。

MCP vs CLI

MCP与CLI对比

MCP clients — use the hosted PlanetScale MCP server (see
```
pscale agent-guide --format json
```
for the current URL).
Shell scripts and coding agents — use
```
pscale
```
with
```
--format json
```
as above.

MCP客户端——使用托管的PlanetScale MCP服务器（当前URL可通过
```
pscale agent-guide --format json
```
获取）。
Shell脚本与编码代理——按上述方式使用带
```
--format json
```
参数的
```
pscale
```
。

When this skill is not enough

当本技能不足以满足需求时

Install the full PlanetScale skills pack (if not already):

git clone https://github.com/planetscale/skills.git && cd skills && script/setup

安装完整的PlanetScale技能包（如果尚未安装）：

git clone https://github.com/planetscale/skills.git && cd skills && script/setup

or: npx skills add planetscale/skills -g -y


Then run sub-skills or `../00-safe-orchestrator/SKILL.md` for database operations
beyond basic CLI invocation.


然后运行子技能或`../00-safe-orchestrator/SKILL.md`以完成基础CLI调用之外的数据库操作。

Current conventions source of truth

当前约定的权威来源

Prefer live output over memorized flag syntax:

bash

pscale agent-guide --format json

The embedded

guide

field contains the full CLI agent guide shipped with your

pscale

binary.

优先使用实时输出而非记忆的标志语法：

bash

pscale agent-guide --format json

其中嵌入的

guide

字段包含随

pscale

二进制文件发布的完整CLI代理指南。