PlanetScale CLI: branches and deploy requests from the terminal

What pscale actually manages

PlanetScale is a hosted database platform, and pscale is its terminal client. The README frames the tool around three concepts: branches, deploy requests and "other PlanetScale concepts". That is the scope. The CLI does not run a database server on your machine, and it does not replace a MySQL client for query work. It talks to the PlanetScale API and renders the results in your shell, so the unit of work is a platform object, not a table row.

The audience follows from that. A team that already has a PlanetScale organization gets a way to script the parts of the platform that would otherwise live in a web console: creating a branch, opening a deploy request, listing the deploy requests that are waiting. Anyone who wants a general purpose MySQL CLI is looking at the wrong tool, and the README does not claim otherwise.

One detail in the README is worth reading twice. It says the CLI is "more than a jumble of commands", which is a positioning statement rather than a technical one. The concrete version of that claim is the file layout: cmd/ holds the entry point, internal/ holds the implementation, and doc/ holds notes such as doc/api-client.md. That is a conventional Go CLI structure, and it tells you the project is organized around one binary rather than a plugin system.

How the CLI is wired: cobra, vendored API client, XDG config

The dependency list in go.mod is the clearest description of the architecture available. Command parsing is cobra with pflag, and configuration is viper. Interactive prompts use the charmbracelet stack (bubbletea, huh, lipgloss, bubbles), so commands that need input can render a terminal UI rather than a bare prompt. Credentials are stored through 99designs/keyring, and config paths come from adrg/xdg, which means the CLI follows the XDG convention on platforms that have one rather than inventing its own directory.

The API layer is the part that changed. The README states that the API client is vendored at internal/planetscale/ and that the repository "no longer depends on planetscale-go". Anyone reading older tutorials that mention importing planetscale-go into their own Go code is reading about a different arrangement. The README also points at doc/api-client.md and asks contributors to read it before touching API-facing code, which is a signal that the boundary between command code and API code is deliberate.

For database connectivity the module pulls in go-sql-driver/mysql, lib/pq and jackc/pgx, plus vitess.io/vitess and github.com/planetscale/psdb and psdbproxy. The mix of MySQL and Postgres drivers is visible in the manifest, but the README does not document which commands use which driver, so that is a question to answer from the source rather than from the docs. The Dockerfile installs mysql-client into the runtime image and exposes port 3306, which is consistent with commands that open a connection rather than only call the API.

Installing pscale and running a first command

macOS users install through the Homebrew tap. The README notes that certain commands need a MySQL 8 client on the PATH, and gives the Homebrew formula for it.

brew install planetscale/tap/pscale
brew install [email protected]

Upgrades go through the same package manager, so `brew upgrade pscale` moves you to the current release. Windows users go through scoop, and the README installs the MySQL client in the same step.

scoop bucket add pscale https://github.com/planetscale/scoop-bucket.git
scoop install pscale mysql

Linux has no package manager path in the README. It points at the releases page for .deb and .rpm files, installed with `sudo dpkg -i` or `sudo rpm -i`, and mentions an Arch package named pscale-cli-bin. There is also a cross-platform installer, bin, which the README shows as `bin install https://github.com/planetscale/cli`.

If you would rather not install anything, the project publishes container images. The README gives `docker pull planetscale/pscale:latest` for the current build and a versioned tag form for pinning. It also offers a shell alias that runs the container as your own user, mounts $HOME/.config/planetscale into the container, and publishes port 3306. That alias is the piece to read carefully: without the config mount, a containerized pscale would lose the credentials you stored on the host.

mkdir -p $HOME/.config/planetscale
alias pscale="docker run -e HOME=/tmp -v $HOME/.config/planetscale:/tmp/.config/planetscale --user $(id -u):$(id -g) --rm -it -p 3306:3306/tcp planetscale/pscale:latest"

The README does not show a login command in the excerpt, so the first step after install is not documented here. What it does show is CI usage, where credentials arrive as environment variables rather than an interactive session. The GitHub Actions example installs the CLI with setup-pscale-action and then lists deploy requests for a database.

- name: Setup pscale
  uses: planetscale/setup-pscale-action@v1
- name: Use pscale
  env:
    PLANETSCALE_SERVICE_TOKEN_ID: ${{ secrets.PLANETSCALE_SERVICE_TOKEN_ID }}
    PLANETSCALE_SERVICE_TOKEN: ${{ secrets.PLANETSCALE_SERVICE_TOKEN }}
  run: |
    pscale deploy-request list my-db --org my-org

That snippet is the first real use case in the README: a service token pair, an organization, a database name, and a subcommand that returns a list. Expect tabular output, since the module includes a table printer. The README also mentions `pscale agent-guide` and `pscale --skill` for automation, and a separate repository, planetscale/skills, for operational workflows.

Where pscale stops being the right tool

The sharpest limitation is that pscale is a client for a hosted service. There is no documented mode that points it at a self-managed MySQL instance, and nothing in the README suggests the API client can be redirected. If your databases are not on PlanetScale, the binary has nothing to talk to. That is not a defect, it is the design, but it rules the tool out for a large share of people who search for a MySQL CLI.

The second constraint is the MySQL 8 client dependency. The README says pscale "requires a MySQL 8 Client in your PATH for certain commands", and the Dockerfile installs mysql-client into the runtime image for the same reason. The README does not enumerate which commands those are. On a minimal CI runner or a slim container, that gap surfaces as a failure at the moment you need the command, not at install time. The Docker image sidesteps it; a hand-rolled image will not.

Third, the release cadence is high. Three releases landed between 2026-08-25 and 2026-08-28, and the version string is still in the v0.3xx range, which conventionally signals pre-1.0. The last push to the repository was on 2026-08-28. Nothing in the README promises command-line or output stability, and the vendored API client means internal changes can land without a corresponding upstream module bump. If you parse pscale output in a script, pin a version rather than tracking latest.

pscale against a plain mysql client and the PlanetScale web console

The obvious alternative for query work is the mysql client itself. The difference is what each one knows about. A mysql client connects to a server and speaks the wire protocol; it has no concept of a branch or a deploy request. pscale operates one layer up, on platform objects, and reaches for a MySQL client when a command needs an actual connection. That is why the README tells you to install both, and why the Docker image ships both.

The other alternative is the PlanetScale web console. The README's own framing, "brings branches, deploy requests, and other PlanetScale concepts to your fingertips", describes the console's feature set moved into a terminal. The practical difference is automation: a console action is a human clicking, while the GitHub Actions example shows a deploy request being listed inside a CI job with a service token. If your workflow never leaves a browser, the CLI adds a second place to do the same work. If you need the same operation to run unattended, the CLI is the only one of the two that fits.

There is a third path for teams that want a local database instead of a hosted one. That is a different product decision, not a pscale configuration, and the README does not present pscale as a way to get there.

Licence, upgrade cost and what the repository does not say

The project is Apache-2.0. That is a permissive licence with an explicit patent grant and a requirement to preserve notices, which matters if you redistribute the binary inside your own product. It does not grant rights to the PlanetScale service itself; the licence covers the CLI source, and using the CLI still means holding a PlanetScale account under PlanetScale's own terms. Nothing here is legal advice, and the LICENSE file in the repository is the authority.

Upgrade cost is low on paper and uneven in practice. Homebrew, scoop and bin each have a one-line upgrade path, and the README lists all three. The container path needs a fresh pull unless you pin a tag. The real cost is the version churn: with releases arriving days apart, a team that pins a version will periodically need to re-verify the commands it depends on. The README does not document a deprecation policy for flags or output formats, so the only way to know whether an upgrade is safe is to read the release notes for the versions you skip.

Several things a reader would reasonably want are absent. The README does not document authentication or a login flow, does not list the full command set, does not say which commands require the MySQL 8 client, and does not describe rollback behaviour for deploy requests. The documentation link it gives is planetscale.com/docs/reference/planetscale-cli, and that page, not the README, is where those answers would live. Treat the README as an install guide and a CI example, not as a command reference.

Editorial conclusion

Adopt pscale if your team already runs PlanetScale and wants branches, deploy requests and connection strings driven from a shell or a GitHub Actions step, since the README ships a setup-pscale-action example for exactly that. Do not adopt it if you run MySQL elsewhere: every command is a call against the hosted PlanetScale API, and the repository states the API client is vendored at internal/planetscale with no dependency on planetscale-go, so there is no offline mode to fall back on. Before rolling it out, verify that a MySQL 8 client is on the PATH of every machine that will run commands needing it, and confirm that PLANETSCALE_SERVICE_TOKEN_ID and PLANETSCALE_SERVICE_TOKEN are available to your CI job rather than only to an interactive login.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes