Using Polter with Ops
Polter is the recommended workflow manager for Ops Supabase operations. Use it for setup, link, migrations, configuration, and packaged app installation.
Polter exists because Ops needs repeatable Supabase workflows that are easier to discover, less error-prone, and more explicit than keeping those responsibilities inside the app CLI.
The result is a clean split: Ops owns local development startup, while Polter owns setup, project linking, migrations, runtime configuration, and installation workflows.
Why Ops uses Polter
A self-hosted desktop app needs more than a generic dev command. Operators need project-aware setup, controlled migration workflows, and a way to prepare packaged apps with a runtime backend connection. Polter is the workflow layer that standardizes those jobs.
This separation also keeps the Ops CLI intentionally small, which is useful for maintainability and clearer documentation.
Polter references
Polter on npm
Package and installation reference for the recommended Ops workflow manager.
Polter on GitHub
Source repository for Polter, including workflow and command details.
Major commands
| Command | Description |
|---|---|
npx polter app setup ops --path . | Full source-checkout bootstrap. Recommended when cloning or refreshing a local repository. |
npx polter app link ops --path . | Link or relink the checkout to the intended Supabase project. |
npx polter app migrate ops push --path . | Push pending migrations to the linked Supabase project. |
npx polter app migrate ops lint --path . | Check migrations for lint issues before applying them. |
npx polter app migrate ops reset --path . | Destructively reset the linked remote database and reapply migrations. |
npx polter app migrate ops local-reset --path . | Destructively reset the local Docker-based Supabase database. |
npx polter app configure ops --path . | Refresh .env.local and runtime bootstrap material without reinstalling the app. |
npx @polterware/polter@latest app install ops | Install the packaged macOS app from GitHub Releases and prepare the runtime Supabase connection payload. Add --version <version> to pin a release. |
npx @polterware/polter@latest app update ops | Update an existing packaged macOS install to a newer release while preserving persisted runtime configuration, local settings, and session data. |
When to use each workflow
Use setup
When you have a fresh checkout or want Polter to drive the full Ops bootstrap process from dependency validation through runtime payload preparation.
Use link
When the repository should target a different Supabase project or when the link needs to be repaired.
Use migrate
When the project is already linked and you need to push, lint, reset, or local-reset migrations.
Use configure
When the backend connection changed and you want to refresh development env values or the runtime payload without reinstalling the app.
Use install
When you are distributing or testing a packaged macOS app and need Polter to install it with the right Supabase connection context.
Use update
When Ops is already installed and you only want to replace the app bundle with a newer release while preserving the current runtime/app state.
Do not treat old Ops commands as the current workflow
Historical commands such as pnpm opssetup, pnpm opsdb, and pnpm opscheck are not the current documented path. The current source of truth is the Polter workflow set above plus pnpm ops dev for development startup.
Advanced notes for operators
- Use configure when you need to rotate runtime connection details without reinstalling the packaged app.
- Use update when you want a newer packaged build without re-entering connection details.
- Use link before migration workflows if the repository was moved between Supabase projects.
- Reserve reset for intentional destructive operations and communicate it clearly to stakeholders.
- Treat install as an application distribution workflow, not as a substitute for migration management.