Powergit CLI (powergit)

powergit ships the git-remote-powergit remote helper. Once a powergit::... remote is added, you use normal Git commands (git push, git fetch) and the helper streams data to PowerSync. The powergit CLI itself is only needed for setup (login/profile management) and optional diagnostics like powergit sync.

Quick start (hosted PowerSync)

1. Install the CLI (global install recommended):

   npm install -g @powersync-community/powergit

2. From your Git repo, add a PowerSync remote (Git-first flow):

   git remote add powersync powergit::/<org_slug>/<repo_slug>

   Prefer the convenience wrapper? powergit remote add is equivalent and will update an existing remote if needed.

3. Authenticate once so the daemon can talk to PowerSync (required for pushes/fetches):

   powergit login

4. Use normal Git commands:

   git push powersync main
   git fetch powersync

Install

Grab the published package from npm (replace npm with pnpm or yarn if you prefer another package manager):

npm install -g @powersync-community/powergit

This global install provides:

• powergit
• powergit-daemon
• git-remote-powergit (Git remote helper)

Heads up For git push/git fetch to work with powergit::... remotes, Git must find git-remote-powergit on your PATH (global install, or local install with node_modules/.bin on your PATH). The powergit CLI is optional after that point.

Point a repo at PowerSync

From the root of any Git repository, add the remote with Git:

git remote add powersync powergit::/<org_slug>/<repo_slug>

Prefer the convenience wrapper? This does the same thing and updates the remote if it already exists:

powergit remote add powersync powergit::/<org_slug>/<repo_slug>

You can verify the remote with standard Git tooling:

git remote -v

Why powergit::? Git uses the prefix before :: to pick a remote helper binary named git-remote-<prefix>. We ship git-remote-powergit, so the URL must start with powergit::.

Shorthand remote URLs (profiles)

powergit::/<org>/<repo> uses the default profile (production out of the box). To target another stack, create a profile that bundles both the PowerSync and Supabase endpoints, then reference that profile in the remote URL:

powergit profile set staging \
  --set powersync.url=https://powersync.staging.example.com \
  --set supabase.url=https://staging.supabase.co \
  --set supabase.anonKey=<anon-key>

# Optional (only needed for server-side workflows/tests that require elevated Supabase access):
powergit profile set staging --set supabase.serviceRoleKey=<service-role-key>

git remote add powersync powergit::staging/<org>/<repo>

Supabase config (URL/anon key) and your login session are not part of the remote URL. Keep them in the profile/env (and never put a supabase.serviceRoleKey in a Git remote).

Choose a different remote name

With plain Git, just pick any remote name you like (powersync is the default convention). If you use powergit remote add, set the REMOTE_NAME environment variable or pass --remote to target a custom name:

REMOTE_NAME=staging powergit remote add powersync powergit::/<org_slug>/<repo_slug>

Authenticate once with powergit login

Before running commands that talk to PowerSync (push/fetch or powergit sync), sign in so the daemon can reuse the access token across invocations:

powergit login

powergit login starts a device-code flow. The daemon prints a device code and an Open: URL — open it, sign in with Supabase, and keep the tab open until the CLI reports success. The Supabase session is cached per profile under ~/.powergit/daemon/<profile>/session.json and reused by the daemon.

By default the daemon serves the device-login page locally at http://127.0.0.1:5030/ui/auth.

If you don’t see an Open: URL, set daemon.deviceLoginUrl in your profile or export POWERSYNC_DAEMON_DEVICE_URL (useful when the daemon runs somewhere other than localhost).

If the browser can’t POST back to your local daemon (e.g. net::ERR_BLOCKED_BY_CLIENT), try an incognito window or disable ad blockers/privacy shields for the device login page.

To discard credentials, run powergit logout.

Inspect PowerSync metadata quickly

Once a repository has a PowerSync remote configured you can ask the daemon for the current counts of refs, commits, file changes, and objects that it is tracking for that repo:

powergit sync

Flags

• --remote / -r – pick a non-default remote name (defaults to powersync or REMOTE_NAME env var).

The command ensures the daemon is running (starting it if auto-start is enabled), reuses the cached credentials from powergit login, and makes a lightweight RPC call to the daemon. The daemon responds with counts derived from its PowerSync tables (refs, commits, file_changes, objects), so the CLI no longer creates or maintains its own SQLite database file.

CI / ephemeral usage

When you’re scripting inside CI, install the package so git-remote-powergit is on PATH (global install or add node_modules/.bin to PATH). You can still use npx/pnpm dlx for one-off powergit commands, but Git needs the helper binary available when it runs.

pnpm dlx @powersync-community/powergit remote add powersync powergit::/<org_slug>/<repo_slug>

Local stack (optional)

For local development, Supabase + PowerSync stack setup, and live CLI tests, see docs/supabase.md.

Developing the CLI locally

If you’re contributing to the CLI itself, clone the repository and work from source:

pnpm install
pnpm --filter @powersync-community/powergit run build

Helpful scripts:

• pnpm --filter @powersync-community/powergit run typecheck – static checks via tsc
• pnpm --filter @powersync-community/powergit test – Vitest suite (unit + e2e)
• pnpm --filter @powersync-community/powergit run build – transpile to dist/ and ensure the binary stays executable

Whenever you expand the CLI with new commands, remember to document them here and add coverage under packages/cli/tests/.