Documentation

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

Docs/Agent CLI setup

Agent CLI setup

Let an AI agent set up BaseBuddy projects with CLI commands, schema inspection, mapping drafts, and verification before saving.

Use this flow when an AI agent or operator needs to set up BaseBuddy against an existing Postgres/Supabase schema without digging through BaseBuddy source code.

The CLI can now inspect the connected database, draft mapping JSON, explain that mapping, and save it through the same config APIs the app uses. That gives agents a safer path:

  1. inspect the live schema,
  2. create a small hints file when the schema uses custom names,
  3. draft mapping JSON,
  4. explain and verify the draft,
  5. save the mapping only after it is valid.

For the full command list, keep CLI reference open beside this page. If you are still doing the first install, start with First-run setup or How to set up BaseBuddy from UI or CLI.

If the agent needs to choose where BaseBuddy app data should live, start with App data storage options.

Start with the agent workflow

Run this first from the BaseBuddy app root:

bashpnpm basebuddy agent:setup --json

It prints the recommended command order for agents. The output is intentionally machine-readable so an agent can plan the setup without guessing from docs prose.

The short version is:

bashpnpm basebuddy doctor --json
pnpm basebuddy app-data:migrate
pnpm basebuddy app-data:check
pnpm basebuddy setup --owner-email owner@example.com --owner-name "Owner" --owner-password "strong-password"
pnpm basebuddy projects:create --actor-email owner@example.com --name "Docs" --slug docs
pnpm basebuddy schema:inspect --schema public --json
pnpm basebuddy mapping:draft --schema public --table posts --json
pnpm basebuddy mapping:explain --input mapping.json --json
pnpm basebuddy mapping:set --project docs --input mapping.json --binding-status ready --json

Use real values for the owner, project name, slug, schema, table, and mapping file. Skip app-data:migrate and app-data:check when the install uses the default basebuddy-data/ folder.

If the Supabase/Postgres app-data role cannot create schemas or tables, use:

bashpnpm basebuddy app-data:sql

Run the printed SQL in the database SQL editor, then continue with pnpm basebuddy app-data:check.

Inspect the schema

Before writing mapping JSON, ask BaseBuddy what the connected database actually exposes:

bashpnpm basebuddy schema:inspect --schema public --json

For a narrower run:

bashpnpm basebuddy schema:inspect --schema public --table posts,authors,categories --json

The output includes tables, columns, primary keys, foreign keys, enum values, row estimates, and a few sample rows when they can be read safely. It does not print your database URL or env secrets.

Use this output instead of reading BaseBuddy internals to learn the user's table names and column names. If a table is missing, fix database permissions or the schema/table flags before drafting mapping.

Draft mapping JSON

For common schemas, draft directly from inspection:

bashpnpm basebuddy mapping:draft --schema public --table posts --json > mapping-draft.json

If the schema has custom names, create a hints file. Hints are not the mapping itself; they only tell BaseBuddy which table and fields to prefer while drafting valid mapping JSON.

json{
  "postsTable": "public.pages",
  "titleColumn": "headline",
  "slugColumn": "slug",
  "excerptColumn": "summary",
  "featuredImageUrlColumn": "hero_image_url",
  "contentFields": [
    {
      "column": "body_md",
      "kind": "markdown",
      "label": "Body"
    }
  ],
  "customFields": [
    {
      "column": "faq_json",
      "kind": "json",
      "label": "FAQ"
    }
  ],
  "workflow": {
    "mode": "published_flag",
    "publishedFlagColumn": "is_published",
    "publishedAtColumn": "published_at"
  }
}

Then draft with the hints:

bashpnpm basebuddy mapping:draft --schema public --table pages --hints mapping-hints.json --json > mapping-draft.json

The draft output includes mappingConfig, summary, and valid: true. Save only the mappingConfig object as the file you pass to mapping:set.

Explain before saving

Before applying the mapping, explain it:

bashpnpm basebuddy mapping:explain --input mapping.json --json

Check the summary for:

  • the right posts source, such as public.pages;
  • the expected title, slug, content, workflow, and custom fields;
  • safe storage shapes for Markdown, HTML, JSON, arrays, and relations;
  • optional storage metadata only when media/files are needed.

If anything looks wrong, update the hints or mapping JSON and run mapping:explain again. Do not save a mapping that points at the wrong source table or writes to fields the user expects to stay read-only.

Save through the CLI

When the explanation is correct:

bashpnpm basebuddy mapping:validate --input mapping.json --json
pnpm basebuddy mapping:set --project docs --input mapping.json --binding-status ready --json
pnpm basebuddy mapping:get --project docs --json

mapping:set saves a mapping revision in BaseBuddy app data. It does not rename tables, add columns, or change user content schemas.

Agents can also save sidebar layout and non-secret storage metadata:

bashpnpm basebuddy sidebar:set --project docs --input sidebar.json --json
pnpm basebuddy storage:set --project docs --library media --provider supabase_bucket --bucket media --json
pnpm basebuddy storage:set --project docs --library files --provider s3_compatible --bucket files --region auto --endpoint https://example.r2.cloudflarestorage.com --json

Storage commands save metadata only. Supabase keys, S3 keys, database URLs, and auth secrets still belong in env. See Media and files and How to configure Supabase Storage buckets when uploads are part of the setup.

What agents should avoid

Agents should not edit app data directly unless they are repairing a broken default file and the CLI cannot load it.

Agents should not guess mapping JSON from source code. Use schema:inspect, mapping:draft, and mapping:explain first. Source reading is only for BaseBuddy development, not normal user setup.

Agents should not put secrets into mapping files, config files, screenshots, docs, or final answers. Keep secrets in .env or the production host.