CLI

PowerSync CLI on NPM

Install globally or run via npx

Source Code

PowerSync CLI repo on GitHub

Changelog

Changelog for the CLI

The PowerSync CLI lets you manage PowerSync Service instances, deploy sync config (your Sync Streams or Sync Rules), generate client schemas, run diagnostics, and more. It is distributed as the powersync npm package.

The CLI is currently in beta. We recommend it for new and existing projects.

For a full step-by-step flow using the CLI, use the Setup Guide: choose the CLI (Cloud) or CLI (Self-Hosted) tab in steps 2–5 to configure your instance, connect the source database, deploy sync config, and generate development tokens.

The CLI was overhauled in version 0.9.0. The redesign is based on this design proposal.

What changed in 0.9.0?

Main improvements:

Project-based config — A powersync/ directory in your repo holds service.yaml and sync-config.yaml, so you version and review config with your app code.
Self-hosted support — Most commands work against any linked instance, PowerSyncCloud and self-hosted. You can also use powersync docker configure to scaffold a local PowerSync stack with no manual setup.
Better validation — powersync validate checks your config before deploy and reports errors with line and column numbers.
Config Studio — powersync edit config opens a built-in editor with schema validation, autocomplete, inline errors, and more. See the Config Studio README.
Browser login — powersync login opens a browser to create or paste a PAT and stores it; in CI use PS_ADMIN_TOKEN.
Plugins — npm-based plugin system (OCLIF); install with powersync plugins install <package> or build with @powersync/cli-core.
Open source — Source and advanced docs are in the PowerSync CLI repo. See Migrating From the Previous CLI if you used the older flow.

Installation

Install globally or run via npx:

npm install -g powersync

npx powersync@0.9.0  # 0.9.0 is the first version with the new CLI

Authentication (Cloud)

Cloud commands require a PowerSync personal access token (PAT). Interactive login (recommended for local use):

powersync login

You can open a browser to create a token in the PowerSync Dashboard or paste an existing token. The CLI stores the token in secure storage when available (e.g. macOS Keychain), or in a config file after confirmation. CI and scripts: Set the PS_ADMIN_TOKEN environment variable. The CLI uses PS_ADMIN_TOKEN when set; otherwise it uses the token from powersync login.

export PS_ADMIN_TOKEN=your-personal-access-token
powersync fetch instances --project-id=<project-id>

To clear stored credentials: powersync logout.

Config Files

The CLI uses a config directory (default powersync/) with YAML files:

File	Purpose
`service.yaml`	Instance configuration: name, region, replication connection, client auth
`sync-config.yaml`	Sync Streams (or Sync Rules)
`cli.yaml`	Link file (written by `powersync link`); ties this directory to an instance

Developer Notes

Use the !env tag for secrets, e.g. uri: !env PS_DATABASE_URI (or !env VAR::number / !env VAR::boolean for types).
Edit files in your IDE, then run powersync validate and powersync deploy. For schema validation and !env support in your editor, run powersync configure ide; or run powersync edit config to open Config Studio (built-in web-based editor).
To run commands against several instances from one config directory, define named targets in cli.yaml. See Named Targets. The CLI usage docs cover other layouts, such as one directory per instance.
For Cloud secrets in service.yaml, use password: secret: !env VAR to supply the value from an environment variable at deploy time; after the first deploy you can switch to secret_ref: default_password to reuse the stored secret. Details
cli.yaml records the instance ID along with the organization and project IDs. The organization and project IDs act as a cache: when both are present, the CLI uses them directly instead of looking them up from the instance, saving an API request. If they are missing, the CLI resolves them automatically from the instance ID. If they are present but incorrect for the instance, the CLI reports an error rather than overriding them.

Cloud Workflows

You can create instances, deploy and pull config, run all Cloud commands.

Create a New Instance

powersync login
powersync init cloud

Edit config

Edit powersync/service.yaml (name, region, replication, auth) and sync config; use !env for secrets.

Create and link

powersync link cloud --create --project-id=<project-id>

Add --org-id=<org-id> if your token has multiple orgs.

Deploy

powersync validate
powersync deploy

Use --directory=<path> for a different config folder.

Use an Existing Instance (Pull)

Pull config from an instance that already exists (e.g. created in the Dashboard):

powersync login
powersync pull instance --instance-id=<instance-id>

Then edit service.yaml and sync-config.yaml as needed, run powersync validate, and powersync deploy. Run powersync pull instance again (no IDs if already linked) to refresh from the cloud.

Preview a Deploy

Add --dry-run to powersync deploy, powersync deploy service-config, or powersync deploy sync-config to see what a deploy would do without changing the instance:

powersync deploy --dry-run

The command prints the target instance, runs the same validations as a real deploy, and then summarizes what would change: the service.yaml sections that differ from the deployed config, and a diff of the sync config. Nothing is deployed, even when the instance is not provisioned yet. The service config summary lists section names only, because service.yaml holds connection strings and other secrets. To compare the full file, run powersync pull instance without --overwrite. It writes the deployed config to service-fetched.yaml next to your service.yaml, so you can diff the two files locally.

Connections that pass a password with secret always show replication as changed, because the value is sent again on every deploy.

Run Commands Without Local Config

To run commands (e.g. powersync generate schema, powersync status) against an instance managed elsewhere (e.g. Dashboard):

Link once: powersync link cloud --instance-id=<id> (writes cli.yaml); later commands use that instance.
Or pass each time: --instance-id, or set INSTANCE_ID in the environment.

The CLI resolves the instance in a fixed order: flags first, then cli.yaml (the selected target, then the top-level fields), then environment variables. For details, see supplying linking information for Cloud and self-hosted commands in the CLI usage docs.

Named Targets

Named targets let one config directory point at more than one Cloud instance, such as staging and production. Each target is an entry under targets in cli.yaml with its own instance, organization, and project IDs. The top-level fields stay the default when you do not select a target. Link an existing instance under a target name, or create a new instance and link it under one:

powersync link cloud --target=staging --instance-id=<instance-id>
powersync link cloud --create --target=staging --project-id=<project-id>

The resulting cli.yaml:

type: cloud
instance_id: <production-instance-id>
org_id: <org-id>
project_id: <project-id>
targets:
  staging:
    instance_id: <staging-instance-id>
    org_id: <org-id>
    project_id: <project-id>

Select a target with --target on a command, or set POWERSYNC_TARGET for scripts and CI:

powersync pull instance --target=staging
powersync deploy --target=staging
powersync status --target=staging
POWERSYNC_TARGET=staging powersync deploy sync-config

--instance-id takes precedence over POWERSYNC_TARGET. You cannot combine --target with --instance-id in one command. powersync fetch instances lists the targets of each linked directory. Before deploy, stop, destroy, and compact change anything, the CLI prints the instance name and IDs, plus the target name when one is selected.

Deploy writes the name from service.yaml to the instance it targets. Instances deployed from one service.yaml end up with the same name in the Dashboard, so tell them apart by target name or instance ID rather than by instance name.

Self-Hosted Workflows

Support is limited: you link to an existing PowerSync API and run a subset of commands. The CLI does not create, deploy to, or pull config from your server; you manage the server and its config yourself. For local development, use Docker to run a PowerSync Service (and optional DB/storage) in containers.

Authenticate

On the server

In your PowerSync instance config, define API tokens in service.yaml:

api:
  tokens:
    - dev-token-do-not-use-in-production   # or !env MY_API_TOKEN

Link the CLI

powersync link self-hosted --api-url <url>

Writes cli.yaml with the API URL.

Set the API key

In cli.yaml set api_key: !env PS_ADMIN_TOKEN (or a literal value matching a server token), or set the PS_ADMIN_TOKEN environment variable. If both are set, the environment variable takes precedence.

# powersync/cli.yaml (self-hosted)
type: self-hosted
api_url: https://powersync.example.com
api_key: !env PS_ADMIN_TOKEN   # or a literal value matching one of the tokens in service.yaml

Scaffold and Link (No Docker)

When you already have a running PowerSync API:

powersync init self-hosted
# Edit powersync/service.yaml with instance details and api.tokens
powersync link self-hosted --api-url https://powersync.example.com
powersync status

Use --directory=<path> for a different config folder.

Supported Commands (Self-Hosted)

Only these commands apply to self-hosted instances: powersync status, powersync generate schema, powersync generate token, powersync validate, powersync fetch instances (scans current directory for folders with cli.yaml). Cloud-only commands (powersync deploy, powersync pull instance, powersync fetch config, powersync destroy, powersync stop, powersync compact) do not apply.

Docker (Local Development)

Run a PowerSync Service (and optional DB/storage) in containers on your machine—no remote server.

powersync init self-hosted
powersync docker configure    # links to the local API automatically
powersync docker start

Then use the same commands as any self-hosted instance (powersync status, powersync generate schema, etc.). To stop: powersync docker stop (add --remove to remove containers, --remove-volumes to reset so init scripts run again). For a clean setup: powersync docker reset (stop and remove, then start).

For the full Docker workflow, all flags (--database, --storage, --remove, --remove-volumes), and how the template layout and init scripts work, see Docker usage in the CLI repo. Run powersync docker --help for command options.

Common Commands

Command	Description
`powersync login`	Store PAT for Cloud (interactive or paste token); use `PS_ADMIN_TOKEN` in CI
`powersync logout`	Remove stored token
`powersync init cloud`	Scaffold Cloud config directory
`powersync init self-hosted`	Scaffold self-hosted config directory
`powersync configure ide`	IDE: YAML schema validation and `!env` support
`powersync link cloud --instance-id=<id>`	Link to existing Cloud instance
`powersync link cloud --create --project-id=<id>`	Create new Cloud instance and link
`powersync link cloud --target=<name> --instance-id=<id>`	Link an instance as a named target in `cli.yaml`
`powersync link self-hosted --api-url=<url>`	Link to self-hosted instance
`powersync pull instance --instance-id=<id>`	Download Cloud config to local files
`powersync deploy`	Deploy full config to linked Cloud instance
`powersync deploy service-config`	[Cloud] Deploy only service config
`powersync deploy sync-config`	[Cloud] Deploy only sync config
`powersync deploy --dry-run`	[Cloud] Validate and preview what a deploy would change, without deploying
`powersync deploy --target=<name>`	[Cloud] Deploy to a named target. `--target` works on every instance command
`powersync validate`	Validate config and Sync Streams/Rules
`powersync edit config`	Open Config Studio (Monaco editor)
`powersync status`	Instance diagnostics (Cloud and self-hosted)
`powersync generate schema --output=ts --output-path=schema.ts`	Generate client schema
`powersync generate token --subject=user-123`	Generate development JWT
`powersync fetch instances`	List Cloud and linked instances
`powersync fetch config`	[Cloud] Print instance config (YAML/JSON)
`powersync migrate sync-rules`	Migrate Sync Rules to Sync Streams
`powersync destroy --confirm=yes`	[Cloud] Permanently destroy instance
`powersync stop --confirm=yes`	[Cloud] Stop instance (restart with deploy)
`powersync compact`	[Cloud] Trigger bucket compacting on demand

Run powersync --help or powersync <command> --help for flags. Full command reference in the CLI repo.

Deploying From CI (e.g. GitHub Actions)

You can automate sync config (and full config) deployments using the CLI in CI. Use the config directory as the source of truth: keep service.yaml and sync-config.yaml in the repo (with secrets via !env and CI secrets), then run powersync deploy (or powersync deploy sync-config). Secrets: Set PS_ADMIN_TOKEN to your PowerSync personal access token. If the workflow does not use a linked directory, also set INSTANCE_ID. If the linked directory defines targets, set POWERSYNC_TARGET to pick one. For self-hosted, API_URL can specify the PowerSync API base URL. The CLI prints the target instance name and IDs before a deploy starts, so the job log shows which instance changed. For pull request checks, run powersync deploy --dry-run to validate the config and preview the changes without deploying.

GitHub Actions Demo

Example: deploy sync config on push to main

Migrating From the Previous CLI

If you used the older PowerSync CLI (e.g. npx powersync init to set token and org/project, then powersync instance set, powersync instance deploy, etc.), the new CLI uses a different flow. Version 0.9.0 and above are not backwards compatible with 0.8.0. If you are not ready to migrate, you can stay on the old CLI:

npm install -g @powersync/cli@0.8.0

Otherwise, upgrade to the latest powersync npm package and follow the mapping below.

Previous CLI	New CLI
`npx powersync init` (enter token, org, project)	`powersync login` (token only). Then `powersync init cloud` to scaffold config, or `powersync pull instance --instance-id=...` to pull an existing instance.
`powersync instance set --instanceId=<id>`	`powersync link cloud --instance-id=<id>` (writes `cli.yaml` in config directory). Or use `--directory` for a specific folder, or `--target=<name>` to keep several instances in one directory.
`powersync instance deploy` (interactive or long flag list)	Edit `powersync/service.yaml` and `powersync/sync-config.yaml`, then `powersync deploy`. Config is in files, not command args.
`powersync instance config`	`powersync fetch config` (output as YAML or JSON with `--output`).
Deploy only Sync Streams/Rules	`powersync deploy sync-config`.
`powersync instance schema`	`powersync generate schema --output=... --output-path=...` (and/or `powersync status` for diagnostics).
Org/project stored by init	Not required separately. The CLI determines the organization and project from the instance ID and caches their IDs in `cli.yaml`. For CI, set `PS_ADMIN_TOKEN` and `INSTANCE_ID`.

Summary: Authenticate with powersync login (or PS_ADMIN_TOKEN in CI). Use a config directory with service.yaml and sync-config.yaml as the source of truth. Link with powersync link cloud or powersync pull instance, then run powersync deploy or powersync deploy sync-config. No more setting “current instance” separately from config—the directory and cli.yaml define the target.

Additional Documentation (CLI Repository)

More information is available in the PowerSync CLI repository.

Resource	Description
CLI README	Getting started, Cloud and self-hosted overview, and full command reference with all flags.
General usage	How the CLI works: local config vs linking, resolution order (flags → `cli.yaml` → env vars), and configuring multiple instances (named targets in `cli.yaml`, separate directories, or `!env`).
Docker (local development)	Self-hosted Docker workflow, configure/start/stop/reset, database and storage modules, and template layout.
Config Studio (editor)	Built-in Monaco-powered editor for `service.yaml` and `sync-config.yaml` (`powersync edit config`), schema validation, and local development.
Examples	Sample projects initialized with the CLI (e.g. Cloud pull, self-hosted Postgres, self-hosted Supabase).

Known Issues and Limitations

When secure storage is unavailable, powersync login may store the token in a plaintext config file after explicit confirmation.
Self-hosted: the CLI does not create or manage instances on your server, or deploy config to it; it only links to an existing API and runs a subset of commands (status, generate schema/token, validate). The sole exception is Docker: it starts a local PowerSync Service (and optional DB/storage) in containers on your machine for development — not a remote or production instance.
Some validation checks require a connected instance to complete successfully; validation of an unprovisioned instance may show errors that resolve after the first deployment.

Reference

npm: powersync

Package and version history

Manage your access tokens

Create or revoke tokens in the PowerSync Dashboard

PowerSync CLI Repo

Source code, usage docs, Docker usage, and examples

Get Started

Configuration Details

Sync Streams & Rules

Client SDKs

Handling Writes

Maintenance & Ops

Integrations

Tools

Resources

PowerSync CLI on NPM

Source Code

Changelog

Installation

Authentication (Cloud)

Config Files

Developer Notes

Cloud Workflows

Create a New Instance

Use an Existing Instance (Pull)

Preview a Deploy

Run Commands Without Local Config

Named Targets

Self-Hosted Workflows

Authenticate

Scaffold and Link (No Docker)

Supported Commands (Self-Hosted)

Docker (Local Development)

Common Commands

Deploying From CI (e.g. GitHub Actions)

GitHub Actions Demo

Migrating From the Previous CLI

Additional Documentation (CLI Repository)

Known Issues and Limitations

Reference

npm: powersync

Manage your access tokens

PowerSync CLI Repo

PowerSync CLI on NPM

Source Code

Changelog

​Installation

​Authentication (Cloud)

​Config Files

​Developer Notes

​Cloud Workflows

​Create a New Instance

​Use an Existing Instance (Pull)

​Preview a Deploy

​Run Commands Without Local Config

​Named Targets

​Self-Hosted Workflows

​Authenticate

​Scaffold and Link (No Docker)

​Supported Commands (Self-Hosted)

​Docker (Local Development)

​Common Commands

​Deploying From CI (e.g. GitHub Actions)

GitHub Actions Demo

​Migrating From the Previous CLI

​Additional Documentation (CLI Repository)

​Known Issues and Limitations

​Reference

npm: powersync

Manage your access tokens

PowerSync CLI Repo

Installation

Authentication (Cloud)

Config Files

Developer Notes

Cloud Workflows

Create a New Instance

Use an Existing Instance (Pull)

Preview a Deploy

Run Commands Without Local Config

Named Targets

Self-Hosted Workflows

Authenticate

Scaffold and Link (No Docker)

Supported Commands (Self-Hosted)

Docker (Local Development)

Common Commands

Deploying From CI (e.g. GitHub Actions)

Migrating From the Previous CLI

Additional Documentation (CLI Repository)

Known Issues and Limitations

Reference