feat: CLI

[stevensJourney]

Implementation of https://docs.google.com/document/d/1iqpJF2gog2jB-ZWeN8TBEjcad8aBKNKbue2yJ21q_-s/edit?tab=t.0#heading=h.tlu0tywj9wmg

Summary

This PR introduces a new PowerSync CLI monorepo for managing PowerSync instances (Cloud and self-hosted). The CLI provides project scaffolding, linking, deployment, config management, validation, and client artifact generation, with an optional Docker plugin for running a local self-hosted PowerSync stack via Docker Compose - primarily for local development.

---

What’s in scope

Monorepo layout

• cli/ — Main CLI (@powersync/cli): OCLIF-based entrypoint, commands, Cloud/self-hosted API clients, and YAML templates (cloud + self-hosted).
• packages/cli-core/ — Shared base command types, YAML helpers (including !env), and project-config utilities used by the CLI and plugins.
• packages/schemas/ — Shared config schemas for validation and typing.
• plugins/docker/ — Docker plugin (@powersync/cli-plugin-docker): configure, reset, start, stop for a Compose-based self-hosted stack.

Workspace roots: cli, packages/*, plugins/* (pnpm).

Main CLI capabilities

Area	Commands	Notes
Project setup	init cloud, init self-hosted, link (cloud / self-hosted)	Scaffold powersync/ from a template with init cloud or init self-hosted; bind to an instance via link.yaml.
Cloud lifecycle	deploy, stop, destroy	Deploy sync rules/config, stop instance, destroy instance (Cloud only).
Config & sync rules	fetch config, pull config, fetch instances, fetch status	Get instance config (YAML/JSON), list instances, pull config into local files, show diagnostics (Cloud and/or self-hosted where applicable).
Validation	validate	Validate config schema, connections, and sync rules (Cloud and self-hosted).
Client artifacts	generate schema, generate token	Generate client schema (multiple targets) and dev JWT (Cloud and self-hosted).
Auth	login	Store PowerSync token in secure storage; PS_TOKEN supported for CI/scripts.

Not all commands require a PowerSync config folder: commands that don’t need local config (e.g. fetch status, generate schema, generate token) can be run with instance specified by flags (and/or env) only, without a powersync/ directory or link.yaml. Where a config directory is used, --directory (default powersync/) applies.

Docker plugin (self-hosted)

• docker configure — Composes database and storage modules (e.g. postgres / external) into powersync/docker/, generates docker-compose.yaml and .env, merges replication/storage into service.yaml, and sets link.yaml (including plugins.docker.project_name). If --database or --storage are omitted, the CLI prompts interactively (Inquirer); use none to skip configuring a module.
• docker reset — Stop and remove containers (docker compose down), then start (docker compose up -d --wait); use for a clean bring-up (e.g. after config changes).
• docker start / docker stop — Start stack or stop by project name; stop supports --remove and --remove-volumes. After a failed start/reset, the CLI lists only running PowerSync Docker projects (from docker compose ls -q) so you can stop the right one.

Templates support postgres and external options for source database and bucket storage.

Config and conventions

• Config directory — Default powersync/; holds service.yaml, sync.yaml, link.yaml, and (with Docker plugin) docker/.
• Linking — link.yaml stores Cloud IDs or self-hosted api_url (and optional api_key); supports !env for env-based values.
• YAML — Custom !env tag for substituting env vars (with optional ::number / ::boolean cast); used in link and service config.

Quality and CI

• Tests — Unit tests for CLI commands (Vitest) in cli/test/.
• CI — GitHub Actions: format check (Prettier), build, and test on push (excluding main); matrix: Node 24, Ubuntu + Windows.
• Docs — docs/usage.md (general usage, linking, auth, Cloud vs self-hosted), docs/usage-docker.md (Docker plugin workflow and flags), plus READMEs in repo root, cli/, and plugins/docker/.

---

Todos

These will be done in future PRs

• Distribution, changesets, packaging and publishing.
• Update YAML schema after packages are deployed
• Refactor powersync help command list
• Automatic update checking

---

How to run

nvm use          # Node from .nvmrc (e.g. 24)
pnpm install
pnpm build
pnpm powersync -- --help

Docker self-hosted flow:

# Interactive: prompts for database and storage (or use --database/--storage; use "none" to skip one)
pnpm powersync docker configure
# Or non-interactive:
pnpm powersync docker configure --database postgres --storage postgres
pnpm powersync docker start

See README.md, docs/usage.md, and docs/usage-docker.md for full usage.

[Copilot]

Pull request overview

Copilot reviewed 182 out of 193 changed files in this pull request and generated 8 comments.

Files not reviewed (1)

• examples/self-hosted/local-postgres-node/pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Chriztiaan]

Awesome work! A welcome iteration.

[stevensJourney]

Due to the size of this PR. I'd like to merge it now, and address any additional feedback as additional PRs.
Feedback is still welcome.