Login

better-supabase login connects the CLI to your Better Supabase cloud account. Commands that call the cloud, such as db seed --sample, use the saved login.

pnpm better-supabase login

The command prints a web address and a short code. Open the address, confirm the code, and the CLI saves the login.

Side effects: Calls the Better Supabase cloud.

How it worksCopy Anchor Link

The CLI starts a device login with POST /api/cli/auth/start, which answers deviceCode, userCode, verificationUrl, interval and expiresIn. It then polls POST /api/cli/auth/poll with the deviceCode. The cloud answers 202 while it waits, 200 with an accessToken, refreshToken, expiresAt and email once you approve, and 410 when the code expired or was denied.

The login lives in $XDG_CONFIG_HOME/better-supabase/auth.json, or ~/.config/better-supabase/auth.json, with mode 0600. $BSB_CLOUD_URL points the CLI at another cloud address.

When the access token is less than a minute from expiresAt, the CLI posts the refreshToken to POST /api/cli/auth/refresh and saves the new tokens the cloud returns (the same body as an approved poll; the refresh token rotates). A refresh token the cloud refuses with 401 asks you to run login again.

logoutCopy Anchor Link

pnpm better-supabase logout

Deletes the saved login. It does not revoke the session in the cloud.

Side effects: Writes files.

whoamiCopy Anchor Link

pnpm better-supabase whoami

Prints the email and plan of the saved login, from GET /api/billing.

Side effects: Calls the Better Supabase cloud.

Sample data endpointCopy Anchor Link

db seed --sample sends POST /api/seeds/sample with a Bearer token and a body of design or preset, instances, variants, locale, size, seed, and a target, tenant with a slug or demoOrg. The cloud answers 200 with statements, summary and estimatedRows. An account without sample data gets 402 application/problem+json with an upgrade address, and the CLI exits with code 3.