# supacharger-cli

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

# supacharger-cli

## Authentication and Supabase doctor

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

```bash
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

```bash
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:

```bash
supacharger init my-project
```

### enable plugin-name

alias: **en**

- Enables a registered module by setting enabled to true.

Example:

```bash
supacharger en plugin-name
```

### disable plugin-name

alias: **dis**

- Disables a registered module by setting enabled to false.

Example:

```bash
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

```bash
supacharger install plugin-name
```

You will need to rebuild your project after enabling a module

```bash
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:

```bash
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:

```bash
supacharger coreupdate --plan
```

```bash
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.