feat: CLI

.envrc

@@ -0,0 +1,3 @@
+layout node
+use node
+[ -f .env ] && dotenv

.gitattributes

@@ -0,0 +1,3 @@
+* text=auto eol=lf
+*.cmd text eol=crlf
+*.bat text eol=crlf

.github/workflows/onPushToMain.yml

@@ -0,0 +1,60 @@
+name: release on push to main
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+      - name: Check if CLI version already exists
+        id: version-check
+        run: |
+          package_version=$(node -p "require('./cli/package.json').version")
+          exists=$(gh api repos/${{ github.repository }}/releases/tags/v$package_version >/dev/null 2>&1 && echo "true" || echo "")
+
+          if [ -n "$exists" ];
+          then
+            echo "Version v$package_version already exists"
+            echo "::warning file=cli/package.json,line=1::Version v$package_version already exists - no release will be created."
+            echo "skipped=true" >> $GITHUB_OUTPUT
+          else
+            echo "Version v$package_version does not exist. Creating release..."
+            echo "skipped=false" >> $GITHUB_OUTPUT
+            echo "tag=v$package_version" >> $GITHUB_OUTPUT
+          fi
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+      - name: Setup git
+        if: ${{ steps.version-check.outputs.skipped == 'false' }}
+        run: |
+          git config --global user.email ${{ secrets.GH_EMAIL }}
+          git config --global user.name ${{ secrets.GH_USERNAME }}
+      - name: Generate OCLIF README (cli)
+        if: ${{ steps.version-check.outputs.skipped == 'false' }}
+        run: |
+          pnpm run build
+          cd cli && pnpm exec oclif readme
+          cd ..
+          if [ -n "$(git status --porcelain)" ]; then
+            git add .
+            git commit -am "chore: update README.md"
+            git push -u origin ${{ github.ref_name }}
+          fi
+      - name: Create GitHub Release
+        uses: ncipollo/release-action@2c591bcc8ecdcd2db72b97d6147f871fcd833ba5
+        if: ${{ steps.version-check.outputs.skipped == 'false' }}
+        with:
+          name: ${{ steps.version-check.outputs.tag }}
+          tag: ${{ steps.version-check.outputs.tag }}
+          commit: ${{ github.ref_name }}
+          token: ${{ secrets.GH_TOKEN }}
+          skipIfReleaseExists: true

.github/workflows/onRelease.yml

@@ -0,0 +1,22 @@
+name: publish on release
+
+on:
+  release:
+    types: [released]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run build
+      # - name: Publish @powersync/cli to npm
+      #   run: pnpm publish -- --no-git-checks --access public
+      #   env:
+      #     NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/test.yml

@@ -0,0 +1,26 @@
+name: tests
+
+on:
+  push:
+    branches-ignore: [main]
+
+jobs:
+  unit-tests:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        node_version: [24]
+      fail-fast: false
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+      - name: Check formatting
+        run: pnpm exec prettier --check .
+      - run: pnpm run build
+      - run: pnpm run test

.gitignore

@@ -137,3 +137,12 @@ dist
 # Vite logs files
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
+
+# Playground for testing cli commands
+playground/
+
+# PNPM
+.pnpm-store/
+
+# MacOS
+.DS_Store

.husky/pre-commit

@@ -0,0 +1,17 @@
+#!/bin/sh
+set -e
+
+if git diff --cached --quiet --diff-filter=ACMR; then
+	exit 0
+fi
+
+git diff --cached --name-only -z --diff-filter=ACMR \
+	| xargs -0 pnpm prettier --write --ignore-unknown
+
+if git diff --cached --name-only --diff-filter=ACMR -- '*.js' '*.cjs' '*.mjs' '*.ts' '*.tsx' | grep -q .; then
+	git diff --cached --name-only -z --diff-filter=ACMR -- '*.js' '*.cjs' '*.mjs' '*.ts' '*.tsx' \
+		| xargs -0 pnpm eslint --fix
+fi
+
+git diff --cached --name-only -z --diff-filter=ACMR \
+	| xargs -0 git add --

.nvmrc

@@ -0,0 +1 @@
+24

.prettierignore

@@ -0,0 +1,3 @@
+pnpm-lock.yaml
+**/pnpm-lock.yaml
+**/*.json

.prettierrc.json

@@ -0,0 +1,10 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "bracketSameLine": true,
+  "useTabs": false,
+  "endOfLine": "lf",
+  "printWidth": 120,
+  "trailingComma": "none"
+}

AGENTS.md

@@ -0,0 +1,22 @@
+# Agent Guidelines
+
+## Environment Variables
+
+- Do not read `process.env` directly in application code.
+- Use typed env helpers (for example, `env` from `@powersync/cli-core`) so environment access is centralized and testable.
+- Keep environment resolution logic in one place; command and service code should consume resolved values.
+
+## Testing Environment Behavior
+
+- Prefer mocking env helpers/modules in tests instead of relying on direct `process.env` reads in production code.
+- Tests may set temporary env values when needed, but should primarily validate behavior through mocked env access points.
+- Reset env-related mocks/state between tests to avoid leakage.
+
+## File Naming Conventions
+
+- Choose the filename based on the file's primary responsibility so agents can infer intent without opening the file.
+- If the main export is a class or a type/interface, the filename must exactly match that export name (for example, `ServiceCloudConfig.ts`, `AccountsHubClientSDKClient.ts`).
+- Use this class/type naming rule even if the file also contains small helper functions; the primary exported symbol takes precedence.
+- If the file's purpose is utility logic (single function or a group of helper methods), use action-style kebab-case names in the form `do-this-action.ts` (for example, `ensure-service-type.ts`, `resolve-config-path.ts`).
+- Utility filenames should describe what the code does, not what it is. Prefer verb-led names such as `load-*`, `parse-*`, `validate-*`, `write-*`, `ensure-*`.
+- Avoid generic utility names like `helpers.ts`, `utils.ts`, or `common.ts` unless the file is intentionally a broad shared entry point.

README.md

@@ -0,0 +1,84 @@
+# PowerSync CLI
+
+Monorepo for the PowerSync CLI and related tooling. Built with [pnpm](https://pnpm.io) workspaces and [OCLIF](https://oclif.io).
+
+## Requirements
+
+- **Node**: LTS v24+ (see [.nvmrc](./.nvmrc); use `nvm use` to switch)
+- **Package manager**: pnpm
+
+## Monorepo structure
+
+The workspace is split into the main CLI, shared **packages**, and optional **plugins**:
+
+| Package                                              | Path                 | Description                                                                        |
+| ---------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------- |
+| [**@powersync/cli**](./cli)                          | `cli/`               | Main CLI — manage instances, config, sync config, cloud and self-hosted            |
+| [**@powersync/cli-core**](./packages/cli-core)       | `packages/cli-core/` | Core types and base commands shared by the CLI and plugins                         |
+| [**@powersync/cli-schemas**](./packages/schemas)     | `packages/schemas/`  | Shared config schemas (cli.yaml, service.yaml, etc.)                               |
+| [**@powersync/cli-plugin-docker**](./plugins/docker) | `plugins/docker/`    | Docker plugin — self-hosted PowerSync with Compose (configure, reset, start, stop) |
+
+```
+├── cli/                    # @powersync/cli — main CLI (commands, cloud/self-hosted, templates)
+├── packages/
+│   ├── cli-core/           # @powersync/cli-core — base commands & YAML utils (used by CLI + plugins)
+│   └── schemas/            # @powersync/cli-schemas — config validation (LinkConfig, CLIConfig)
+├── plugins/
+│   └── docker/             # @powersync/cli-plugin-docker — docker configure, reset, start, stop
+├── examples/               # Sample projects initialized with the CLI (see examples/README.md)
+│   ├── cloud/
+│   └── self-hosted/
+└── docs/
+    ├── usage.md            # General CLI usage (Cloud, self-hosted, linking, auth)
+    └── usage-docker.md     # Docker plugin (configure, reset, start, stop, templates)
+```
+
+- **cli** depends on **cli-core**, **cli-schemas**, and **@powersync/cli-plugin-docker**. It loads the docker plugin and re-exports base command types from cli-core.
+- **plugin-docker** (in **plugins/docker**) depends on **cli-core** and **cli-schemas**. No dependency on the CLI package.
+- **cli-core** depends on **schemas**. It provides `SelfHostedInstanceCommand`, YAML helpers (`!env`), and shared types for plugins.
+
+Workspace roots are listed in [pnpm-workspace.yaml](./pnpm-workspace.yaml): `cli`, `packages/*`, `plugins/*`.
+
+## OCLIF plugins
+
+We rely on standard [OCLIF plugin loading](https://oclif.io/docs/plugins/) so plugins can register new commands or hook into command execution. The main CLI ships with a Docker plugin under [plugins/docker](./plugins/docker), and any other OCLIF-compatible plugin can be installed the same way.
+
+For PowerSync-specific plugins, the optional [@powersync/cli-core](./packages/cli-core) package exposes base command helpers and shared types. The Docker plugin consumes these helpers and adds Docker-focused commands as a reference implementation.
+
+Users can manage their own installed plugins dynamically at runtime. Run `powersync plugins --help` for install, uninstall, and inspection options.
+
+## Getting started
+
+```bash
+nvm use          # use Node from .nvmrc (optional)
+pnpm install
+pnpm build
+```
+
+Run the CLI from the repo root:
+
+```bash
+powersync --help
+```
+
+### Self-hosted with Docker
+
+From the repo root, create the Docker layout and run the stack:
+
+```bash
+powersync docker configure
+powersync docker start
+```
+
+See [plugins/docker](./plugins/docker/README.md) and [docs/usage-docker.md](./docs/usage-docker.md) for details.
+
+## Examples
+
+The [**examples/**](./examples) folder contains basic projects initialized with the CLI. See [examples/README.md](./examples/README.md) for the full list and links to each example's README.
+
+## Documentation
+
+- [**Usage**](./docs/usage.md) — How the CLI works: Cloud and self-hosted, linking, auth, supplying instance info
+- [**Usage (Docker)**](./docs/usage-docker.md) — Docker plugin: configure, reset, start, stop, templates, flags
+- [**CLI documentation conventions**](./docs/cli-documentation-conventions.md) — How we document commands (description, summary, examples, flags, topics)
+- [CLI package README](./cli/README.md) — Install, usage, and command reference

cli/.gitignore

@@ -0,0 +1,5 @@
+/dist
+/tmp
+oclif.manifest.json
+
+

cli/.prettierrc.json

@@ -0,0 +1 @@
+"../.prettierrc.json"