Supabase CLI

https://github.com/supabase/cli
Admin
The Supabase CLI is a command-line interface tool for managing Supabase projects, enabling local...
Tokens:1,038,227
Snippets:6,288
Trust Score:10
License:MIT
Update:21 hours ago
Show doc for...
Tokens:
Raw
### Quick start with Supabase CLI

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

Install the CLI via Homebrew or npx, log in to authenticate, and initialize and start a local Supabase stack.

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

# Authenticate
supabase login

# Start a project
supabase init
supabase start
```

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

### Start local development using supabase start

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

Starts local Supabase Docker containers with options to exclude specific services or run in sandbox mode.

```text
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)
```

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

### Create and manage a standalone database instance

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

This TypeScript example demonstrates how to create a standalone database instance using the proposed `stack.services.create` API. It shows starting, waiting for readiness, and destroying the instance. Use this pattern when you need an independent database instance not part of the default composition.

```typescript
const shadow = await stack.services.create({
  service: "database",
  pin: selection.database,
  config: {},
  endpoints: { sql: { port: "auto" } },
});

try {
  await shadow.start();
  await shadow.ready();
  // Run the migration or comparison against this instance.
} finally {
  await shadow.destroy();
}
```

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

### Explore Command Flags and Examples via Help

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

Passes the `--help` flag to specific commands to view detailed usage instructions, options, and examples.

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

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

### supabase db start command usage and flags

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

Starts the local Postgres database instance, optionally restoring from a logical backup file.

```text
Starts local Postgres database

Usage:
  supabase db start [flags]

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

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

### Start local Supabase development stack

Source: https://github.com/supabase/cli/blob/develop/apps/cli-go/internal/utils/templates/initial_schemas/README.md

Initializes and starts the local Supabase development stack with default configuration, excluding gotrue, storage-api, and imgproxy.

```bash
go run . init
go run . start -x gotrue,storage-api,imgproxy
```

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

### JSON output of supabase stack start

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

Example JSON output from `supabase stack start --output-format json`, showing stack ID, runtime, endpoints, lazy services, and environment variables.

```json
{
  "id": "<stack id>",
  "runtime": "docker",
  "endpoints": {
    "database.sql": {
      "protocol": "tcp",
      "address": "127.0.0.1",
      "port": 54322,
      "url": "tcp://127.0.0.1:54322"
    }
  },
  "lazy_services": ["rest", "auth", "studio"],
  "env": {
    "API_URL": "http://127.0.0.1:54321",
    "DB_URL": "postgresql://postgres:postgres@127.0.0.1:54322/postgres",
    "STUDIO_URL": "http://127.0.0.1:54323",
    "MCP_URL": "http://127.0.0.1:54321/mcp",
    "MAILPIT_URL": "http://127.0.0.1:54324",
    "PUBLISHABLE_KEY": "sb_publishable_...",
    "SECRET_KEY": "sb_secret_...",
    "ANON_KEY": "ey...",
    "SERVICE_ROLE_KEY": "ey..."
  },
  "message": ""
}
```

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

### Install Supabase CLI on Windows via Scoop

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

Add the Supabase bucket and 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 Supabase development stack

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

Start local containers for Postgres, Auth, Storage, and other services. Prints the local API URL and keys once ready.

```sh
supabase start
```

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

### Install Inspection Reference Repositories

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

Installs reference repositories used for developer and agent inspection after performing a fresh repository clone.

```sh
pnpm repos:install
```

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

### DatabaseInstance snapshot interface and usage example

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

Defines the DatabaseInstance interface with saveSnapshot and restoreSnapshot methods, and demonstrates their usage with baseline and shadow instances. The example shows stopping the baseline, saving a snapshot, restoring it on a fresh shadow instance, and starting the shadow. A failed restore leaves the empty instance in place for initialization.

```typescript
interface DatabaseInstance extends ServiceInstance {
  readonly service: "database";
  saveSnapshot(key: string, options?: { scope?: "cache" | "instance" }): Promise<void>;
  restoreSnapshot(key: string, options?: { scope?: "cache" | "instance" }): Promise<boolean>;
}

// `baseline` has already been initialized; `shadow` is a fresh instance.
await baseline.stop();
await baseline.saveSnapshot("baseline");

if (!(await shadow.restoreSnapshot("baseline"))) {
  // A miss leaves the empty instance in place; initialize that same instance.
}
await shadow.start();
await shadow.ready();
```

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

### Initialize and Start Local Supabase Stack

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

Initializes a Supabase workspace and starts the local stack containing Postgres, Auth, Realtime, Storage, Edge Functions, and APIs.

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

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

### Install pinned tool versions with mise

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

Install the pinned tool versions (Node, Bun, Go, pnpm, golangci-lint, jactionlint, shellcheck) that this repo expects. Run after trusting the repo's mise.toml.

```sh
mise install
```

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

### Install and test Supabase shim via Scoop

Source: https://github.com/supabase/cli/blob/develop/docs/adr/0011-cli-release-and-distribution-strategy.md

Add the custom Scoop bucket and install the Supabase CLI shim package to verify installation and version output on Windows x64.

```powershell
scoop bucket add avallete-poc https://github.com/avallete/scoop-bucket
scoop install supabase-shim-poc
supabase-shim-poc --version   # expect: supabase v0.0.1
```

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

### Open a stack and start a database using Effect

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

Opens a stack with `Stack.open`, retrieves a database service, starts it, waits for readiness, and returns its status. The handle is scoped and will be destroyed when the enclosing `Scope` closes. Requires `NodeServices` and `NodeHttpClient` layers.

```typescript
import { NodeHttpClient, NodeServices } from "@effect/platform-node";
import { Effect, Layer } from "effect";
import * as Stack from "@supabase/stack/effect";

const program = Effect.gen(function* () {
  const stack = yield* Stack.open({ id, stateRoot, cacheRoot });
  const database = yield* stack.services.get(databaseId);
  yield* database.start;
  yield* database.ready;
  return yield* database.status;
});

await Effect.runPromise(
  program.pipe(
    Effect.scoped,
    Effect.provide(Layer.merge(NodeServices.layer, NodeHttpClient.layerNodeHttp)),
  ),
);
```

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

### Start local registry with pnpm local-registry

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

Starts a local Verdaccio registry on http://localhost:4873 and creates a publish user. Global npm and pnpm registry config is not modified; press Ctrl+C to stop.

```sh
pnpm local-registry
```

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

### Install Supabase CLI on macOS via Homebrew

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

Install the Supabase CLI on macOS using Homebrew tap.

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

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

### Test published package with npx or global install

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

Tests the published package by running it directly with npx or installing globally. Both commands target the local registry at http://localhost:4873.

```sh
# Run directly with npx
npx --registry http://localhost:4873 supabase@0.0.0-local.1 --version

# Or install globally and run as `supabase`
npm install -g --registry http://localhost:4873 supabase@0.0.0-local.1
supabase --version
```

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

### POST /v1/projects/{ref}/custom-hostname/initialize

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/domains/SIDE_EFFECTS.md

Initializes the custom hostname setup for a project. Used during the `create` operation.

```APIDOC
## POST /v1/projects/{ref}/custom-hostname/initialize

### Description
Initializes the custom hostname setup for a project. Used during the `create` operation.

### Method
POST

### Endpoint
/v1/projects/{ref}/custom-hostname/initialize

### Authentication
Bearer token

### Parameters
#### Path Parameters
- **ref** (string) - Required - Project reference

#### Request Body
- **custom_hostname** (string) - Required - The custom hostname to initialize

### Request Example
{
  "custom_hostname": "example.com"
}

### Response
#### Success Response (201)
- **status** (string) - Status of the operation
- **custom_hostname** (string) - The custom hostname
- **data** (object) - Additional data
  - **result** (object) - Result object
    - **ssl** (object) - SSL information
    - **custom_origin_server** (string) - Custom origin server

#### Response Example
{
  "status": "success",
  "custom_hostname": "example.com",
  "data": {
    "result": {
      "ssl": {},
      "custom_origin_server": "origin.example.com"
    }
  }
}
```

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

### Start local Verdaccio registry

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

Run this in one terminal to start the local npm registry for Ring 1 testing.

```sh
pnpm local-registry
```

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

### Install Supabase CLI across platforms

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

Install Supabase CLI via curl, npm, Homebrew, or Scoop across macOS, Linux, and Windows platforms.

```sh
# YOLO
curl -fsSL https://raw.githubusercontent.com/supabase/cli/main/install | bash

# npm
npm install -D supabase                   # or bun/pnpm/yarn add -D supabase
npm install -D supabase@beta              # beta channel

# macOS and Linux
brew install supabase/tap/supabase        # always up to date
brew install supabase                     # official formula, may be delayed
brew install supabase/tap/supabase-beta   # beta channel

# Windows
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase
scoop install supabase-beta               # beta channel

# Linux packages
# Download .apk, .deb, .rpm, or .pkg.tar.zst from GitHub Releases.
```

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

### Install mise on macOS or Linux

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

Install mise on macOS or Linux using the official install script or Homebrew. Use this to set up the polyglot version manager for the Supabase CLI monorepo.

```sh
# macOS / Linux
curl https://mise.run | sh

# macOS via Homebrew
brew install mise
```

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

### Install the PoC release on macOS/Linux with Homebrew

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

Commands a fresh reviewer runs without cloning the repo. The PoC formula installs a `supabase` binary too, so uninstall any existing one first. `brew tap <owner>/<suffix>` looks up https://github.com/<owner>/homebrew-<suffix>, which is why the tap repo must be named homebrew-supabase-shim-poc.

```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
```

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

### Install stack dependencies with supabase stack install

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

Resolves and locks service versions, then downloads artifacts without creating a stack. Use `--frozen` to fail if the lock is missing or out-of-date, and `--runtime native` to download archives into the artifact cache.

```sh
supabase stack install
supabase stack install --frozen --runtime native --output-format json
```

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

### GET /v1/projects

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/experimental/compute/push/SIDE_EFFECTS.md

Lists available projects for selection.

```APIDOC
## GET /v1/projects

### Description
Retrieves a list of projects for project picking.

### Method
GET

### Endpoint
`/v1/projects`

### Authentication
Bearer token

### Request Body
None

### Response
- **id** - Project identifier
- **name** - Project name
- **organization_slug** - Organization slug
- **region** - Project region
```

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

### Example gateway access log line

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/experimental/stack/start/SIDE_EFFECTS.md

The shared API port records each request and WebSocket upgrade under `logs/gateway/gateway/` as one nginx combined line with a millisecond timestamp and a trailing duration. This example shows the format of such a log entry.

```text
127.0.0.1 - - [01/Oct/2026:09:25:23.456 +0000] "GET /rest/v1/todos?select=* HTTP/1.1" 200 126 "-" "curl/8.7.1" 12ms
```

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

### GET /v1/projects/{ref}

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/notebooks/pull/SIDE_EFFECTS.md

Fetches details of a specific project for cache filling.

```APIDOC
## GET /v1/projects/{ref}

### Description
Retrieves details for a specific project reference to fill the linked project cache.

### Method
GET

### Endpoint
`/v1/projects/{ref}`

### Parameters
#### Path Parameters
- **ref** (string) - Required - Project reference identifier

### Authentication
Bearer token
```

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

### Run CLI help from source

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

Navigate to the CLI workspace and display available CLI commands using pnpm.

```sh
cd apps/cli
pnpm dev -- --help
```

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

### Bootstrap Project from Template

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

Initializes a new Supabase project workspace based on a predefined template.

```sh
supabase bootstrap
```

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

### Verify Supabase CLI installation

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

Check the installed version of the Supabase CLI to verify installation.

```sh
supabase --version
```

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

### GET /v1/projects

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/backups/list/SIDE_EFFECTS.md

Lists available projects. Used as a fallback prompt when a project is not specified.

```APIDOC
## GET /v1/projects

### Description
Retrieves a list of projects.

### Method
GET

### Endpoint
`/v1/projects`

### Authentication
Bearer token

### Response
#### Success Response
Array of project objects containing:
- **id** - Project identifier
- **ref** - Project reference
- **name** - Project name
- **organization_slug** - Organization slug
- **region** - Project region
```

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

### Install workspace dependencies

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

Install workspace dependencies. This also installs a local commit-msg git hook via husky that validates commit messages against commitlint.config.js.

```sh
pnpm install
```

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

### Initialize a new Supabase project

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

Create a new Supabase configuration and project structure in the current directory.

```sh
supabase init
```

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

### GET /v1/projects/{ref}

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/projects/SIDE_EFFECTS.md

Fetches project details by reference ID to populate project cache.

```APIDOC
## GET /v1/projects/{ref}

### Description
Fetches project details for a specific project reference.

### Method
GET

### Endpoint
`/v1/projects/{ref}`

### Authentication
Bearer token

### Parameters
#### Path Parameters
- **ref** - Required - Project reference
```

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

### View structured help text with supabase projects --help

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

Provides structured, complete command syntax, subcommands, flags, and usage examples that LLM agents can parse to understand command capabilities.

```text
$ 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
```

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

### GET /v1/projects/{ref}/custom-hostname

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/domains/SIDE_EFFECTS.md

Retrieves the custom hostname configuration for a project. Used during the `get` operation.

```APIDOC
## GET /v1/projects/{ref}/custom-hostname

### Description
Retrieves the custom hostname configuration for a project. Used during the `get` operation.

### Method
GET

### Endpoint
/v1/projects/{ref}/custom-hostname

### Authentication
Bearer token

### Parameters
#### Path Parameters
- **ref** (string) - Required - Project reference

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - Status of the operation
- **custom_hostname** (string) - The custom hostname
- **data** (object) - Additional data
  - **result** (object) - Result object
    - **ssl** (object) - SSL information
    - **custom_origin_server** (string) - Custom origin server

#### Response Example
{
  "status": "success",
  "custom_hostname": "example.com",
  "data": {
    "result": {
      "ssl": {},
      "custom_origin_server": "origin.example.com"
    }
  }
}
```

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

### Install @supabase/config with Effect

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

Install @supabase/config alongside the required Effect 4.x peer dependency using the rc dist-tag.

```sh
npm install @supabase/config effect@rc
```

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

### Link or deploy project with existing local variables

Source: https://github.com/supabase/cli/blob/develop/docs/environments-management.md

Run link or deploy to detect local environment files and prompt to push variables to the development environment. Confirming the prompt pushes standard variables via the bulk upsert API.

```shell
cli link          # or cli deploy
```

```text
Found local environment variables in supabase/.env.Push them to the "development" environment? [y/N]

```

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

### Initialize a local project using supabase init

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

Initializes a local Supabase configuration file, with options for interactive IDE setup and OrioleDB storage.

```text
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.
```

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

### GET /v2/projects/{ref}/notebooks

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/notebooks/pull/SIDE_EFFECTS.md

Lists project notebooks for broad pull reconciliation. Follows links.next for pagination.

```APIDOC
## GET /v2/projects/{ref}/notebooks

### Description
Retrieves a list of notebooks belonging to a project, used for broad pull operations. Pagination is walked by following links.next until it is null.

### Method
GET

### Endpoint
`/v2/projects/{ref}/notebooks`

### Parameters
#### Path Parameters
- **ref** (string) - Required - Project reference identifier

### Authentication
Bearer token

### Response
#### Success Response
- **data[].id** (string) - Notebook identifier
- **data[].attributes.name** (string) - Notebook name
- **links.next** (string) - URL for the next page of results
```

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

### Display table index sizes output

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

Example output showing index sizes for each database table calculated via pg_indexes_size().

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

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

### Create and manage a standalone database service

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

Use the Promise entrypoint to create a stack and a database service with explicit artifact pins. Start and ready are separate operations; restart replaces recipe configuration while retaining instance identity. Snapshots require a stopped instance with wake disabled.

```typescript
import { create } from "@supabase/stack";
import { postgres } from "@supabase/stack/commands";
import { defaultArtifactSelection } from "@supabase/stack/defaults";

// Every service names the exact artifact pin it runs; the defaults are the compiled catalog pins.
const selection = defaultArtifactSelection();

const stack = await create({
  projectRoot: process.cwd(),
  runtime: "native", // or "docker" or "podman"
  stateRoot: "/tmp/example-stack/state",
  cacheRoot: "/tmp/example-stack/cache",
});

const database = await stack.services.create({
  service: "database",
  pin: selection.database,
  config: {
    databasePassword: "local-password",
    jwtSecret: "local-development-secret-at-least-32-characters",
    jwtExpiry: 3600,
  },
  endpoints: { sql: { port: "auto" } },
});

await database.start(); // process launched
await database.ready(); // initialization and health completed
const { databaseUrl } = await database.credentials({ from: "runtime" });

if (databaseUrl === undefined) throw new Error("Database endpoint missing");
await stack.commands.run(postgres.psql({ pin: selection.database }), {
  args: ["--dbname", databaseUrl, "--command", "SELECT 1"],
  stdout: (bytes) => {
    process.stdout.write(bytes);
  },
  stderr: (bytes) => {
    process.stderr.write(bytes);
  },
});

// Runs recipe initialization without registering a service instance.
const { authDatabaseUrl } = await database.credentials({ from: "runtime" });
if (authDatabaseUrl === undefined) throw new Error("Auth database URL missing");
await stack.commands.run({
  type: "auth.initialize",
  pin: selection.auth,
  databaseId: database.id,
  databaseUrl: authDatabaseUrl,
});

await database.stop();
await database.saveSnapshot("baseline");
await stack.close(); // disconnects this client
```

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

### Enable stack backend in supabase/config.toml

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

Add this to `supabase/config.toml` to make `supabase start`, `supabase stop`, and `supabase status` aliases of the corresponding `supabase stack` commands. Set to `false` or remove to restore legacy commands.

```toml
[experimental]
stack = true
```

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

### GET /v2/projects/{ref}/compute/{name}

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/experimental/compute/push/SIDE_EFFECTS.md

Retrieves the current build and runtime state for a given compute resource.

```APIDOC
## GET /v2/projects/{ref}/compute/{name}

### Description
Fetches status information, image version, and spec for a compute resource, often polled while build state is building.

### Method
GET

### Endpoint
`/v2/projects/{ref}/compute/{name}`

### Authentication
Bearer token

### Parameters
#### Path Parameters
- **ref** - Project reference
- **name** - Compute name

### Request Body
None

### Response
- **build_state** - Status of the build
- **state_reason** - Reason for current state
- **image_version** - Image version deployed
- **spec** - Compute specification
```

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

### Run live suite locally with pnpm run test:live

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

Runs the live suite locally after copying apps/cli/live.env.example and setting the API URL and access token. The root Turbo entrypoint prepares CLI artifacts before Vitest starts.

```sh
pnpm run test:live
```

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

### Import loadCliConfig convenience entrypoint from @supabase/config/io

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

Imports loadCliConfig for convenience entrypoints at the runtime edge.

```ts
import { loadCliConfig } from "@supabase/config/io";
```

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

### Pass explicit registry to npx or npm install

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

Use when npx resolves from npm instead of the local registry. Passes the local registry URL explicitly to npx or npm install.

```shell
npx --registry http://localhost:4873
```

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

### Project Creation Response with --output-format json

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/projects/create/SIDE_EFFECTS.md

Emitted to stdout as a single JSON object on successful project creation, containing fields for the created project.

```json
{
  "id": "abcdefghijklmnopqrst",
  "organization_slug": "combined-fuchsia-lion",
  "name": "my-project",
  "region": "us-east-1",
  "created_at": "2022-04-25T02:14:55.906498Z"
}
```

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

### open({ id, stateRoot, cacheRoot })

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

Reconnects to a saved stack. The package stores the stack document at `<stateRoot>/<id>/state.json` and service data at `<stateRoot>/<id>/data/<instance-id>`. Use `startOwner: true` to start a detached owner process for live operations.

```APIDOC
## open({ id, stateRoot, cacheRoot })

### Description
Reconnects to a saved stack. The package stores the stack document at `<stateRoot>/<id>/state.json` and service data at `<stateRoot>/<id>/data/<instance-id>`. Use `startOwner: true` to start a detached owner process for live operations.

### Method
Function call

### Endpoint
`open({ id, stateRoot, cacheRoot })`

### Parameters
- **id** (string) - Required - The stack ID.
- **stateRoot** (string) - Required - Root directory for state.
- **cacheRoot** (string) - Required - Root directory for cache.
- **startOwner** (boolean) - Optional - If true, starts a detached owner process.
- **requestedCreations** (array) - Optional - Creations to hand to a freshly spawned owner.

### Request Example
```json
{
  "id": "my-stack",
  "stateRoot": "/path/to/state",
  "cacheRoot": "/path/to/cache",
  "startOwner": true,
  "requestedCreations": []
}
```

### Response
Returns a stack object with saved definition and live owner's endpoint, if any.

#### Response Example
```json
{
  "id": "my-stack",
  "definition": { ... },
  "endpoint": "http://localhost:54321"
}
```
```

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

### Build all migrated workspaces

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

Build all migrated workspaces.

```sh
pnpm run build
```

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

### Seed production environment from preview

Source: https://github.com/supabase/cli/blob/develop/docs/environments-management.md

Seed the production environment interactively from the preview environment when preparing for deployment.

```shell
cli env seed production --from preview --interactive
```

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

### View per-platform package archive layout

Source: https://github.com/supabase/cli/blob/develop/docs/adr/0011-cli-release-and-distribution-strategy.md

Illustrates the directory layout for per-platform packages containing the compiled executable and the legacy proxy target.

```text
packages/cli-<platform>/bin/
├── supabase      (Bun --compile SFE)
└── supabase-go   (legacy shell only, Phase 0 proxy target)
```

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

### Test Scoop manifest locally with --local and --dry-run

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

The Scoop updater script supports --local to generate a manifest pointing at local dist artifacts instead of a GitHub URL. Copy the JSON from dist/supabase-shim-poc.json, then install it with scoop install.

```powershell
bun apps/cli/scripts/update-scoop.ts --version 0.0.1 `
    --name supabase-shim-poc --local --dry-run
# Copy the JSON from dist/supabase-shim-poc.json, then:
scoop install .\dist\supabase-shim-poc.json
```

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

### Install the PoC release on Windows with Scoop

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

Commands a fresh reviewer runs without cloning the repo. The PoC manifest also shims `supabase.exe`, so uninstall any existing one first. Validated on Windows x64 (v0.0.1, 2026-04-21) with no SmartScreen block on the unsigned Bun SFE; Windows arm64 is still pending.

```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
```

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

### GET /v1/projects

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/secrets/unset/SIDE_EFFECTS.md

Retrieves the list of projects for project selection.

```APIDOC
## GET /v1/projects

### Description
Fetches available projects.

### Method
GET

### Endpoint
`/v1/projects`

### Authentication
- **Bearer token**

### Response
#### Success Response
- Project picker list.
```

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

### Benchmark CLI binaries using bench-cli.ts

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

Compares wall-time performance between a base CLI binary and a branch build across repeated runs with warmup iterations. Uses --trace to run untimed span comparisons and --cwd-setup init for commands requiring an initialized project.

```sh
bun apps/cli/scripts/bench-cli.ts --base /tmp/cli-base/apps/cli/dist/supabase --branch apps/cli/dist/supabase \
  --runs 10 --warmup 2 --command "--version" --command "status" --cwd-setup init --trace
```

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

### GET /v1/organizations

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/projects/SIDE_EFFECTS.md

Retrieves the list of organizations accessible by the authenticated user.

```APIDOC
## GET /v1/organizations

### Description
Retrieves the list of organizations.

### Method
GET

### Endpoint
`/v1/organizations`

### Authentication
Bearer token

### Response
#### Success Response
- **id** - Organization identifier
- **slug** - Organization slug
- **name** - Organization name
```

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

### GET /v1/projects

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/notebooks/push/SIDE_EFFECTS.md

Retrieves a list of projects available to the authenticated user.

```APIDOC
## GET /v1/projects

### Description
Retrieves a list of available projects.

### Method
GET

### Endpoint
`/v1/projects`

### Authentication
Bearer token

### Response
#### Success Response
- **id** (string) - Project ID
- **name** (string) - Project name
- **organization_slug** (string) - Organization slug
- **region** (string) - Project region
```

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

### Seed preview environment from development

Source: https://github.com/supabase/cli/blob/develop/docs/environments-management.md

Seed the preview environment interactively using variable values defined in the development environment. Adjust the values as needed for hosted infrastructure.

```shell
cli env seed preview --from development --interactive
```

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

### GET /v1/organizations/{slug}/entitlements

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/vanity-subdomains/activate/SIDE_EFFECTS.md

Retrieves the feature entitlements for a specific organization.

```APIDOC
## GET /v1/organizations/{slug}/entitlements

### Description
Retrieves feature entitlements for an organization by its slug.

### Method
GET

### Endpoint
`/v1/organizations/{slug}/entitlements`

### Authentication
Bearer token

### Parameters
#### Path Parameters
- **slug** (string) - Required - The organization slug identifier.

### Request Body
None

### Response
#### Success Response Fields
- **entitlements** (array) - List of feature entitlement objects containing `feature.key` and `hasAccess`.
```

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

### Run or generate the docs site using pnpm

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

Provides commands to generate documentation pages and start the Next.js development server or run the standalone generation task from the repository root.

```sh
# From the repository root:
pnpm run dev:docs    # Generate command pages, then start the Next.js dev server

# To generate pages without starting the server:
pnpm --filter @supabase/docs run generate
```

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

### GET /v1/projects/{ref}

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/sso/update/SIDE_EFFECTS.md

Retrieves project details such as organization information and name.

```APIDOC
## GET /v1/projects/{ref}

### Description
Retrieves metadata for a specific project reference, including organization identifier and slug.

### Method
GET

### Endpoint
`/v1/projects/{ref}`

### Authentication
Bearer token

### Parameters
#### Path Parameters
- **ref** (string) - Required - The project reference.

### Request Body
None

### Response
#### Success Response (200)
- **ref** (string) - Project reference.
- **name** (string) - Project name.
- **organization_id** (string) - Organization ID.
- **organization_slug** (string) - Organization slug.
```

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

### GET /v1/projects/{ref}

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/notebooks/push/SIDE_EFFECTS.md

Retrieves project details for a specific project reference.

```APIDOC
## GET /v1/projects/{ref}

### Description
Retrieves project details for a specified project reference.

### Method
GET

### Endpoint
`/v1/projects/{ref}`

### Authentication
Bearer token

### Parameters
#### Path Parameters
- **ref** (string) - Required - The project reference.
```

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

### View CLI usage for supabase migration

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

Displays available subcommands and flags for managing database migration scripts.

```text
Manage database migration scripts

Usage:
  supabase migration [command]

Aliases:
  migration, migrations

Available Commands:
  down        Resets applied migrations up to the last n versions
  fetch       Fetch migration files from history table
  list        List local and remote migrations
  new         Create an empty migration script
  repair      Repair the migration history table
  squash      Squash migrations to a single file
  up          Apply pending migrations to local database

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

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

### GET /v1/projects

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/notebooks/pull/SIDE_EFFECTS.md

Lists projects accessible to the authenticated user for project selection.

```APIDOC
## GET /v1/projects

### Description
Retrieves projects accessible to the user, used for interactive project selection.

### Method
GET

### Endpoint
`/v1/projects`

### Authentication
Bearer token

### Response
#### Success Response
- **id** (string) - Project ID
- **name** (string) - Project name
- **organization_slug** (string) - Organization slug
- **region** (string) - Region identifier
```

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

### Example output for db-replication-slots

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

Displays the active status, WAL sender state, replication client address, and replication lag in gigabytes for logical replication slots configured on the database.

```text
                       NAME                    │ ACTIVE │ STATE   │ REPLICATION CLIENT ADDRESS │ REPLICATION LAG GB
  ─────────────────────────────────────────────┼────────┼─────────┼────────────────────────────┼─────────────────────
    supabase_realtime_replication_slot         │ t      │ N/A     │ N/A                        │                  0
    datastream                                 │ t      │ catchup │ 24.201.24.106              │                 45
```

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

### Load CLI configuration using Effect and BunServices

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

Loads project CLI configuration from the current working directory using CliConfigStore and Effect with BunServices.layer.

```ts
import {
  CliConfigSchema,
  CliConfigStore,
  cliConfigStoreLayer,
  type CliConfig,
} from "@supabase/config/effect";
import { BunServices } from "@effect/platform-bun";
import { Effect, Layer } from "effect";

const layer = cliConfigStoreLayer.pipe(Layer.provide(BunServices.layer));

const loaded = await Effect.runPromise(
  Effect.gen(function* () {
    const store = yield* CliConfigStore;
    return yield* store.load(process.cwd());
  }).pipe(Effect.provide(layer)),
);
```

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

### GET /v1/projects

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/functions/deploy/SIDE_EFFECTS.md

Lists available projects. Requires Bearer token authentication.

```APIDOC
## GET /v1/projects

### Description
Retrieves a list of available projects.

### Method
GET

### Endpoint
/v1/projects

### Authentication
- **Bearer token** - Required

### Response
#### Success Response
- Array of projects: `[{id, name, organization_slug, region}]`
```

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

### Mermaid diagram: Database, pg-meta, and Studio dependency flow

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

Illustrates the explicit dependency edges between service instances. The Database instance must be ready before pg-meta launches, and pg-meta must be ready before Studio launches. This reflects that each service has its own lifecycle and health, and composition declares the edges explicitly.

```mermaid
flowchart LR
    Database["Database instance"] -->|ready before launch| PgMeta["pg-meta instance"]
    PgMeta -->|ready before launch| Studio["Studio instance"]
```

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

### GET /v1/projects/{ref}

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/network-bans/remove/SIDE_EFFECTS.md

Retrieves project information for a specific project reference.

```APIDOC
## GET /v1/projects/{ref}

### Description
Fetches details of a project by its reference.

### Method
GET

### Endpoint
`/v1/projects/{ref}`

### Authentication
Bearer token

### Parameters
#### Path Parameters
- **ref** (string) - Required - The project reference.

### Response
- **ref** (string) - Project reference
- **name** (string) - Project name
- **organization_id** (string) - Organization ID
- **organization_slug** (string) - Organization slug
```

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

### GET /v1/projects/{ref}

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/experimental/compute/push/SIDE_EFFECTS.md

Fetches metadata for a single project by reference ID.

```APIDOC
## GET /v1/projects/{ref}

### Description
Retrieves specific project details using its project reference identifier.

### Method
GET

### Endpoint
`/v1/projects/{ref}`

### Authentication
Bearer token

### Parameters
#### Path Parameters
- **ref** - Project reference ID

### Request Body
None

### Response
- **ref** - Project reference ID
- **name** - Project name
- **organization_id** - Organization ID
- **organization_slug** - Organization slug
```

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

### GET /v1/projects/{ref}

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/experimental/compute/delete/SIDE_EFFECTS.md

Retrieves details for a single project by reference ID.

```APIDOC
## GET /v1/projects/{ref}

### Description
Retrieves project metadata by its project reference.

### Method
GET

### Endpoint
`/v1/projects/{ref}`

### Parameters
#### Path Parameters
- **ref** - Required - The project reference identifier.

### Response
#### Success Response
- **ref** - Project reference identifier.
- **name** - Project name.
- **organization_id** - Identifier of the organization.
- **organization_slug** - Slug of the organization.
```

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

### Run root Turbo entrypoints for live and auxiliary workflows

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

Executes build, code generation, targeted workspace build, and live test workflows using root Turbo entrypoints.

```sh
pnpm run build
pnpm run generate
pnpm exec turbo run supabase#build
pnpm run test:live
```

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

### GET /v1/projects

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/experimental/compute/delete/SIDE_EFFECTS.md

Retrieves the list of available projects for populating project selection.

```APIDOC
## GET /v1/projects

### Description
Fetches all projects accessible by the authenticated user.

### Method
GET

### Endpoint
`/v1/projects`

### Response
#### Success Response
- **id** - Project identifier.
- **name** - Project name.
- **organization_slug** - Slug of the organization.
- **region** - Region of the project.
```

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

### Missing environment variable warning output

Source: https://github.com/supabase/cli/blob/develop/docs/environments-management.md

Displays the CLI startup warning and resolution guidance generated when a function references an unset environment variable.

```text
Warning: functions.payment-webhook.env references missing variables:
  STRIPE_KEY (from env(STRIPE_KEY))

Set it with:
  cli env set STRIPE_KEY "your-value" --env development --secret
```

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

### Run tests and commit repository changes (GREEN phase)

Source: https://github.com/supabase/cli/blob/develop/docs/superpowers/plans/2026-08-16-cli-2110-managed-port-allocation.md

Run integration tests and linters to verify passing status, then stage and commit modified repository files.

```bash
pnpm --filter @supabase/stack exec vitest run --project integration src/managed-service.integration.test.ts
pnpm --filter @supabase/stack check:all
git add packages/stack/src/managed/repository.ts packages/stack/src/managed/repository-memory.ts packages/stack/src/managed/sqlite.ts packages/stack/src/managed-service.integration.test.ts
git commit -m "feat(stack): enforce managed port ownership matrix"
```

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

### GET /v2/projects/{ref}/config

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/config/push/SIDE_EFFECTS.md

Reads the effective configuration for a specific project.

```APIDOC
## GET /v2/projects/{ref}/config

### Description
Fetches effective project config (the only read this command makes).

### Method
GET

### Endpoint
`/v2/projects/{ref}/config`

### Parameters
#### Path Parameters
- **ref** (string) - Required - Project reference

### Response
#### Success Response (200)
```

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

### GET /v1/organizations/{slug}/entitlements

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/sso/update/SIDE_EFFECTS.md

Retrieves feature entitlements and access permissions for an organization.

```APIDOC
## GET /v1/organizations/{slug}/entitlements

### Description
Retrieves the feature entitlements for a specified organization slug.

### Method
GET

### Endpoint
`/v1/organizations/{slug}/entitlements`

### Authentication
Bearer token

### Parameters
#### Path Parameters
- **slug** (string) - Required - The organization slug.

### Request Body
None

### Response
#### Success Response (200)
- **entitlements** (array) - List of entitlements.
  - **feature.key** (string) - Entitlement feature key.
  - **hasAccess** (boolean) - Whether the organization has access to the feature.
```

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

### Bootstrap a project using supabase bootstrap

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

Bootstraps a new Supabase project from a starter template with flags for authentication and database password specification.

```text
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.
```

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

### Inspect database queries ordered by number of calls

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

Shows example output of database queries ordered by call frequency, execution times, and proportion of total execution time.

```text

                        QUERY                      │ TOTAL EXECUTION TIME │ PROPORTION OF TOTAL EXEC TIME │ NUMBER CALLS │  SYNC IO TIME
  ─────────────────────────────────────────────────┼──────────────────────┼───────────────────────────────┼──────────────┼──────────────────
    SELECT * FROM users WHERE id = $1              │ 14:50:11.828939      │ 89.8%                         │  183,389,757 │ 00:00:00.002018
    SELECT * FROM user_events                      │ 01:20:23.466633      │ 1.4%                          │       78,325 │ 00:00:00
    INSERT INTO users (email, name) VALUES ($1, $2)│ 00:40:11.616882      │ 0.8%                          │       54,003 │ 00:00:00.000322

```

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

### GET /v1/projects/{ref}

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/ssl-enforcement/update/SIDE_EFFECTS.md

Retrieves detailed information for a specific project by reference ID.

```APIDOC
## GET /v1/projects/{ref}

### Description
Retrieves project details for a specific project.

### Method
GET

### Endpoint
`/v1/projects/{ref}`

### Authentication
- **Bearer token**

### Parameters
#### Path Parameters
- **ref** (string) - Required - The project reference identifier

### Response
#### Success Response Fields
- **ref** (string)
- **name** (string)
- **organization_id** (string)
- **organization_slug** (string)

### Response Example
```json
{
  "ref": "string",
  "name": "string",
  "organization_id": "string",
  "organization_slug": "string"
}
```
```

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

### Build CLI documentation spec

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

Runs the documentation generator script using Bun and outputs the spec to cli_v1_commands.yaml.

```bash
bun scripts/generate-docs-spec.ts > cli_v1_commands.yaml
```

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

### GET /v1/projects/{ref}

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/postgres-config/update/SIDE_EFFECTS.md

Retrieves metadata and details for a specific project by its reference identifier.

```APIDOC
## GET /v1/projects/{ref}

### Description
Retrieves project details for a specific project reference.

### Method
GET

### Endpoint
`/v1/projects/{ref}`

### Authentication
Bearer token

### Parameters
#### Path Parameters
- **ref** (string) - Required - Project reference identifier

### Response
#### Success Response (200)
- **ref** (string) - Project reference identifier
- **name** (string) - Project name
- **organization_id** (string) - Organization identifier
- **organization_slug** (string) - Organization slug
```

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

### Pull summary text output format

Source: https://github.com/supabase/cli/blob/develop/apps/cli/src/commands/pull/SIDE_EFFECTS.md

Example of the aligned per-step summary block printed when using `--output-format text`. Shows the status of each step in the order: config, migration_history, db, functions.

```text
Pull summary — project <ref>
  config              changed    supabase/config.toml
  migration_history   skipped    (not_needed)
  db                  changed    supabase/migrations/<timestamp>_remote_schema.sql
  functions           unchanged
```
Tokens:
Raw