Skip to content
PlanetScale CLI Automation

PlanetScale CLI AutomationSkill

by PlanetScale
Added to Onei
Repository Docs
markdown Development

Summary

How to drive the PlanetScale CLI non-interactively: --format json everywhere, auth check before anything else, pscale sql instead of pscale shell, correct flag placement.

Features

  • Bootstrap with `pscale agent-guide` and `pscale auth check`, both --format json
  • --format json on every command so output is parseable, never a table
  • --org belongs on the resource subcommand, not on root pscale
  • Positional arguments before flags; --force where a prompt would block
  • `pscale sql` for non-interactive queries — never `pscale shell`
  • Separates the CLI's AGENTS.md from your project's, and forbids editing the latter unasked

Install This Skill

Add this skill to your favorite AI agent in a few steps.

Any AI agent

This skill is plain instructions — it works with any assistant that accepts custom instructions or system prompts.

  1. Copy the skill content with the button below.
  2. Paste it into your agent's instruction file or system prompt (for example AGENTS.md, .cursorrules, or a custom instructions field).
  3. Ask the agent to apply the skill whenever the task matches.

Skill Content

Markdown Content

Copy this content and use it with your preferred AI agent

---
name: planetscale-pscale-cli-automation
description: >-
  Use the PlanetScale CLI (pscale) from automated agents with --format json,
  auth check, pscale sql, and per-command --force. Run before other PlanetScale
  skills when driving pscale directly. Use when the user asks to automate
  pscale, run CLI commands headless, or verify pscale auth from an agent.
---

# PlanetScale CLI automation

## 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
`../planetscale-safe-orchestrator/SKILL.md` for a full assessment.

## Two AGENTS.md files (do not confuse them)

| 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
`../planetscale-mcp-agent-operating-model/SKILL.md`).

## Bootstrap (always start here)

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

If `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`.

## 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` or `PSCALE_FORCE`.
- **`--format json` alone never skips confirmations** — add `--force` on the
  destructive subcommand after explicit user approval.

## 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.

## MCP vs 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.

## When this skill is not enough

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

```sh
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 `../planetscale-safe-orchestrator/SKILL.md` for database operations
beyond basic CLI invocation.

## 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.

Usage Instructions

Learn how to use this skill with different AI agents.

Generic Instructions
npx skills add planetscale/skills -g -y

Description

pscale is built for a human at a terminal, and an agent that treats it that way hangs on an interactive prompt or parses a table that was never meant to be parsed. This official PlanetScale skill is the conventions layer that stops that happening. It covers the CLI only — the operational workflows live in the pack's other skills.

Bootstrap, then assume nothing

Two commands come first, every time: pscale agent-guide --format json for the CLI's own machine-readable conventions, and pscale auth check --format json to confirm authentication. When auth check comes back "status": "action_required", the JSON carries issues and next_steps to follow — and login may need a human to approve in a browser, which the skill flags rather than letting the agent stall.

The conventions that actually bite
  • `--format json` on everything. Table output is for people.
  • `--org <org>` goes on the resource subcommand (database, branch, sql, api), not on root pscale. This is the flag placement people get wrong first.
  • Positional arguments before flags: pscale sql mydb main --org bb ....
  • `pscale sql`, never `pscale shell` — the latter is interactive and will hang an unattended run.
  • `--force` per command where a confirmation prompt would otherwise appear.
Two AGENTS.md files, and they are not the same

A distinction worth the space it takes: the CLI's own AGENTS.md (shipped with pscale, or pscale agent-guide) tells an agent how to call the CLI. Your application repository's AGENTS.md tells it which org, database, branch, engine, production branch, MCP scope and approval rules apply. The skill is explicit that the project file is not the agent's to edit without operator approval.

Run this before the other PlanetScale skills whenever the agent is driving pscale directly. Part of PlanetScale's official skill pack; works with any agent that reads SKILL.md.

Related Skills

Skill: Inngest Agents

by Inngest

New

Build crash-safe AI agents on AgentKit and step.ai — durable tool calls, human-in-the-loop approval, realtime progress, and when not to reach for an agent loop at all.

Development
1 views

Skill: Inngest Durable Functions

by Inngest

New

Inngest's durable-execution playbook as an agent skill — steps and memoisation, event and cron triggers, idempotency, cancellation, retries and non-retriable errors.

Development
2 views

Skill: Temporal Developer

by Temporal

New

Temporal's official skill for building durable workflows — SDK patterns across seven languages, plus the determinism rules that decide whether a workflow survives a replay.

Development
6 views
Browse all skills →