supacharger-cli

Authentication and Supabase doctor

Run the read-only alignment check from an application root:

supacharger doctor

It checks the Next.js Proxy entry point, protected access boundaries, canonical account/organisation configuration, managed organisation routes/tests/adapters, duplicate App Router pages after route-group normalisation, canonical English namespaces, obsolete account/organisation routes, obsolete MFA visibility config, local TOTP enrol/verify capability, the managed-file manifest, required post-update scripts and Bruno assets, Supabase dependencies and configuration, migrations and aliases, and public environment-variable names. It reports whether contracts exist; it does not print values, contact a linked project, or mutate a database.

The current contract corrects the historical PATH_AUTH_GARD spelling to PATH_AUTH_GUARD. Existing applications must rename that key in src/supacharger.config.ts when adopting this core version.

After a core update adds a Supabase migration, review the changed files and the CLI's linked dry-run output before approving a push. Hosted Auth Hook selection is environment configuration: after deploying the migration, select app.custom_access_token_hook under Authentication → Hooks in each hosted Supabase project. A committed local config.toml does not perform that hosted setting change.

Installation

Install the supacharger-cli with npm. More on npm

npm i @glowplug/supacharger-cli

Commands

init

Clones the canonical starter into the target directory and records the installed core commit in .supacharger/core-lock.json. If the target is the current directory or is not empty, the CLI asks before removing its contents except .git.

The command does not configure environment values, start Supabase, apply hosted migrations, install dependencies, build, or start Next.js. Follow the setup guide after installation.

Example:

supacharger init my-project

enable plugin-name

alias: en

• Enables a registered module by setting enabled to true.

Example:

supacharger en plugin-name

disable plugin-name

alias: dis

• Disables a registered module by setting enabled to false.

Example:

supacharger dis plugin-name

install plugin-name

alias: in

flags: -f (force - will remove git refs and files, then clone a fresh copy)

Atttempts to install a plugin and activate it.

• pulls source from github - may require purcahse first and github username
• modifies core files
• ceates database tables
• pushes edge functions
• seeds data
• enables the module in its config
• stops the development server process
• triggers a rebuild of the project
• starts the development server

supacharger install plugin-name

You will need to rebuild your project after enabling a module

npm run build

uninstall plugin-name

alias: un Completely uninstalls a Plugin

• Removes the Plugin directory from (plugins)
• Attempts to remove source from core files if it has not been modified
• Attempts to remove database tables
• Attempts to remove edge functions
• stops the development server process
• removes Plugin from .gitmodules
• triggers a rebuild of the project, removing it from registry
• starts the development server

Example:

supacharger un plugin-name

coreupdate

Update a project to the latest version of Supacharger.

This ones hardcore and can potentially screw up your project. Back up first.

• Pull the latest core files from the canonical glowplug-studio/supacharger repository.
• Read the version 2 .supacharger/managed-files.json ownership contract: byte-replace only managedPaths, merge mergeManagedPaths, append new files under forwardOnlyMigrationPaths, and preserve developerOwnedPaths.
• Replace shared managed contract tests only with their canonical Core versions. Preserve test/project-billing-schema-contract.test.mjs for application catalogue, table, RPC, and policy assertions, and preserve consumer package scripts that run it beside the shared test.
• Preserve developer-owned adapters in src/supacharger.adapters/, application routes in src/app/(project)/, demo presentation, configuration, localisation, and project styles.
• Install src/app/layout.tsx for a new project, then preserve it as a developer-owned root-layout template during every core update.
• When adopting the Cache Components release, set cacheComponents: true in the developer-owned Next.js configuration and keep export const instant = false in the developer-owned root layout because locale selection reads the request cookie before the document renders. Remove obsolete dynamic = 'force-dynamic' route exports; Cache Components rejects them. Run npm run build before advancing the lock.
• Preserve developer-owned settings in src/supacharger.config.ts; insert only absent approved profile-media, ACCOUNT_SETTINGS, ORGANISATIONS, and BILLING.ACCOUNT_SUBJECTS keys with disabled-safe defaults.
• Remove the obsolete AUTH_SESSION.VERIFICATION_MODE setting while retaining the rest of AUTH_SESSION; claims verification is now a fixed Proxy invariant.
• Remove obsolete AUTHENTICATION.MFA_TOTP.ENABLED, preserve REQUIRED_FOR_SIGN_IN, and enable both local [auth.mfa.totp] APIs. Restart the local Supabase stack after updating; hosted MFA capability remains a separate Dashboard setting.
• Update the protected src/supacharger/supacharger-config-contract.ts so option names and value shapes remain canonical while application values stay unchanged. Follow the release's configuration migration instructions when the contract changes.
• For the social-provider contract expansion, report missing AUTH_PROVDERS_ENABLED keys in --plan; during a real update, back up the developer config, preserve existing values, and add each newly supported provider as false.
• For the root-document contract expansion, report missing METADATA, ROOT_PROVIDERS, and ANALYTICS blocks in --plan; during a real update, back up the developer config and insert only missing blocks. Existing branding and provider values remain application-owned.
• Preserve developer-owned localisation configuration in src/i18n/ and every secondary catalogue. Recursively add missing canonical keys to messages/en.json and fill empty English values without replacing non-empty application wording.
• Install missing auth, account, billing, and organisation adapter/style starters once, then preserve established implementations. src/styles/supacharger-auth.css, src/styles/supacharger-account.css, and src/styles/supacharger-organisations.css own the complete presentation of their managed semantic markup. Organisation adapter starters include chrome.tsx, navigation.ts, pages.tsx, profile-fields.tsx, and profile-extension.ts under src/supacharger.adapters/organisations/.
• Preserve the developer-owned src/assets/svgr/ui/inline-loader.svg and optional dark variant, while updating protected authentication-provider SVGs at src/supacharger/assets/svgr/auth-providers/ and the protected Proxy/server-access paths.
• Record the installed core commit in .supacharger/core-lock.json.
• Detect locally modified or missing baseline files before replacing them.
• Back up overwritten files outside compilable source under .supacharger/backups/ and remove files that were managed by the installed baseline but are obsolete in the new release.
• Merge Core dependency requirements and missing manifest-required scripts into the application package without removing product dependencies or existing scripts. Regenerate the lock only when dependencies change.
• Copy only previously absent Core migrations. A differing migration with the same filename is a conflict; installed migration history is never replaced, removed, reordered, or rewritten. A reviewed consumer-specific equivalent under another immutable filename must be declared explicitly in .supacharger/migration-aliases.json; the plan reports it and update validates the target before skipping the canonical file.
• When migrations changed, show supabase db push --linked --dry-run and ask separately before any linked push. The core lock advances only after the selected post-update work completes.
• Back up and remove an obsolete postcss.config.js only when it matches the installed baseline; preserve and stop on an independently customised legacy file. The canonical exact file is postcss.config.mjs.
• Never treat a copied supabase/config.toml as a hosted Auth Hook update; select the deployed hook separately in each Supabase environment.
• Install the exact managed Bruno collection and checker. Core parity covers every current api RPC; consumer parity requires the canonical subset and permits separate product RPCs.
• Run every manifest-declared check before advancing the lock. Missing scripts, missing canonical RPCs, or parity failures leave the existing lock unchanged.

Preview the exact managed writes, developer-config additions, English catalogue additions, obsolete removals, dependency changes, migrations and aliases, and checks without changing project files or a database:

supacharger coreupdate --plan

supacharger coreupdate

Backups are recovery material for files, not a database rollback. Review the linked migration dry run carefully and take an environment-appropriate database backup before approving a hosted push.