Introducing the New PowerSync CLI

Overview

The PowerSync CLI has been completely rewritten and is now also open-source This release, version 0.9.0, adds support for self-hosted PowerSync instances, allows you to store your PowerSync instance configuration in versioned YAML files in your project directory, and resolves long-standing DX pain points in the previous version.

Previous versions of the CLI required specifying your entire instance configuration as command-line flags. Flags don't map well to the full range of config options, which made the reference difficult to document and commands unwieldy as configs grew. The validation loop was also slow — errors only surfaced after running a command. The new CLI stores configuration in YAML files in your project directory. Your IDE validates and autocompletes against the config schema, so you see errors as you type. You edit the files, commit them alongside your code, and deploy with a single command.

Beta: The CLI remains in Beta so we can validate these changes with real usage. We're targeting v1.0 in the near-term, and are not planning any further big structural changes.

What's new

• Project-based configuration files: The CLI is designed to live inside your project, similar to the Supabase CLI. A powersync/ directory in your repository holds your instance configuration and Sync Streams (or legacy Sync Rules), committed and reviewed alongside your app code. Your IDE validates and autocompletes against the config schema, and secrets are referenced via environment variables so credentials never end up in source control.

• Self-hosted support: The CLI now also works with self-hosted PowerSync instances. Commands like powersync validate, powersync status, powersync generate schema, and powersync generate token work against any linked instance.

• Docker support for local development: powersync docker configure and powersync docker start set up and run a local PowerSync environment using Docker Compose — no manual configuration required to get started.

• Sync Streams (or Sync Rules) validation: powersync validate runs validation against your local configuration before you deploy, with clearer error messages when something is misconfigured.

• Config Studio (built-in editor): powersync edit config opens a Monaco-powered web app that edits service.yaml and sync-config.yaml with schema-aware validation, autocomplete, and hover docs — preconfigured for the best DX. The editor shows sync config warnings and errors inline and writes changes back to your project directory.

• Browser-based login: powersync login opens a browser window to generate a personal access token (PAT) and stores it automatically. In CI, set the PS_ADMIN_TOKEN environment variable instead.

• Plugin system: The CLI supports an npm-based plugin system (built on OCLIF). Use powersync plugins to list installed plugins, powersync plugins install <package> to add one, or build your own using @powersync/cli-core.

• IDE configuration: powersync configure ide sets up your IDE for YAML schema validation, autocomplete, and !env custom tag support. For VS Code, powersync init cloud --vscode configures the workspace for the config directory.

• Sync Rules → Sync Streams migration: powersync migrate sync-rules migrates your existing Sync Rules to Sync Streams.

• Open source: The CLI source code is now publicly available.

Getting started

Install globally or use via npx:

npm install -g powersync

# or

npx powersync@0.9.0

Cloud: create a new instance

powersync login
powersync init cloud
# Edit powersync/service.yaml (connection, auth, region) and powersync/sync-config.yaml (Sync Streams)
powersync link cloud --create --project-id=<project-id>
powersync validate
powersync deploy

Cloud: update an existing instance

powersync login
powersync pull instance --project-id=<project-id> --instance-id=<instance-id>
# powersync/ directory is now populated with your current instance config
# Make your changes, then:
powersync validate
powersync deploy

Local development

powersync init self-hosted
powersync docker configure
powersync docker start

See the CLI docs for further instructions covering both Cloud and self-hosted workflows.

Migrating from the previous CLI

The new CLI is not backwards compatible with previous versions. If you're using npx powersync in CI/CD pipelines or scripts without pinning a version, those workflows will break.

If you're not ready to migrate, pin to the previous CLI version:

# Instead of:
npx -y powersync [command]

# Use:
npx -y powersync@0.8.0 [command]

Or in package.json:

{
  "devDependencies": {
    "@powersync": "0.8.0"
  }
}

When you're ready to migrate: install the latest version and run powersync login to get started. The main change is that configuration is no longer passed as command-line arguments — it lives in YAML files in your project directory. Use powersync pull instance to seed a local powersync/ directory from your existing cloud instance, then deploy from there.

For a full mapping of previous commands to new ones, see the CLI migration guide.

Limitations

• powersync deploy applies to PowerSync Cloud instances only. The CLI does not currently push configuration directly to self-hosted instances.

• Some validation checks require a connected instance to complete successfully; validation of an unprovisioned instance may show errors that resolve after the first deployment.

• When secure storage is unavailable, powersync login may store the token in a plaintext config file only after explicit confirmation.

Resources

• CLI documentation: Cloud and self-hosted workflows, command reference, and CI/CD setup

• Setup guide: Getting started with PowerSync, including CLI-based flows for both Cloud and self-hosted

• Example projects: Sample projects initialized with the PowerSync CLI

Feedback and help

This rewrite was driven by community feedback on the previous CLI's pain points. If you're curious about the thinking behind it, the design proposal is publicly available.

Please share feedback or report issues on GitHub or in the PowerSync Discord.