### Install Supabase CLI with npm

Source: https://github.com/supabase/cli/blob/develop/apps/docs/content/docs/getting-started.mdx

Install the Supabase CLI using npm.

```sh
npx supabase
```

--------------------------------

### Verify installation

Source: https://github.com/supabase/cli/blob/develop/apps/docs/content/docs/getting-started.mdx

Verify the Supabase CLI installation by checking its version.

```sh
supabase --version
```

--------------------------------

### Install Supabase CLI on Windows

Source: https://github.com/supabase/cli/blob/develop/apps/docs/content/docs/getting-started.mdx

Install the Supabase CLI on Windows using Scoop.

```sh
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase
```

--------------------------------

### Start local development

Source: https://github.com/supabase/cli/blob/develop/apps/docs/content/docs/getting-started.mdx

Spin up a local Supabase stack including Postgres, Auth, and Storage.

```sh
supabase start
```

--------------------------------

### Initialize a project

Source: https://github.com/supabase/cli/blob/develop/apps/docs/content/docs/getting-started.mdx

Create a new Supabase project in the current directory.

```sh
supabase init
```

--------------------------------

### Prefetching in Global Setup

Source: https://github.com/supabase/cli/blob/develop/packages/stack/README.md

Example of prefetching binaries and Docker images in a Vitest global setup to avoid download delays.

```typescript
// vitest.config.ts globalSetup
import { prefetch } from "@supabase/stack";

export async function setup() {
  await prefetch();
}
```

--------------------------------

### Quick start

Source: https://github.com/supabase/cli/blob/develop/apps/docs/content/docs/index.mdx

Commands to install, authenticate, and start a Supabase project locally.

```sh
# Install
brew install supabase/tap/supabase   # macOS
npx supabase                          # or via npx

# Authenticate
supabase login

# Start a project
supabase init
supabase start
```

--------------------------------

### Quick Start

Source: https://github.com/supabase/cli/blob/develop/packages/stack/README.md

Basic example demonstrating how to create, start, and dispose of a Supabase stack with zero configuration.

```typescript
import { createStack } from "@supabase/stack";

// Zero config \u2014 all settings have sensible defaults
const stack = await createStack();
await stack.start();

const supabase = createClient(stack.url, stack.publishableKey);
// ...
await stack.dispose();
```

--------------------------------

### prefetch Vitest Global Setup Example

Source: https://github.com/supabase/cli/blob/develop/packages/stack/docs/architecture.md

Example of how to use `prefetch` in a Vitest `globalSetup` to download assets and pull Docker images.

```ts
// vitest.config.ts / globalSetup.ts
import { prefetch } from "@supabase/stack";

export async function setup() {
  await prefetch(); // downloads auto-mode assets for all services before any test runs
  await prefetch({ mode: "docker" }); // pulls Docker images for all services
}
```

--------------------------------

### Guide file example

Source: https://github.com/supabase/cli/blob/develop/docs/self-documenting-cli.md

Each command can have an optional .guide.md file colocated with its source. A guide file is a hand-authored markdown template with HTML comment markers where auto-generated sections get injected.

```markdown
# Login

Log in to Supabase by providing an access token or using browser-based OAuth.

## When to use

Run once to authenticate before using commands that require auth.

<!-- USAGE:START -->
<!-- USAGE:END -->

<!-- FLAGS:START -->
<!-- FLAGS:END -->

<!-- EXAMPLES:START -->
<!-- EXAMPLES:END -->

## Tips

- Token resolution priority: `--token` flag > `SUPABASE_ACCESS_TOKEN` env > ...

```

--------------------------------

### Authenticate via browser

Source: https://github.com/supabase/cli/blob/develop/apps/docs/content/docs/getting-started.mdx

Log in to Supabase CLI, which opens your browser for OAuth.

```sh
supabase login
```

--------------------------------

### Authenticate with a token

Source: https://github.com/supabase/cli/blob/develop/apps/docs/content/docs/getting-started.mdx

Log in to Supabase CLI using a token, useful for CI environments.

```sh
supabase login --token sbp_your_token_here
```

--------------------------------

### Install Supabase CLI on macOS

Source: https://github.com/supabase/cli/blob/develop/apps/docs/content/docs/getting-started.mdx

Install the Supabase CLI on macOS using Homebrew.

```sh
brew install supabase/tap/supabase
```

--------------------------------

### Seed storage buckets

Source: https://github.com/supabase/cli/blob/develop/apps/cli-go/examples/README.md

Example demonstrating how to seed storage buckets.

```bash
export SUPABASE_PROJECT_ID="zeoxvqpvpyrxygmmatng"
export SUPABASE_SERVICE_ROLE_KEY="eyJh..."
go run examples/migrate-database/main.go
```

--------------------------------

### start command

Source: https://github.com/supabase/cli/blob/develop/apps/cli/docs/go-cli-reference.md

Start containers for Supabase local development.

```cli
Start containers for Supabase local development

Usage:
  supabase start [flags]

Flags:
  -x, --exclude strings       Names of containers to not start. [gotrue,realtime,storage-api,imgproxy,kong,mailpit,postgrest,postgres-meta,studio,edge-runtime,logflare,vector,supavisor]
  -h, --help                  help for start
      --ignore-health-check   Ignore unhealthy services and exit 0
      --sandbox               Run in sandbox mode using native binaries (experimental)
```

--------------------------------

### Example Output

Source: https://github.com/supabase/cli/blob/develop/apps/cli-go/docs/supabase/inspect/db-total-index-size.md

An example of the output from the `db-total-index-size` command.

```text
    SIZE
  ─────────
    12 MB
```

--------------------------------

### Migrate database

Source: https://github.com/supabase/cli/blob/develop/apps/cli-go/examples/README.md

Example demonstrating how to migrate a database. Schemas should be placed under the `supabase/migrations` directory.

```bash
# Place your schemas under supabase/migrations
export PGHOST="db.zeoxvqpvpyrxygmmatng.supabase.co"
export PGPORT="5432"
export PGUSER="postgres"
export PGPASS="<your-password>"
export PGDATABASE="postgres"
go run examples/migrate-database/main.go
```

--------------------------------

### Deploy functions

Source: https://github.com/supabase/cli/blob/develop/apps/cli-go/examples/README.md

Example demonstrating how to deploy functions. Functions should be placed under the `supabase/functions` directory.

```bash
# Place your functions under supabase/functions
export SUPABASE_PROJECT_ID="zeoxvqpvpyrxygmmatng"
export SUPABASE_ACCESS_TOKEN="sbp_..."
go run examples/deploy-functions/main.go
```

--------------------------------

### Example Output

Source: https://github.com/supabase/cli/blob/develop/apps/cli-go/docs/supabase/inspect/db-total-table-sizes.md

An example of the output showing table names and their total sizes.

```console
                NAME               │    SIZE
───────────────────────────────────┼─────────────
  job_run_details                  │ 395 MB
  slack_msgs                       │ 648 kB
  emails                           │ 640 kB
```

--------------------------------

### db start

Source: https://github.com/supabase/cli/blob/develop/apps/cli/docs/go-cli-reference.md

Starts local Postgres database

```shell
Starts local Postgres database

Usage:
  supabase db start [flags]

Flags:
      --from-backup string   Path to a logical backup file.
  -h, --help                 help for start
```

--------------------------------

### Test Setup with beforeAll / afterAll

Source: https://github.com/supabase/cli/blob/develop/packages/stack/README.md

An example of setting up and tearing down a Supabase stack for integration tests using Vitest's beforeAll and afterAll hooks.

```typescript
import { afterAll, beforeAll, describe, expect, test } from "vitest";
import { createStack } from "@supabase/stack";
import { createClient } from "@supabase/supabase-js";

describe("my app", () => {
  let stack;
  let supabase;

  beforeAll(async () => {
    stack = await createStack({
      jwtSecret: "super-secret-jwt-token-with-at-least-32-characters-long",
      postgres: { dataDir: "/tmp/test-supabase" }
    });
    await stack.start();
    supabase = createClient(stack.url, stack.publishableKey);
  }, 120_000);

  afterAll(async () => {
    await stack?.dispose();
  }, 30_000);

  test("queries data", async () => {
    const { data, error } = await supabase.from("todos").select("*");
    expect(error).toBeNull();
  });
});
```

--------------------------------

### Registering a guide

Source: https://github.com/supabase/cli/blob/develop/docs/self-documenting-cli.md

Guides are registered in apps/cli/src/lib/guide-registry.ts.

```typescript
const guides = new Map<string, GuideEntry>([
  [
    "login",
    {
      template: loginGuide,
      skillName: "supabase-login",
      skillDescription: "Use when you need to authenticate, log in, or ...",
    },
  ],
]);
```

--------------------------------

### Install Supabase CLI on Windows via Scoop

Source: https://github.com/supabase/cli/blob/develop/apps/cli/docs/release-process.md

These commands show the user-side installation process for the Supabase CLI on Windows using Scoop, including uninstalling, adding the PoC bucket, installing the shim, and verifying the version.

```powershell
scoop uninstall supabase  # PoC manifest also shims `supabase.exe`
scoop bucket add avallete-poc https://github.com/avallete/scoop-bucket
scoop install supabase-shim-poc
supabase --version        # expect: supabase v0.0.1
```

--------------------------------

### Example Output

Source: https://github.com/supabase/cli/blob/develop/apps/cli-go/docs/supabase/inspect/db-table-index-sizes.md

An example of the output when running the `db-table-index-sizes` command, showing table names and their respective index sizes.

```text
                 TABLE               │ INDEX SIZE
  ───────────────────────────────────┼─────────────
    job_run_details                  │ 10104 kB
    users                            │ 128 kB
    job                              │ 32 kB
    instances                        │ 8192 bytes
    http_request_queue               │ 0 bytes
```

--------------------------------

### Example Output

Source: https://github.com/supabase/cli/blob/develop/apps/cli-go/docs/supabase/inspect/db-index-sizes.md

Example output showing the name and size of various database indexes.

```text
              NAME              │    SIZE
  ──────────────────────────────┼─────────────
    user_events_index           │ 2082 MB
    job_run_details_pkey        │ 3856 kB
    schema_migrations_pkey      │ 16 kB
    refresh_tokens_token_unique │ 8192 bytes
    users_instance_id_idx       │ 0 bytes
    buckets_pkey                │ 0 bytes
```

--------------------------------

### Run from Source Examples

Source: https://github.com/supabase/cli/blob/develop/apps/cli/README.md

Examples of running various Supabase CLI commands from source.

```sh
pnpm dev:next -- start
pnpm dev:next -- start --mode docker
pnpm dev:next -- start --detach
pnpm dev:next -- status
pnpm dev:next -- logs
pnpm dev:next -- login --no-browser
pnpm dev:legacy -- hello
```

--------------------------------

### Discoverable via --help

Source: https://github.com/supabase/cli/blob/develop/docs/adr/0001-cli-dx-architecture-pillars.md

Example of structured and complete help text for the `supabase projects` command, demonstrating usage, subcommands, flags, and examples.

```bash
$ supabase projects --help

Usage: supabase projects [subcommand]

Subcommands:
  list     List all projects (default)
  create   Create a new project

Flags:
  --output <format>   Output format: human, json, env (default: auto)
  --org <id>          Filter by organization ID

Examples:
  supabase projects                     # List all projects
  supabase projects --output json       # JSON output for scripting
  supabase projects create --org abc    # Create project in org
```

--------------------------------

### init command

Source: https://github.com/supabase/cli/blob/develop/apps/cli/docs/go-cli-reference.md

Initialize a local project.

```cli
Initialize a local project

Usage:
  supabase init [flags]

Flags:
      --force          Overwrite existing supabase/config.toml.
  -h, --help           help for init
  -i, --interactive    Enables interactive mode to configure IDE settings.
      --use-orioledb   Use OrioleDB storage engine for Postgres.
```

--------------------------------

### Starting Supabase Local Stack

Source: https://github.com/supabase/cli/blob/develop/tools/release/release-notes-prompt.md

The `supabase start` command now handles missing optional configuration sections like `[db.pooler]` without crashing.

```shell
supabase start
```

--------------------------------

### Usage as a library

Source: https://github.com/supabase/cli/blob/develop/packages/process-compose/README.md

Example of initializing and starting process-compose as a library.

```ts
import { createProcessCompose } from "@supabase/process-compose";

const pc = await createProcessCompose({
  configPath: "process-compose.yaml",
  apiPort: 8080,
});

await pc.start();
```

--------------------------------

### Stack Lifecycle methods

Source: https://github.com/supabase/cli/blob/develop/packages/stack/README.md

Examples of methods to manage the entire stack's lifecycle: start, stop, and dispose.

```typescript
await stack.start(); // Prepare assets, start all services, block until ready
await stack.stop(); // Graceful dependency-ordered shutdown
await stack.dispose(); // stop() + release runtime resources
```

--------------------------------

### Streaming Logs During Debugging

Source: https://github.com/supabase/cli/blob/develop/packages/stack/README.md

Example of creating a stack, starting it, and then streaming PostgreSQL logs to standard output for debugging purposes.

```typescript
const stack = await createStack({
  jwtSecret: "...",
  postgres: { dataDir: "/tmp/data" }
});
await stack.start();

// Print postgres logs as they arrive
for await (const entry of stack.serviceLogs("postgres")) {
  process.stdout.write(entry.message + "\n");
}
```

--------------------------------

### Provider Setup

Source: https://github.com/supabase/cli/blob/develop/apps/cli/docs/ui.md

Example of setting up the `RegistryProvider` in a React application to provide an `AtomRegistry` to components.

```tsx
import { RegistryProvider } from "@effect/atom-react";

function App() {
  return (
    <RegistryProvider initialValues={[[countAtom, 0]]} defaultIdleTTL={400}>
      <MyComponent />
    </RegistryProvider>
  );
}
```

--------------------------------

### Bootstrap Supabase Project from Template

Source: https://github.com/supabase/cli/blob/develop/README.md

Start a new Supabase project using a predefined template.

```sh
supabase bootstrap
```

--------------------------------

### supabase projects create

Source: https://github.com/supabase/cli/blob/develop/apps/cli/docs/go-cli-reference.md

Create a project on Supabase

```bash
Create a project on Supabase

Usage:
  supabase projects create [project name] [flags]

Examples:
supabase projects create my-project --org-id cool-green-pqdr0qc --db-password ******** --region us-east-1

Flags:
      --db-password string   Database password of the project.
  -h, --help                 help for create
      --org-id string        Organization ID to create the project in.
      --region string        Select a region close to you for the best performance.
      --size string          Select a desired instance size for your project.
```

--------------------------------

### bootstrap command

Source: https://github.com/supabase/cli/blob/develop/apps/cli/docs/go-cli-reference.md

Bootstrap a Supabase project from a starter template.

```cli
Bootstrap a Supabase project from a starter template

Usage:
  supabase bootstrap [template] [flags]

Flags:
  -h, --help              help for bootstrap
  -p, --password string   Password to your remote Postgres database.
```

--------------------------------

### AtomRegistry Core Operations

Source: https://github.com/supabase/cli/blob/develop/apps/cli/docs/ui.md

Example of creating an `AtomRegistry` and demonstrating its core operations like `get`, `set`, `subscribe`, `mount`, `refresh`, and `dispose`.

```ts
const registry = AtomRegistry.make({
  scheduleTask: (f) => {
    /* schedule re-evaluation */
  },
  defaultIdleTTL: 400, // ms before GC of idle atoms
  initialValues: [[countAtom, 42]], // optional initial overrides
});

// Core operations
registry.get(atom); // Read current value
registry.set(atom, value); // Write + notify subscribers
registry.subscribe(atom, callback); // Listen for changes 
registry.mount(atom); // Initialize atom (trigger read, setup side effects)
registry.refresh(atom); // Force re-compute
registry.dispose(); // Cleanup everything
```

--------------------------------

### Install Supabase CLI on macOS/Linux via Homebrew

Source: https://github.com/supabase/cli/blob/develop/apps/cli/docs/release-process.md

These commands demonstrate how a user would install the Supabase CLI from a PoC Homebrew tap, including uninstalling previous versions, tapping the repository, installing the shim, and verifying the installation.

```sh
brew uninstall supabase || true       # PoC formula installs a `supabase` binary too
brew tap avallete/supabase-shim-poc   # note: "avallete/<tap-suffix>", not the full repo name
brew install supabase-shim-poc
supabase --version                    # expect: supabase v0.0.1
brew test supabase-shim-poc           # expect: pass
```

--------------------------------

### POST /start

Source: https://github.com/supabase/cli/blob/develop/packages/stack/docs/detach-mode.md

Initiates the startup process for the entire Supabase Stack. This operation triggers the preparation of assets and the starting of all configured services.

```APIDOC
## POST /start

### Description
Starts the entire Supabase Stack.

### Method
POST

### Endpoint
/start
```

--------------------------------

### Installation

Source: https://github.com/supabase/cli/blob/develop/packages/stack/README.md

Command to install the @supabase/stack package using Bun.

```sh
bun add @supabase/stack
```

--------------------------------

### Install Workspace Dependencies

Source: https://github.com/supabase/cli/blob/develop/CONTRIBUTING.md

Command to install all necessary dependencies for the monorepo workspace.

```sh
pnpm install
```

--------------------------------

### Observability Integration Example

Source: https://github.com/supabase/cli/blob/develop/docs/adr/0007-realtime-progress-in-command-handlers.md

Illustrates how 'step' and 'done' pairs in command execution map directly to trace spans, providing real-time progress and observability.

```text
supabase dev (total: 1.2s)
├── config: 12ms       ← step → done
├── docker: 890ms      ← step → done
└── health: 230ms      ← step → done
```

--------------------------------

### Initialize and Start Supabase Local Stack

Source: https://github.com/supabase/cli/blob/develop/README.md

Create a new Supabase workspace and start the local development stack, including Postgres, Auth, Realtime, Storage, and Edge Functions.

```sh
supabase init
supabase start
supabase status
```

--------------------------------

### Example Output

Source: https://github.com/supabase/cli/blob/develop/apps/cli-go/docs/supabase/inspect/db-outliers.md

An example of the output from the db-outliers command, showing various query statistics.

```console
                 QUERY                   │ EXECUTION TIME   │ PROPORTION OF EXEC TIME │ NUMBER CALLS │ SYNC IO TIME
─────────────────────────────────────────┼──────────────────┼─────────────────────────┼──────────────┼───────────────
 SELECT * FROM archivable_usage_events.. │ 154:39:26.431466 │ 72.2%                   │ 34,211,877   │ 00:00:00
 COPY public.archivable_usage_events (.. │ 50:38:33.198418  │ 23.6%                   │ 13           │ 13:34:21.00108
 COPY public.usage_events (id, reporte.. │ 02:32:16.335233  │ 1.2%                    │ 13           │ 00:34:19.784318
 INSERT INTO usage_events (id, retaine.. │ 01:42:59.436532  │ 0.8%                    │ 12,328,187   │ 00:00:00
 SELECT * FROM usage_events WHERE (alp.. │ 01:18:10.754354  │ 0.6%                    │ 102,114,301  │ 00:00:00
```

--------------------------------

### Examples of API Request Commands

Source: https://github.com/supabase/cli/blob/develop/apps/cli/docs/platform-command-generation.md

Examples demonstrating how to list routes, make requests, and inspect schemas for multi-method routes.

```shell
supabase api routes --group projects
```

```shell
supabase api request /v1/projects
```

```shell
supabase api request /v1/projects --method POST
```

```shell
supabase api request /v1/projects/{ref}/config/auth --method PATCH --schema
```

--------------------------------

### Start Verdaccio for Local pg-delta Development

Source: https://github.com/supabase/cli/blob/develop/apps/cli-go/CONTRIBUTING.md

Navigate to the `pg-toolbelt` directory and start the Verdaccio registry to serve local `@supabase/*` packages.

```sh
cd pg-toolbelt
bun run verdaccio:start
```

--------------------------------

### ssl-enforcement get

Source: https://github.com/supabase/cli/blob/develop/apps/cli/docs/go-cli-reference.md

Get the current SSL enforcement configuration

```cli
Get the current SSL enforcement configuration

Usage:
  supabase ssl-enforcement get [flags]

Flags:
  -h, --help   help for get
```

--------------------------------

### config

Source: https://github.com/supabase/cli/blob/develop/apps/cli/docs/go-cli-reference.md

Manage Supabase project configurations

```bash
Manage Supabase project configurations

Usage:
  supabase config [command]

Available Commands:
  push        Pushes local config.toml to the linked project

Flags:
  -h, --help                 help for config
      --project-ref string   Project ref of the Supabase project.
```

--------------------------------

### supabase network-restrictions get

Source: https://github.com/supabase/cli/blob/develop/apps/cli/docs/go-cli-reference.md

Get the current network restrictions

```bash
Get the current network restrictions

Usage:
  supabase network-restrictions get [flags]

Flags:
  -h, --help   help for get
```

--------------------------------

### supabase network-bans get

Source: https://github.com/supabase/cli/blob/develop/apps/cli/docs/go-cli-reference.md

Get the current network bans

```cli
Get the current network bans

Usage:
  supabase network-bans get [flags]

Flags:
  -h, --help   help for get
```

--------------------------------

### Explore Supabase CLI Command Options

Source: https://github.com/supabase/cli/blob/develop/README.md

Use the `--help` flag with any Supabase CLI command to view available options and examples.

```sh
supabase db --help
supabase functions deploy --help
```

--------------------------------

### Install websocat

Source: https://github.com/supabase/cli/blob/develop/apps/cli-go/tests/README.md

Command to install websocat, a prerequisite for some tests, using Homebrew.

```bash
brew install websocat
```

--------------------------------

### Default `supabase init` Config File Path

Source: https://github.com/supabase/cli/blob/develop/apps/cli/docs/supabase-home.md

The default path where `supabase init` creates a minimal repository-scoped configuration file.

```text
supabase/config.json
```