The Three Surfaces
bgng is one binary with three independent surfaces. They share config, workspace state, and error conventions, but a user can stay within one surface without touching the others.
Personal knowledge base
This surface captures YouTube transcripts, imports Markdown or text files, manages qmd collections and context, and searches content.
Core commands:
bgng init
bgng url "<youtube-url>"
bgng queue add "<youtube-url>"
bgng search "exact words"
bgng query "semantic question"
IDE control plane
This surface installs the beginningdb-cloudfs VSCode extension, manages named profiles, stores auth material, refreshes gateway sessions, and opens workspaces.
Core commands:
bgng ide install
bgng ide connect --mode beginningdb.direct --id local-dev ...
bgng ide login --profile local-dev --token "Bearer ..."
bgng ide profiles resolve local-dev --json
Direct admin
This surface is closer to operational tooling. bgng db sends direct BeginningDB HTTP requests. bgng s3 calls S3 adapter admin endpoints.
Core commands:
bgng db doctor --profile local-dev
bgng db cat /readme.md --profile local-dev
bgng s3 keys list
bgng s3 sessions abort <upload-id>
Shared conventions
All surfaces use the same clipanion binary, stdout/stderr split, BgngError exit-code model, and local workspace under ~/.bgng/ unless BGNG_HOME is set.