<pectus.ai/>
./pectus.ai — builder framework · self-hosted · MIT

For end users

Upgrading Pectus

Pectus is fork-and-pull. You cloned pectusai/pectus to your machine. To get updates, you pull the latest from upstream and then apply any pending DB migrations from inside the CMS.

The flow

git pull
npm install                       # in case dependencies changed
npm run dev
# then open /settings/updates in the CMS and apply any pending migrations

npx pectus update is a convenience wrapper that does the git pull + npm install part. Schema migrations apply through the in-CMS overlay at /settings/updates, not the CLI. The overlay lists every migration file in connectors/supabase/migrations/, marks which have already been applied (via the _pectus_migrations ledger), and offers an Apply button per migration. If you have SUPABASE_ACCESS_TOKEN in .env.local, Pectus calls the Supabase Management API on your behalf; otherwise it shows the SQL with a copy button so you can paste into Supabase’s SQL editor.

What updates will never touch

These are yours. Upstream only ships into upstream-managed paths.

  • brands/<slug>/ — your brand profile, imported design bundles, knowledge files, example photos
  • .env.local — your secrets
  • Any skill or app you authored locally

Handling conflicts

If you’ve edited an upstream-managed file (anything inside apps/, skills/, cms/src/, cli/src/, connectors/), git rebase will surface a conflict because both you and upstream changed the same file.

Don’t resolve it by keeping your changes. That sends you on the path to drifting permanently from upstream and missing every future update. Your fork becomes a dead end.

Instead:

  1. Discard your local edits to that file: git checkout upstream/main -- path/to/file.
  2. If your edits were genuinely valuable, draft them as a PR to pectusai/pectus so they land upstream. Everyone benefits, your work survives every future update.

Configuration files are the one exception. If apps/content-insights/pectus.config.ts (or similar) conflicts because both you and upstream changed it, hand-merge that one — it’s a config you’re meant to customize.

Migrations

The current set of migration files: 0001_pectus_v04.sql (squashed v0.4 baseline), 0002_content_insights.sql, 0003_project_files.sql, 0004_brand_font_sizes.sql. They’re numbered and applied in order via the overlay at /settings/updates.

First-time installs paste the baseline (0001_pectus_v04.sql) once in the Supabase SQL editor; everything after that applies via the in-CMS overlay. Existing installs already past v0.4.2 just open /settings/updates after each git pull and tap Apply on any pending rows.

Migrations are forward-only and idempotent. Re-running a migration that’s already been applied is a safe no-op — the overlay shows it as Applied and won’t re-run it.

If a migration fails (rare — usually a permissions issue, a missing extension, or a network blip), the overlay surfaces the error inline with the raw response body. Fix the underlying cause and re-run; nothing is left in a half-applied state.

What changed in this version

See CHANGELOG.md at the repo root for the running log.

Rolling back

git reset --hard <previous-commit>

Pectus doesn’t ship a CLI rollback because the hard part isn’t the code — it’s the database. If a migration changed the schema in a non-reversible way, rolling back the code without rolling back the database leaves you in a broken state.

If you really need to roll back:

  1. Identify the migration that needs reversing.
  2. Write a manual reverse migration (or restore from a Supabase backup).
  3. Run the reverse migration first.
  4. Then revert the code with git reset --hard <previous-commit>.

If you’re not sure, open an issue at https://github.com/pectusai/pectus/issues before rolling back. Most of the time the right answer is “fix forward” — patch the broken thing, ship a new version.