Documentation

Practical product docs for setting up, mapping, editing, and operating BaseBuddy.

Docs/First-run setup

First-run setup

Create BaseBuddy app data from onboarding or the CLI.

First-run setup creates BaseBuddy app data. By default, that is process.cwd()/basebuddy-data/basebuddy.config.json.

App data stores local users, sessions, projects, members, permissions, invitations, mappings, and sidebar settings. Secrets stay in env. Your existing content database schema stays untouched.

Before choosing a backend, compare the three options in App data storage options.

Setup Flow

Open /onboardingChoose where to storeBaseBuddy dataConnect to yourdatabasePrepare BaseBuddy datatables(Supabase/PostgresCreate account onBaseBuddyLet's check the setupnowOpen BaseBuddy andsign inCreate projectSave mapping

Use Onboarding

  1. Start the app.
  2. Open /onboarding.
  3. Choose where to store BaseBuddy data.
  4. Add the required env values shown on Connect to your database.
  5. If you chose Supabase/Postgres app data, prepare the BaseBuddy data tables:

```sh

pnpm basebuddy app-data:migrate

pnpm basebuddy app-data:check

`

If the database role cannot create tables, run pnpm basebuddy app-data:sql and paste the printed SQL into your database SQL editor.

  1. Confirm I added the env values.
  2. Create the first owner account.
  3. Let setup checks run automatically.

When setup succeeds, BaseBuddy shows Open BaseBuddy. Sign in with the owner account, then create your first project.

Use CLI Setup

Agents and operators can create the same app data without clicking through the UI.

If you selected Supabase/Postgres app data, run this before setup:

shpnpm basebuddy app-data:migrate
pnpm basebuddy app-data:check

Then create the owner:

shpnpm basebuddy setup \
  --owner-email owner@example.com \
  --owner-name "Owner" \
  --owner-password "replace-with-a-strong-password"

Run diagnostics:

shpnpm basebuddy doctor

The same CLI surface can also manage app-data-backed users, projects, members, invites, permissions, mapping revisions, sidebar layout, and storage mapping metadata. See CLI reference.

What Setup Does Not Do

BaseBuddy does not rename tables, add columns, rewrite content, or infer a mapping as runtime truth. If you choose Supabase/Postgres app data, the migration creates only basebuddy.app_state and basebuddy.audit_events. The saved mapping you create later is what drives reads and writes.