clispec: '001'
info:
  id: cli
  version: 2.119.0
  title: Supabase CLI
  language: sh
  source: https://github.com/supabase/cli
  bugs: https://github.com/supabase/cli/issues
  spec: https://github.com/supabase/spec/cli_v1_commands.yaml
  description: Supabase CLI provides you with tools to develop your application locally, and deploy your application to the Supabase platform.
  tags:
    - id: quick-start
      title: Quick Start
    - id: local-dev
      title: Local Development
    - id: management-api
      title: Management APIs
    - id: other-commands
      title: Additional Commands
flags:
  - id: agent
    name: --agent <[ auto | yes | no ]>
    description: 'Override agent detection: yes, no, or auto (default auto)'
    default_value: auto
    accepted_values:
      - id: auto
        name: auto
        type: '[ auto | yes | no ]'
      - id: 'yes'
        name: 'yes'
        type: '[ auto | yes | no ]'
      - id: 'no'
        name: 'no'
        type: '[ auto | yes | no ]'
  - id: create-ticket
    name: --create-ticket
    description: create a support ticket for any CLI error
    default_value: 'false'
  - id: debug
    name: --debug
    description: output debug logs to stderr
    default_value: 'false'
  - id: dns-resolver
    name: --dns-resolver <[ native | https ]>
    description: lookup domain names using the specified resolver
    default_value: native
    accepted_values:
      - id: native
        name: native
        type: '[ native | https ]'
      - id: https
        name: https
        type: '[ native | https ]'
  - id: experimental
    name: --experimental
    description: enable experimental features
    default_value: 'false'
  - id: help
    name: -h, --help
    description: Show help information
    default_value: 'false'
  - id: network-id
    name: --network-id <string>
    description: use the specified docker network instead of a generated one
    default_value: ''
  - id: output
    name: -o, --output <[ env | pretty | json | toml | yaml ]>
    description: output format of status variables
    default_value: pretty
    accepted_values:
      - id: env
        name: env
        type: '[ env | pretty | json | toml | yaml ]'
      - id: pretty
        name: pretty
        type: '[ env | pretty | json | toml | yaml ]'
      - id: json
        name: json
        type: '[ env | pretty | json | toml | yaml ]'
      - id: toml
        name: toml
        type: '[ env | pretty | json | toml | yaml ]'
      - id: yaml
        name: yaml
        type: '[ env | pretty | json | toml | yaml ]'
  - id: output-format
    name: --output-format <[ text | json | stream-json ]>
    description: 'Output format: text (default), json, or stream-json (NDJSON)'
    default_value: text
    accepted_values:
      - id: text
        name: text
        type: '[ text | json | stream-json ]'
      - id: json
        name: json
        type: '[ text | json | stream-json ]'
      - id: stream-json
        name: stream-json
        type: '[ text | json | stream-json ]'
  - id: profile
    name: --profile <string>
    description: use a specific profile for connecting to Supabase API
    default_value: supabase
  - id: workdir
    name: --workdir <string>
    description: path to the directory containing your supabase/ folder; used exactly as given, with no ancestor directory search (defaults to searching upward from the current directory)
    default_value: ''
  - id: 'yes'
    name: --yes
    description: answer yes to all prompts
    default_value: 'false'
commands:
  - id: supabase-backups
    title: supabase backups
    summary: Manage Supabase physical backups
    description: Manage Supabase physical backups.
    tags:
      - management-api
    links: []
    subcommands:
      - supabase-backups-list
      - supabase-backups-restore
    flags: []
  - id: supabase-backups-list
    title: supabase backups list
    summary: Lists available physical backups
    description: Lists available physical backups
    examples:
      - id: example-1
        name: List all physical backups
        code: supabase backups list
      - id: example-2
        name: List backups for a specific project
        code: supabase backups list --project-ref <ref>
    tags: []
    links: []
    usage: supabase backups list [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-backups-restore
    title: supabase backups restore
    summary: Restore to a specific timestamp using PITR
    description: Restore to a specific timestamp using PITR
    examples:
      - id: example-1
        name: Restore to the given Unix epoch timestamp
        code: supabase backups restore --timestamp 1707407047
    tags: []
    links: []
    usage: supabase backups restore [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: timestamp
        name: -t, --timestamp <int>
        description: The recovery time target in seconds since epoch.
        default_value: '0'
  - id: supabase-bootstrap
    title: supabase bootstrap
    summary: Bootstrap a Supabase project from a starter template
    description: Bootstrap a Supabase project from a starter template.
    tags:
      - quick-start
    links: []
    usage: supabase bootstrap [template] [flags]
    subcommands: []
    flags:
      - id: password
        name: -p, --password <string>
        description: Password to your remote Postgres database.
        default_value: ''
  - id: supabase-branches
    title: supabase branches
    summary: Manage preview branches
    description: Manage Supabase preview branches.
    tags:
      - management-api
    links: []
    subcommands:
      - supabase-branches-create
      - supabase-branches-delete
      - supabase-branches-get
      - supabase-branches-list
      - supabase-branches-pause
      - supabase-branches-unpause
      - supabase-branches-update
    flags: []
  - id: supabase-branches-create
    title: supabase branches create
    summary: Create a preview branch
    description: Create a preview branch for the linked project.
    tags: []
    links: []
    usage: supabase branches create [name] [flags]
    subcommands: []
    flags:
      - id: git-branch
        name: --git-branch <string>
        description: Associate a git branch with the new preview branch.
        default_value: ''
      - id: notify-url
        name: --notify-url <string>
        description: URL to notify when branch is active healthy.
        default_value: ''
      - id: persistent
        name: --persistent
        description: Whether to create a persistent branch.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: region
        name: --region <string>
        description: Select a region to deploy the branch database.
        default_value: ''
        accepted_values:
          - id: ap-east-1
            name: ap-east-1
            type: string
          - id: ap-northeast-1
            name: ap-northeast-1
            type: string
          - id: ap-northeast-2
            name: ap-northeast-2
            type: string
          - id: ap-south-1
            name: ap-south-1
            type: string
          - id: ap-southeast-1
            name: ap-southeast-1
            type: string
          - id: ap-southeast-2
            name: ap-southeast-2
            type: string
          - id: ca-central-1
            name: ca-central-1
            type: string
          - id: eu-central-1
            name: eu-central-1
            type: string
          - id: eu-central-2
            name: eu-central-2
            type: string
          - id: eu-north-1
            name: eu-north-1
            type: string
          - id: eu-west-1
            name: eu-west-1
            type: string
          - id: eu-west-2
            name: eu-west-2
            type: string
          - id: eu-west-3
            name: eu-west-3
            type: string
          - id: sa-east-1
            name: sa-east-1
            type: string
          - id: us-east-1
            name: us-east-1
            type: string
          - id: us-east-2
            name: us-east-2
            type: string
          - id: us-west-1
            name: us-west-1
            type: string
          - id: us-west-2
            name: us-west-2
            type: string
      - id: size
        name: --size <string>
        description: Select a desired instance size for the branch database.
        default_value: ''
        accepted_values:
          - id: large
            name: large
            type: string
          - id: medium
            name: medium
            type: string
          - id: micro
            name: micro
            type: string
          - id: 12xlarge
            name: 12xlarge
            type: string
          - id: 16xlarge
            name: 16xlarge
            type: string
          - id: 24xlarge
            name: 24xlarge
            type: string
          - id: 24xlarge_high_memory
            name: 24xlarge_high_memory
            type: string
          - id: 24xlarge_optimized_cpu
            name: 24xlarge_optimized_cpu
            type: string
          - id: 24xlarge_optimized_memory
            name: 24xlarge_optimized_memory
            type: string
          - id: 2xlarge
            name: 2xlarge
            type: string
          - id: 48xlarge
            name: 48xlarge
            type: string
          - id: 48xlarge_high_memory
            name: 48xlarge_high_memory
            type: string
          - id: 48xlarge_optimized_cpu
            name: 48xlarge_optimized_cpu
            type: string
          - id: 48xlarge_optimized_memory
            name: 48xlarge_optimized_memory
            type: string
          - id: 4xlarge
            name: 4xlarge
            type: string
          - id: 8xlarge
            name: 8xlarge
            type: string
          - id: small
            name: small
            type: string
          - id: xlarge
            name: xlarge
            type: string
      - id: with-data
        name: --with-data
        description: Whether to clone production data to the branch database.
        default_value: 'false'
  - id: supabase-branches-delete
    title: supabase branches delete
    summary: Delete a preview branch
    description: Delete a preview branch by its name or ID.
    tags: []
    links: []
    usage: supabase branches delete [name] [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-branches-get
    title: supabase branches get
    summary: Retrieve details of a preview branch
    description: |-
      Retrieve details of the specified preview branch.

      Note: For the main branch, password-dependent fields (POSTGRES_URL, POSTGRES_URL_NON_POOLING) are not populated because production database credentials are not retrievable via API.
    tags: []
    links: []
    usage: supabase branches get [name] [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-branches-list
    title: supabase branches list
    summary: List all preview branches
    description: List all preview branches of the linked project.
    tags: []
    links: []
    usage: supabase branches list [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-branches-pause
    title: supabase branches pause
    summary: Pause a preview branch
    description: Pause a preview branch.
    tags: []
    links: []
    usage: supabase branches pause [name] [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-branches-unpause
    title: supabase branches unpause
    summary: Unpause a preview branch
    description: Unpause a preview branch.
    tags: []
    links: []
    usage: supabase branches unpause [name] [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-branches-update
    title: supabase branches update
    summary: Update a preview branch
    description: Update a preview branch by its name or ID.
    tags: []
    links: []
    usage: supabase branches update [name] [flags]
    subcommands: []
    flags:
      - id: git-branch
        name: --git-branch <string>
        description: Change the associated git branch.
        default_value: ''
      - id: name
        name: --name <string>
        description: Rename the preview branch.
        default_value: ''
      - id: notify-url
        name: --notify-url <string>
        description: URL to notify when branch is active healthy.
        default_value: ''
      - id: persistent
        name: --persistent
        description: Switch between ephemeral and persistent branch.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: status
        name: --status <string>
        description: Override the current branch status.
        default_value: ''
        accepted_values:
          - id: RUNNING_MIGRATIONS
            name: RUNNING_MIGRATIONS
            type: string
          - id: MIGRATIONS_PASSED
            name: MIGRATIONS_PASSED
            type: string
          - id: MIGRATIONS_FAILED
            name: MIGRATIONS_FAILED
            type: string
          - id: FUNCTIONS_DEPLOYED
            name: FUNCTIONS_DEPLOYED
            type: string
          - id: FUNCTIONS_FAILED
            name: FUNCTIONS_FAILED
            type: string
  - id: supabase-completion
    title: supabase completion
    summary: Generate the autocompletion script for the specified shell
    description: |-
      Generate the autocompletion script for supabase for the specified shell.
      See each sub-command's help for details on how to use the generated script.
    tags:
      - other-commands
    links: []
    subcommands:
      - supabase-completion-bash
      - supabase-completion-fish
      - supabase-completion-powershell
      - supabase-completion-zsh
    flags: []
  - id: supabase-completion-bash
    title: supabase completion bash
    summary: Generate the autocompletion script for bash
    description: |-
      Generate the autocompletion script for the bash shell.

      This script depends on the 'bash-completion' package.
      If it is not installed already, you can install it via your OS's package manager.

      To load completions in your current shell session:

          source <(supabase completion bash)

      To load completions for every new session, execute once:

      #### Linux:

          supabase completion bash > /etc/bash_completion.d/supabase

      #### macOS:

          supabase completion bash > $(brew --prefix)/etc/bash_completion.d/supabase

      You will need to start a new shell for this setup to take effect.
    tags: []
    links: []
    usage: supabase completion bash [flags]
    subcommands: []
    flags:
      - id: no-descriptions
        name: --no-descriptions
        description: disable completion descriptions
        default_value: 'false'
  - id: supabase-completion-fish
    title: supabase completion fish
    summary: Generate the autocompletion script for fish
    description: |-
      Generate the autocompletion script for the fish shell.

      To load completions in your current shell session:

          supabase completion fish | source

      To load completions for every new session, execute once:

          supabase completion fish > ~/.config/fish/completions/supabase.fish

      You will need to start a new shell for this setup to take effect.
    tags: []
    links: []
    usage: supabase completion fish [flags]
    subcommands: []
    flags:
      - id: no-descriptions
        name: --no-descriptions
        description: disable completion descriptions
        default_value: 'false'
  - id: supabase-completion-powershell
    title: supabase completion powershell
    summary: Generate the autocompletion script for powershell
    description: |-
      Generate the autocompletion script for powershell.

      To load completions in your current shell session:

          supabase completion powershell | Out-String | Invoke-Expression

      To load completions for every new session, add the output of the above command
      to your powershell profile.
    tags: []
    links: []
    usage: supabase completion powershell [flags]
    subcommands: []
    flags:
      - id: no-descriptions
        name: --no-descriptions
        description: disable completion descriptions
        default_value: 'false'
  - id: supabase-completion-zsh
    title: supabase completion zsh
    summary: Generate the autocompletion script for zsh
    description: |-
      Generate the autocompletion script for the zsh shell.

      If shell completion is not already enabled in your environment you will need
      to enable it.  You can execute the following once:

          echo "autoload -U compinit; compinit" >> ~/.zshrc

      To load completions in your current shell session:

          source <(supabase completion zsh)

      To load completions for every new session, execute once:

      #### Linux:

          supabase completion zsh > "${fpath[1]}/_supabase"

      #### macOS:

          supabase completion zsh > $(brew --prefix)/share/zsh/site-functions/_supabase

      You will need to start a new shell for this setup to take effect.
    tags: []
    links: []
    usage: supabase completion zsh [flags]
    subcommands: []
    flags:
      - id: no-descriptions
        name: --no-descriptions
        description: disable completion descriptions
        default_value: 'false'
  - id: supabase-config
    title: supabase config
    summary: Manage project configurations
    description: Manage Supabase project configurations.
    tags:
      - management-api
    links: []
    subcommands:
      - supabase-config-diff
      - supabase-config-pull
      - supabase-config-push
    flags: []
  - id: supabase-config-diff
    title: supabase config diff
    summary: Diff local config against a remote project
    description: |


      Shows the configuration differences between the local `supabase/config.toml` and the effective configuration of a remote project or branch. Read-only: it never modifies the local file or any remote configuration.

      Pass `--project-ref` to compare against a specific project, or the name (or UUID) of a branch of the currently linked project — values that are exactly 20 lowercase letters are always treated as project refs. Without it, the linked project is the target. When the target ref matches a `[remotes.*]` block's `project_id`, that block's merged config is the local side of the comparison.

      Only platform-managed properties are compared. Local-stack-only sections — `[studio]`, `[analytics]`, `[functions]`, `[edge_runtime]`, port numbers, image version pins, `[db.migrations]`, and similar — have no hosted counterpart and are never reported, whether or not your file declares them.

      Each difference is classified as `update` (the file declares a value that differs remotely), `remote-only` (the remote differs while the file is silent — the shown local value is the schema default a `config push` would write), or `local-only` (the file declares a value the remote did not report). `(unset)` means the local side has no value at all; `(not returned)` means the response did not carry the property. Secret values are never compared — the platform only reports digests — and are listed in a masked-credentials note instead, as are declared properties that `config push` cannot communicate and any block the response omitted entirely.

      Local values are shown as the configuration your file would produce once pushed, not its literal spelling: a duration written as `"1m"` renders as `"1m0s"`, and byte sizes are shown in the units you wrote.

      With `--exit-code`, the command exits `2` when any difference is found, keeping exit `1` for errors — so scripts can distinguish drift from failure.

      Machine-readable output is available through `--output-format json|stream-json` — a versioned payload (`schema_version`, `config_schema`, `target`, `scope`, `changes[]`, `masked[]`, `unmanaged[]`, `counts`) with per-change `path`s as segment arrays. The legacy global `-o`/`--output` flag is not supported by this command; use `--output-format json|stream-json` instead.
    examples:
      - id: example-1
        name: Diff against the linked project
        code: supabase config diff
      - id: example-2
        name: Diff against the 'staging' branch, exiting 2 on drift
        code: supabase config diff --project-ref staging --exit-code
    tags: []
    links: []
    usage: supabase config diff [flags]
    subcommands: []
    flags:
      - id: exit-code
        name: --exit-code
        description: Exit with status 2 when any difference is found (errors keep exiting 1).
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project, or the name (or UUID) of one of its branches. Values that are exactly 20 lowercase letters are always treated as project refs.
        default_value: ''
  - id: supabase-config-pull
    title: supabase config pull
    summary: Pull remote config into supabase/config.toml
    description: |


      Writes the effective configuration of a remote project or branch into the local `supabase/config.toml`/`config.json` — the write side of `supabase config diff`. Every write is a surgical, format-preserving edit: comments, key ordering, and quoting elsewhere in the file are left untouched, and only the values that actually change are rewritten.

      Pass `--project-ref` to pull from a specific project, or the name (or UUID) of a branch of the currently linked project — values that are exactly 20 lowercase letters are always treated as project refs. Without it, the linked project is the target.

      Where a pulled value lands depends on whether the target is already tracked by a `[remotes.*]` block, not on how you named it: if any block's `project_id` already matches the resolved ref, that block is reused — whatever its own label — and every value lands there. Otherwise, if the target was named as a branch, a new `[remotes.<branch-name>]` block is created (a branch resolved by UUID falls back to the project ref itself as its label). Only when neither applies — a bare `--project-ref` naming a project directly, or the linked project with no branch involved — do values land at the config root. `--remote-label` overrides the block config pull would otherwise reuse or create; naming a block that already tracks a different project, or naming nothing while a different block already tracks this exact ref, is an error rather than a silent overwrite. A `[remotes.*]` block whose `project_id` is an `env(...)` reference that merely _resolves_ to the target ref is never reused or rewritten — that is a hard error naming the variable, since a value written there would never actually take effect on the next load. Creating a new block always writes its `project_id`, even when every value it would otherwise carry already matches the local defaults — otherwise the block could never be reused on a later pull.

      Writing to the config root can also affect `supabase start`: a handful of root-scoped settings — `auth.site_url`, `db.settings.*`, `db.major_version` (which changes what `supabase start` boots), `db.pooler.*`, and similar — also govern the local stack, so pulling a hosted value into them is a real change to local dev behavior, not just a record of the hosted project's own setting. `config pull` warns about this rather than refusing; writing the same value into a `[remotes.*]` block is unaffected. Passing `--remote-label` is the escape hatch: it diverts what would otherwise be a root-bound pull into a `[remotes.<label>]` block instead, leaving local dev untouched.

      Several kinds of values are never written, and are reported instead of silently skipped: a value whose local declaration resolves from an `env(VAR)` reference (reported by variable name — replace the reference yourself, or pass `--remote-label` to target a different block); a value the REMOTE itself spells as an `env(VAR)` reference (`remote_env_reference`) — the loader would resolve it against the local environment on the next load, so writing it verbatim would let a remote value read whatever this machine's environment holds at that name; secret values, which the platform never returns in plaintext (a masked-credentials note); a value the file declares that the remote does not report (`local-only` — never removed); and a handful of already-declared properties `config push` cannot communicate back at all (an unmanaged note). Local-stack-only sections — `[studio]`, `[analytics]`, `[functions]`, `[edge_runtime]`, port numbers, image version pins, and similar — have no hosted counterpart and are never touched. One family of properties is written despite `config push` having no way to send it back (`auth.oauth_server`, disabled `storage.analytics`/`storage.vector`, …) — pulling still records the hosted value, with a warning that it cannot be pushed back.

      `config pull` never writes a `config.toml`/`.json` it cannot load back on the next command. Pulling a value that GATES other declared fields — e.g. flipping a disabled provider's `enabled` on — also pulls its now-required sibling values into the same write (not just the gate), so the file never comes out half-configured. When one of those siblings genuinely can't be supplied — the remote doesn't report it, or supplying it would still leave a REQUIRED value missing — the whole toggle is skipped instead, reported with a new reason (`requires values pull cannot write` in text output, `would_invalidate` in the machine payload) plus a note naming the missing field(s) and, when a missing field's local spelling is itself an unresolved `env(VAR)` reference, the exact environment variable to set before rerunning.

      `--dry-run` computes and prints exactly what `config diff` would show, then stops — no git check, no prompt, no write. `--output-format json|stream-json` never prompts at all — it returns the confirmation's default value without reading anything, so use `--dry-run` for a preview in those shapes rather than relying on the prompt. A non-interactive run in the default text format (no TTY on stdin) still prints the confirmation to stderr and reads a single line from piped stdin: an explicit `y`/`yes`/`n`/`no` answer is honored, an empty line falls back to the default, and any other answer declines. `--yes` (or `SUPABASE_YES`) answers the confirmation prompt without asking on an interactive TTY; it does not bypass the uncommitted-changes guard — on the contrary, `--yes` together with uncommitted (or untracked) changes aborts instead of silently overwriting them, since no human is left to read the warning. `--force` writes even when `supabase/config.toml` has uncommitted or untracked changes in git — without it, an interactive run's prompt defaults to "no" instead of "yes", and every other case (non-interactive text, machine-format, or `--yes` on any TTY) aborts outright.

      A second `config pull` against an already-tracked, unchanged remote always writes nothing — that convergence is the design's own acceptance property, not a special case. It never even checks for uncommitted local changes to the config file in that case, since there is nothing to write either way. A target that isn't tracked yet (a branch or `--remote-label` name with no existing `[remotes.*]` block) still creates that block on its first pull, even when every value it carries already matches the local defaults — it's the second pull against that now-tracked block that then writes nothing.

      ## Example

      Given `supabase/config.toml`:

      ```toml
      project_id = "abcdefghijklmnopqrst"

      [api]
      enabled = true
      max_rows = 1000
      ```

      `supabase config pull --project-ref staging`, where `staging` is a branch of the linked project and no existing `[remotes.*]` block already tracks it, creates a new block at the end of the file — `max_rows` lands under its own `[remotes.staging.api]` sub-table, the same way `[api]` itself is a sub-table of the document root, not a key directly under `[remotes.staging]`:

      ```toml
      project_id = "abcdefghijklmnopqrst"

      [api]
      enabled = true
      max_rows = 1000

      [remotes.staging]
      project_id = "cccccccccccccccccccc"

      [remotes.staging.api]
      max_rows = 250
      ```

      Running the same command again finds no differences and writes nothing.

      Machine-readable output is available through `--output-format json|stream-json` — a versioned payload (`schema_version`, `config_schema`, `config_path`, `format`, `target`, `destination`, `dry_run`, `wrote`, `scope`, `changes[]`, `warnings[]`, `masked[]`, `unmanaged[]`, `counts`) with per-change `path`s as segment arrays, each carrying `written` and, when unwritten, a `skipped_reason` (`env_reference | local_only | remote_env_reference | unwritable | would_invalidate | declined | dry_run`). A `would_invalidate` warning additionally carries `missing_fields` (`[{path, env_variable?}]`) naming what actually blocked the family. The legacy global `-o`/`--output` flag is not supported by this command; use `--output-format json|stream-json` instead. Note: the payload spells the root scope `"base"` (`target.local_scope`), while text output calls the same thing `config root`.
    examples:
      - id: example-1
        name: Pull from the linked project into the config root
        code: supabase config pull
      - id: example-2
        name: Pull from the 'staging' branch into [remotes.staging]
        code: supabase config pull --project-ref staging
      - id: example-3
        name: Preview the changes without writing the config file
        code: supabase config pull --dry-run
    tags: []
    links: []
    usage: supabase config pull [flags]
    subcommands: []
    flags:
      - id: dry-run
        name: --dry-run
        description: Show what would be written without touching the config file.
        default_value: 'false'
      - id: force
        name: --force
        description: Write even when supabase/config.toml has uncommitted changes in git.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project, or the name (or UUID) of one of its branches. Values that are exactly 20 lowercase letters are always treated as project refs.
        default_value: ''
      - id: remote-label
        name: --remote-label <string>
        description: Name of the [remotes.*] block to write into, overriding the block config pull would otherwise reuse or create.
        default_value: ''
  - id: supabase-config-push
    title: supabase config push
    summary: Push local config to linked project
    description: |


      Updates the configurations of a linked Supabase project with the local `supabase/config.toml` file.

      This command allows you to manage project configuration as code by defining settings locally and then pushing them to your remote project.

      Pass `--project-ref` to push to a specific project, or the name (or UUID) of a branch of the currently linked project — values that are exactly 20 lowercase letters are always treated as project refs. Without it, the linked project is the target.

      Before anything is pushed, the command reports the project it resolved — its name and ref. When the resolved target is a preview branch that was only _inferred_ (for example after `supabase link <branch-name>`, or via `SUPABASE_PROJECT_ID`) rather than named on this invocation, it says so, names the branch and its parent project where they can be resolved, and asks for confirmation first. Declining — including on an unattended run with no `--yes` and no piped answer — fails the command rather than pushing. Pass `--yes` (or set `SUPABASE_YES`) to skip that confirmation in CI and scripted runs.

      An explicit `--project-ref <branch-name-or-uuid>` on the same invocation skips the confirmation entirely (the target is still echoed) — naming the branch yourself already counts as confirming it. Because the confirmation reads one line of piped input just like any other prompt, a script piping multiple `y`/`n` answers to an _inferred_ branch target needs one extra leading answer for it, ahead of the per-service prompts it already answers.
    examples:
      - id: example-1
        name: Push local config to the linked project
        code: supabase config push
      - id: example-2
        name: Push local config to a specific project
        code: supabase config push --project-ref abcdefghijklmnopqrst
      - id: example-3
        name: Push local config to the 'staging' branch
        code: supabase config push --project-ref staging
    tags: []
    links: []
    usage: supabase config push [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project, or the name (or UUID) of one of its branches. Values that are exactly 20 lowercase letters are always treated as project refs.
        default_value: ''
  - id: supabase-db
    title: supabase db
    summary: Manage databases
    description: Manage Postgres databases.
    tags:
      - local-dev
    links: []
    subcommands:
      - supabase-db-advisors
      - supabase-db-diff
      - supabase-db-dump
      - supabase-db-lint
      - supabase-db-pull
      - supabase-db-push
      - supabase-db-query
      - supabase-db-reset
      - supabase-db-schema
      - supabase-db-start
    flags: []
  - id: supabase-db-advisors
    title: supabase db advisors
    summary: Checks database for security and performance issues
    description: |


      Inspects the database for common security and performance issues such as missing RLS policies, unindexed foreign keys, exposed auth.users, and more.
    tags: []
    links: []
    usage: supabase db advisors [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Checks the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: fail-on
        name: --fail-on <[ none | info | warn | error ]>
        description: 'Issue level to exit with non-zero status: none, info, warn, error.'
        default_value: none
        accepted_values:
          - id: none
            name: none
            type: '[ none | info | warn | error ]'
          - id: info
            name: info
            type: '[ none | info | warn | error ]'
          - id: warn
            name: warn
            type: '[ none | info | warn | error ]'
          - id: error
            name: error
            type: '[ none | info | warn | error ]'
      - id: level
        name: --level <[ info | warn | error ]>
        description: 'Minimum issue level to display: info, warn, error.'
        default_value: warn
        accepted_values:
          - id: info
            name: info
            type: '[ info | warn | error ]'
          - id: warn
            name: warn
            type: '[ info | warn | error ]'
          - id: error
            name: error
            type: '[ info | warn | error ]'
      - id: linked
        name: --linked
        description: Checks the linked project for issues.
        default_value: 'false'
      - id: local
        name: --local
        description: Checks the local database for issues.
        default_value: 'true'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: type
        name: --type <[ all | security | performance ]>
        description: 'Type of advisors to check: all, security, performance.'
        default_value: all
        accepted_values:
          - id: all
            name: all
            type: '[ all | security | performance ]'
          - id: security
            name: security
            type: '[ all | security | performance ]'
          - id: performance
            name: performance
            type: '[ all | security | performance ]'
  - id: supabase-db-diff
    title: supabase db diff
    summary: Diffs the local database for schema changes
    description: |


      Diffs schema changes made to the local or remote database.

      Requires the local development stack to be running when diffing against the local database. To diff against a remote or self-hosted database, specify the `--linked` or `--db-url` flag respectively.

      Runs [djrobstep/migra](https://github.com/djrobstep/migra) in a container to compare schema differences between the target database and a shadow database. The shadow database is created by applying migrations in local `supabase/migrations` directory in a separate container. Output is written to stdout by default. For convenience, you can also save the schema diff as a new migration file by passing in `-f` flag.

      Explicit `--from`/`--to` mode always uses pg-delta. In this mode, `-f` is ignored and stdout (or `--output`) is a flattened representation for review, not a portable apply script. Do not apply it directly with plain `psql -f`: transactional units can contain `SET LOCAL` preambles that only take effect inside a transaction, while plans that mix transactional and non-transactional units cannot safely be wrapped in one transaction. To create an applicable migration, use normal target mode with `supabase db diff -f <name>`, then apply it through `supabase db reset` locally or `supabase db push` against the linked project. These paths preserve the plan's per-unit transaction semantics.

      By default, all schemas in the target database are diffed. Use the `--schema public,extensions` flag to restrict diffing to a subset of schemas.

      Projects created by a recent `supabase init` default to the pg-delta diff engine (`[experimental.pgdelta] enabled = true` in `config.toml`). Existing projects are unaffected and keep using migra unless they opt in. To fall back to the legacy migra engine, set `enabled = false` under `[experimental.pgdelta]`, or pass `--use-migra` for a single run.

      With the bundled pg-delta engine, diff SQL defaults to uppercase keywords, indent 2, a maximum width of 180, trailing commas, and column/key alignment, matching its declarative export. When `-f` writes migrations, execution-aware transaction semantics are preserved as ordered per-unit files; non-transactional units carry a directive that the CLI apply path honors. Flattened review output retains the rendered SQL and preambles, but not the unit boundaries supplied to a migration runner. Configure overrides with `[experimental.pgdelta] format_options`, or set `format_options = "null"` to emit raw, unformatted statements.

      While the diff command is able to capture most schema changes, there are cases where it is known to fail. Currently, this could happen if you schema contains:

      - Changes to publication
      - Changes to storage buckets
      - Views with `security_invoker` attributes
    examples:
      - id: basic-usage
        name: Basic usage
        code: supabase db diff -f my_table
        response: |
          Connecting to local database...
          Creating shadow database...
          Applying migration 20230425064254_remote_commit.sql...
          Diffing schemas: auth,extensions,public,storage
          Finished supabase db diff on branch main.

          No schema changes found
      - id: linked-project
        name: Against linked project
        code: supabase db diff -f my_table --linked
        response: |
          Connecting to local database...
          Creating shadow database...
          Diffing schemas: auth,extensions,public,storage
          Finished supabase db diff on branch main.

          WARNING: The diff tool is not foolproof, so you may need to manually rearrange and modify the generated migration.
          Run supabase db reset to verify that the new migration does not generate errors.
      - id: specific-schema
        name: For a specific schema
        code: supabase db diff -f my_table --schema auth
        response: |
          Connecting to local database...
          Creating shadow database...
          Diffing schemas: auth
          Finished supabase db diff on branch main.

          No schema changes found
    tags: []
    links: []
    usage: supabase db diff [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Diffs against the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: file
        name: -f, --file <string>
        description: In normal mode, names and saves the complete schema diff as a new migration; it does not filter objects. Ignored with --from/--to.
        default_value: ''
      - id: from
        name: --from <string>
        description: Diff from local, linked, migrations, or a Postgres URL.
        default_value: ''
      - id: linked
        name: --linked
        description: Diffs local migration files against the linked project.
        default_value: 'false'
      - id: local
        name: --local
        description: Diffs local migration files against the local database.
        default_value: 'true'
      - id: output
        name: -o, --output <string>
        description: Write flattened explicit diff SQL to a file for review; this is not a portable apply script.
        default_value: ''
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: schema
        name: -s, --schema <strings>
        description: Comma separated list of schema to include.
        default_value: '[]'
      - id: strict-coverage
        name: --strict-coverage
        description: Fail when bundled pg-delta finds schema objects it cannot manage instead of leaving them unmanaged.
        default_value: 'false'
      - id: to
        name: --to <string>
        description: Diff to local, linked, migrations, or a Postgres URL.
        default_value: ''
      - id: use-migra
        name: --use-migra
        description: Use migra to generate schema diff.
        default_value: 'true'
      - id: use-pg-delta
        name: --use-pg-delta
        description: Use pg-delta to generate schema diff.
        default_value: 'false'
      - id: use-pg-schema
        name: --use-pg-schema
        description: 'Use pg-schema-diff to generate schema diff. Deprecated: use the pg-delta engine ([experimental.pgdelta] enabled = true / --use-pg-delta) or the default migra engine instead.'
        default_value: 'false'
      - id: use-pgadmin
        name: --use-pgadmin
        description: Use pgAdmin to generate schema diff.
        default_value: 'false'
  - id: supabase-db-dump
    title: supabase db dump
    summary: Dumps data or schemas from the remote database
    description: |


      Dumps contents from a remote database.

      Requires your local project to be linked to a remote database by running `supabase link`. For self-hosted databases, you can pass in the connection parameters using `--db-url` flag.

      Runs `pg_dump` in a container with additional flags to exclude Supabase managed schemas. The ignored schemas include auth, storage, and those created by extensions.

      The default dump does not contain any data or custom roles. To dump those contents explicitly, specify either the `--data-only` and `--role-only` flag.

      ### Note on Privilege Migration

      When restoring to a new project, tables inherit ALL privileges from default privileges in the target database. To preserve specific privileges from your dump, revoke defaults before restoring:

      ```sql
      -- Run BEFORE restoring your schema
      ALTER DEFAULT PRIVILEGES IN SCHEMA public REVOKE ALL ON TABLES FROM anon, authenticated;
      ```
    examples:
      - id: basic-usage
        name: Basic usage
        code: supabase db dump -f supabase/schema.sql
        response: |
          Dumping schemas from remote database...
          Dumped schema to supabase/schema.sql.
      - id: role-only
        name: Role only
        code: supabase db dump -f supabase/roles.sql --role-only
        response: |
          Dumping roles from remote database...
          Dumped schema to supabase/roles.sql.
      - id: data-only
        name: Data only
        code: supabase db dump -f supabase/seed.sql --data-only
        response: |
          Dumping data from remote database...
          Dumped schema to supabase/seed.sql.
    tags: []
    links: []
    usage: supabase db dump [flags]
    subcommands: []
    flags:
      - id: data-only
        name: --data-only
        description: Dumps only data records.
        default_value: 'false'
      - id: db-url
        name: --db-url <string>
        description: Dumps from the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: dry-run
        name: --dry-run
        description: Prints the pg_dump script that would be executed.
        default_value: 'false'
      - id: exclude
        name: -x, --exclude <strings>
        description: List of schema.tables to exclude from data-only dump.
        default_value: '[]'
      - id: file
        name: -f, --file <string>
        description: File path to save the dumped contents.
        default_value: ''
      - id: keep-comments
        name: --keep-comments
        description: Keeps commented lines from pg_dump output.
        default_value: 'false'
      - id: linked
        name: --linked
        description: Dumps from the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Dumps from the local database.
        default_value: 'false'
      - id: password
        name: -p, --password <string>
        description: Password to your remote Postgres database.
        default_value: ''
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: role-only
        name: --role-only
        description: Dumps only cluster roles.
        default_value: 'false'
      - id: schema
        name: -s, --schema <strings>
        description: Comma separated list of schema to include.
        default_value: '[]'
      - id: use-copy
        name: --use-copy
        description: Use copy statements in place of inserts.
        default_value: 'false'
  - id: supabase-db-lint
    title: supabase db lint
    summary: Checks local database for typing error
    description: |


      Lints local database for schema errors.

      Requires the local development stack to be running when linting against the local database. To lint against a remote or self-hosted database, specify the `--linked` or `--db-url` flag respectively.

      Runs the `plpgsql_check` extension against the local database (native or container) to check for errors in all schemas. The default lint level is `warning` and can be raised to error via the `--level` flag.

      To lint against specific schemas only, pass in the `--schema` flag.

      The `--fail-on` flag can be used to control when the command should exit with a non-zero status code. The possible values are:

      - `none` (default): Always exit with a zero status code, regardless of lint results.
      - `warning`: Exit with a non-zero status code if any warnings or errors are found.
      - `error`: Exit with a non-zero status code only if errors are found.

      This flag is particularly useful in CI/CD pipelines where you want to fail the build based on certain lint conditions.
    examples:
      - id: basic-usage
        name: Basic usage
        code: supabase db lint
        response: |
          Linting schema: public

          No schema errors found
      - id: schema-warnings
        name: Warnings for a specific schema
        code: supabase db lint --level warning --schema storage
        response: |
          Linting schema: storage
          [
            {
              "function": "storage.search",
              "issues": [
                {
                  "level": "warning",
                  "message": "unused variable \"_bucketid\"",
                  "sqlState": "00000"
                }
              ]
            }
          ]
    tags: []
    links: []
    usage: supabase db lint [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Lints the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: fail-on
        name: --fail-on <[ none | warning | error ]>
        description: Error level to exit with non-zero status.
        default_value: none
        accepted_values:
          - id: none
            name: none
            type: '[ none | warning | error ]'
          - id: warning
            name: warning
            type: '[ none | warning | error ]'
          - id: error
            name: error
            type: '[ none | warning | error ]'
      - id: level
        name: --level <[ warning | error ]>
        description: Error level to emit.
        default_value: warning
        accepted_values:
          - id: warning
            name: warning
            type: '[ warning | error ]'
          - id: error
            name: error
            type: '[ warning | error ]'
      - id: linked
        name: --linked
        description: Lints the linked project for schema errors.
        default_value: 'false'
      - id: local
        name: --local
        description: Lints the local database for schema errors.
        default_value: 'true'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: schema
        name: -s, --schema <strings>
        description: Comma separated list of schema to include.
        default_value: '[]'
  - id: supabase-db-pull
    title: supabase db pull
    summary: Pull schema from the remote database
    description: |


      Pulls schema changes from a remote database. A new migration file will be created under `supabase/migrations` directory.

      Requires your local project to be linked to a remote database by running `supabase link`. For self-hosted databases, you can pass in the connection parameters using `--db-url` flag.

      > Note this command requires Docker Desktop (or a running Docker daemon), as it starts a local Postgres container to diff your remote schema.

      Optionally, a new row can be inserted into the migration history table to reflect the current state of the remote database.

      If no entries exist in the migration history table, the default diff engine uses `pg_dump` to capture all contents of the remote schemas you have created. Otherwise, this command will only diff schema changes against the remote database, similar to running `db diff --linked`.

      Pass `--diff-engine pg-delta` to keep the migration-file `db pull` workflow while using pg-delta for the shadow diff step. On initial pull, pg-delta replaces `pg_dump` and produces the full migration from the shadow diff alone. Pass `--declarative` to switch to the declarative pg-delta export workflow instead.

      pg-delta plans are execution-aware: when a plan crosses a transaction boundary — for example `ALTER TYPE ... ADD VALUE` followed by a statement that uses the new enum value, which cannot run in the same transaction — `db pull` writes one ordered migration file per plan unit instead of a single file (for example `<ts>_remote_schema_schema_changes.sql` and `<ts+1s>_remote_schema_after_enum_values.sql`), each recorded in the migration history. The common case (a single unit) still produces exactly one `<ts>_remote_schema.sql` file.

      By default the emitted SQL is formatted with the same settings the declarative export uses (uppercase keywords, wrapped at a max width of 180, indented and column-aligned). Configure overrides with `[experimental.pgdelta] format_options` in `config.toml`, or set `format_options = "null"` to opt out and emit raw, unformatted statements.

      When `[experimental.pgdelta] enabled = true` (the default for projects created by a recent `supabase init`), the migration-file `db pull` workflow uses pg-delta for the shadow diff step by default; it does not switch to declarative output. Existing projects without the section are unaffected and keep using migra. To fall back to the legacy migra engine, set `enabled = false` under `[experimental.pgdelta]`, or pass `--diff-engine migra` for a single run.

      When pulling from a remote database with `--db-url`, prefer a direct connection (`db.<project-ref>.supabase.co:5432`) over the connection pooler so pg-delta can introspect the full catalog reliably.

      ## Debugging empty pg-delta pulls

      If `db pull --diff-engine pg-delta` reports `No schema changes found` but you expect schema output, set `PGDELTA_DEBUG=1` before running the command. Unlike `--debug`, this keeps SSL enabled for remote Supabase connections.

      ```sh
      PGDELTA_DEBUG=1 supabase db pull --db-url "$DATABASE_URL" --diff-engine pg-delta
      ```

      When pg-delta returns zero statements, the CLI writes a debug bundle under `supabase/.temp/pgdelta/v2/debug/<timestamp>-diff/` containing the source/desired catalog snapshots, the plan, and coverage diagnostics. Catalog files are not written during normal `db pull` runs.

      For TLS tracing without disabling SSL, use `SUPABASE_SSL_DEBUG=true` alongside `PGDELTA_DEBUG=1`.
    examples:
      - id: basic-usage
        name: Basic usage
        code: supabase db pull
        response: |
          Connecting to remote database...
          Schema written to supabase/migrations/20240414044403_remote_schema.sql
          Update remote migration history table? [Y/n]
          Repaired migration history: [20240414044403] => applied
          Finished supabase db pull.
          The auth and storage schemas are excluded. Run supabase db pull --schema auth,storage again to diff them.
      - id: local-studio
        name: Local studio
        code: supabase db pull --local
        response: |
          Connecting to local database...
          Setting up initial schema....
          Creating custom roles supabase/roles.sql...
          Applying migration 20240414044403_remote_schema.sql...
          No schema changes found
          The auth and storage schemas are excluded. Run supabase db pull --schema auth,storage again to diff them.
          exit status 1
      - id: custom-schemas
        name: Custom schemas
        code: supabase db pull --schema auth,storage
        response: |
          Connecting to remote database...
          Setting up initial schema....
          Creating custom roles supabase/roles.sql...
          Applying migration 20240414044403_remote_schema.sql...
          No schema changes found
          Try rerunning the command with --debug to troubleshoot the error.
          exit status 1
    tags: []
    links: []
    usage: supabase db pull [migration name] [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Pulls from the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: declarative
        name: --declarative
        description: Replace the declarative schema tree from the selected database instead of creating a migration; migration history is not updated.
        default_value: 'false'
      - id: diff-engine
        name: --diff-engine <[ migra | pg-delta ]>
        description: Diff engine to use for migration-style db pull.
        default_value: migra
        accepted_values:
          - id: migra
            name: migra
            type: '[ migra | pg-delta ]'
          - id: pg-delta
            name: pg-delta
            type: '[ migra | pg-delta ]'
      - id: linked
        name: --linked
        description: Pulls from the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Pulls from the local database.
        default_value: 'false'
      - id: password
        name: -p, --password <string>
        description: Password to your remote Postgres database.
        default_value: ''
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: schema
        name: -s, --schema <strings>
        description: Comma separated list of schema to include.
        default_value: '[]'
      - id: strict-coverage
        name: --strict-coverage
        description: Fail when bundled pg-delta finds schema objects it cannot manage instead of leaving them unmanaged.
        default_value: 'false'
  - id: supabase-db-push
    title: supabase db push
    summary: Push new migrations to the remote database
    description: |


      Pushes all local migrations to a remote database.

      Requires your local project to be linked to a remote database by running `supabase link`. For self-hosted databases, you can pass in the connection parameters using `--db-url` flag.

      The first time this command is run, a migration history table will be created under `supabase_migrations.schema_migrations`. After successfully applying a migration, a new row will be inserted into the migration history table with timestamp as its unique id. Subsequent pushes will skip migrations that have already been applied.

      If you need to mutate the migration history table, such as deleting existing entries or inserting new entries without actually running the migration, use the `migration repair` command.

      Use the `--dry-run` flag to view the list of changes before applying.
    examples:
      - id: basic-usage
        name: Basic usage
        code: supabase db push
        response: |
          Linked project is up to date.
      - id: self-hosted
        name: Self hosted
        code: supabase db push --db-url "postgres://user:pass@127.0.0.1:5432/postgres"
        response: |
          Pushing migration 20230410135622_create_employees_table.sql...
          Finished supabase db push.
      - id: dry-run
        name: Dry run
        code: supabase db push --dry-run
        response: |
          DRY RUN: migrations will *not* be pushed to the database.
          Would push migration 20230410135622_create_employees_table.sql...
          Would push migration 20230425064254_my_table.sql...
          Finished supabase db push.
    tags: []
    links: []
    usage: supabase db push [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Pushes to the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: dry-run
        name: --dry-run
        description: Print the migrations that would be applied, but don't actually apply them.
        default_value: 'false'
      - id: include-all
        name: --include-all
        description: Include all migrations not found on remote history table.
        default_value: 'false'
      - id: include-roles
        name: --include-roles
        description: Include custom roles from supabase/roles.sql.
        default_value: 'false'
      - id: include-seed
        name: --include-seed
        description: Include seed data from your config.
        default_value: 'false'
      - id: linked
        name: --linked
        description: Pushes to the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Pushes to the local database.
        default_value: 'false'
      - id: password
        name: -p, --password <string>
        description: Password to your remote Postgres database.
        default_value: ''
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: skip-vault
        name: --skip-vault
        description: Skip updating vault secrets from config.toml.
        default_value: 'false'
  - id: supabase-db-query
    title: supabase db query
    summary: Execute a SQL query against the database
    description: |


      Execute a SQL query against the local or linked database.

      When used by an AI coding agent (auto-detected or via --agent=yes), the default
      output format is JSON with an untrusted data warning envelope. When used by a
      human (--agent=no or no agent detected), the default output format is table
      without the envelope.
    tags: []
    links: []
    usage: supabase db query [sql] [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Queries the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: file
        name: -f, --file <string>
        description: Path to a SQL file to execute.
        default_value: ''
      - id: linked
        name: --linked
        description: Queries the linked project's database via Management API.
        default_value: 'false'
      - id: local
        name: --local
        description: Queries the local database.
        default_value: 'true'
      - id: output
        name: -o, --output <[ json | table | csv ]>
        description: 'Output format: table, json, or csv.'
        default_value: json
        accepted_values:
          - id: json
            name: json
            type: '[ json | table | csv ]'
          - id: table
            name: table
            type: '[ json | table | csv ]'
          - id: csv
            name: csv
            type: '[ json | table | csv ]'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-db-reset
    title: supabase db reset
    summary: Resets the local database to current migrations
    description: |


      Resets the local database to a clean state.

      Requires the local development stack to be started by running `supabase start`.

      Recreates the local Postgres container and applies all local migrations found in `supabase/migrations` directory. If test data is defined in `supabase/seed.sql`, it will be seeded after the migrations are run. Any other data or schema changes made during local development will be discarded.

      Use the `--no-seed` flag to skip seeding entirely. To override `[db.seed].sql_paths` for a single reset, pass one or more `--sql-paths` flags. Each value accepts the same file path or glob pattern syntax as `sql_paths`, relative to the `supabase` directory. Passing `--sql-paths` force-enables seeding for that reset even when `[db.seed].enabled = false`.

      When running db reset with `--linked` or `--db-url` flag, a SQL script is executed to identify and drop all user created entities in the remote database. Since Postgres roles are cluster level entities, any custom roles created through the dashboard or `supabase/roles.sql` will not be deleted by remote reset.

      If you combine `--sql-paths` with `--linked` or `--db-url`, the override seed files are applied to the selected remote database after migrations. Use this only when you intend to seed that remote target.
    examples:
      - id: basic-usage
        name: Basic usage
        code: supabase db reset
        response: |
          Resetting database...
          Initializing schema...
          Applying migration 20220810154537_create_employees_table.sql...
          Seeding data supabase/seed.sql...
          Finished supabase db reset on branch main.
    tags: []
    links: []
    usage: supabase db reset [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Resets the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: last
        name: --last <int>
        description: Reset up to the last n migration versions.
        default_value: '0'
      - id: linked
        name: --linked
        description: Resets the linked project with local migrations.
        default_value: 'false'
      - id: local
        name: --local
        description: Resets the local database with local migrations.
        default_value: 'true'
      - id: no-seed
        name: --no-seed
        description: Skip running the seed script after reset.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: sql-paths
        name: --sql-paths <strings>
        description: Override [db.seed].sql_paths for this reset. May be repeated; each value accepts a SQL file path or glob pattern relative to the supabase directory and force-enables seeding.
        default_value: '[]'
      - id: version
        name: --version <string>
        description: Reset up to the specified version.
        default_value: ''
  - id: supabase-db-schema
    title: supabase db schema
    summary: Manage database schema
    description: Manage database schema.
    tags: []
    links: []
    subcommands:
      - supabase-db-schema-declarative
    flags: []
  - id: supabase-db-schema-declarative
    title: supabase db schema declarative
    summary: Manage declarative database schemas
    description: Manage declarative database schemas.
    tags: []
    links: []
    subcommands:
      - supabase-db-schema-declarative-generate
      - supabase-db-schema-declarative-sync
    flags: []
  - id: supabase-db-schema-declarative-generate
    title: supabase db schema declarative generate
    summary: Generate declarative schema from a database
    description: |


      Generate declarative schema files from a database.

      Exports the schema of a live database (local, linked, or custom URL) into SQL files under the declarative schema directory. This is the entrypoint for bootstrapping declarative mode.

      The bundled pg-delta engine writes one directory per schema at the root of that directory (`supabase/schemas/public/tables/users.sql`, `supabase/schemas/public/schema.sql`), with cluster-level objects that belong to no schema under a reserved `_cluster/` directory (`supabase/schemas/_cluster/roles.sql`). When platform default grants (`anon`/`authenticated`/`service_role`) need an overlay `REVOKE ALL`, the export writes `adp_wipes.sql` after `schema.sql` in that schema — or `_cluster/adp_wipes.sql` for cluster-wide overlays — so a load onto a fresh project keeps privileges that were revoked in the source. A schema literally named `_cluster` or `_custom`, in any casing, has its leading underscore percent-encoded (`%5Fcluster/`) so it can never claim a directory the export owns. Hand-authored SQL that pg-delta does not model belongs in `_custom/`, which the export never writes to and never prunes.

      Emitted SQL uses the same default format as `db pull` (uppercase keywords, indent 2, width 180, column-aligned). Override with `[experimental.pgdelta] format_options`, or set `format_options = "null"` for raw statements.

      Requires `--experimental` flag or `[experimental.pgdelta] enabled = true` in config.
    tags: []
    links: []
    usage: supabase db schema declarative generate [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Generates declarative schema from the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: linked
        name: --linked
        description: Generates declarative schema from the linked project.
        default_value: 'false'
      - id: local
        name: --local
        description: Generates declarative schema from the local database.
        default_value: 'false'
      - id: output-dir
        name: --output-dir <string>
        description: Write the generated declarative schema to this directory without changing the configured declarative schema path.
        default_value: ''
      - id: overwrite
        name: --overwrite
        description: Overwrite declarative schema files without confirmation.
        default_value: 'false'
      - id: password
        name: -p, --password <string>
        description: Password to your remote Postgres database.
        default_value: ''
      - id: reset
        name: --reset
        description: Reset local database before generating (local data will be lost).
        default_value: 'false'
      - id: schema
        name: -s, --schema <strings>
        description: Comma separated list of schema to include.
        default_value: '[]'
      - id: experimental
        name: --experimental
        description: enable experimental features
        default_value: 'false'
      - id: no-cache
        name: --no-cache
        description: Disable catalog cache and force fresh shadow database setup.
        default_value: 'false'
      - id: strict-coverage
        name: --strict-coverage
        description: Fail when bundled pg-delta finds schema objects it cannot manage instead of leaving them unmanaged.
        default_value: 'false'
  - id: supabase-db-schema-declarative-sync
    title: supabase db schema declarative sync
    summary: Generate a new migration from declarative schema
    description: |


      Generate a new migration by diffing your declarative schema files against the current migration state.

      When no declarative schema exists yet, the command offers to run `generate` first. After computing the diff, you can optionally name the migration and apply it to the local database.

      Requires `--experimental` flag or `[experimental.pgdelta] enabled = true` in config.
    examples:
      - id: with-pg-delta
        name: Sync declarative schema with pg-delta
        code: |
          # After editing declarative schema files, generate a migration:
          supabase db schema declarative sync --experimental
        response: |
          Creating shadow database...
          Applying declarative schemas via pg-delta...
          Applied 239 statements in 1 round(s).
          Enter a name for this migration (press Enter to keep 'declarative_sync'): add_updated_at
          Created new migration at supabase/migrations/20260317194051_add_updated_at.sql
          Apply this migration to local database? [Y/n]
          Connecting to local database...
          Applying migration 20260317194051_add_updated_at.sql...
          Migration applied successfully.
      - id: generate-first
        name: Generate declarative schema from migrations
        code: |
          supabase db schema declarative sync --experimental
        response: |
          No declarative schema found. Generate a new one ? [Y/n]
          Reset local database to match migrations first? (local data will be lost) [y/N] y
          Resetting database...
          ...
          Declarative schema written to supabase/schemas
          Finished supabase db schema declarative generate.
    tags: []
    links: []
    usage: supabase db schema declarative sync [flags]
    subcommands: []
    flags:
      - id: apply
        name: --apply
        description: Apply the generated migration to the local database without prompting.
        default_value: 'false'
      - id: file
        name: -f, --file <string>
        description: Saves schema diff to a new migration file.
        default_value: declarative_sync
      - id: name
        name: --name <string>
        description: Name for the generated migration file.
        default_value: ''
      - id: no-apply
        name: --no-apply
        description: Generate the migration file without prompting or applying it to the local database.
        default_value: 'false'
      - id: schema
        name: -s, --schema <strings>
        description: Comma separated list of schema to include.
        default_value: '[]'
      - id: experimental
        name: --experimental
        description: enable experimental features
        default_value: 'false'
      - id: no-cache
        name: --no-cache
        description: Disable catalog cache and force fresh shadow database setup.
        default_value: 'false'
      - id: strict-coverage
        name: --strict-coverage
        description: Fail when bundled pg-delta finds schema objects it cannot manage instead of leaving them unmanaged.
        default_value: 'false'
  - id: supabase-db-start
    title: supabase db start
    summary: Starts local Postgres database
    description: Starts local Postgres database.
    tags: []
    links: []
    usage: supabase db start [flags]
    subcommands: []
    flags:
      - id: from-backup
        name: --from-backup <string>
        description: Path to a logical backup file.
        default_value: ''
  - id: supabase-domains
    title: supabase domains
    summary: Manage custom domain names for Supabase projects
    description: Manage custom domain names for Supabase projects. Use of custom domains and vanity subdomains is mutually exclusive.
    tags:
      - management-api
    links: []
    subcommands:
      - supabase-domains-activate
      - supabase-domains-create
      - supabase-domains-delete
      - supabase-domains-get
      - supabase-domains-reverify
    flags: []
  - id: supabase-domains-activate
    title: supabase domains activate
    summary: Activate the custom hostname for a project
    description: |


      Activates the custom hostname configuration for a project.

      This reconfigures your Supabase project to respond to requests on your custom hostname.

      After the custom hostname is activated, your project's third-party auth providers will no longer function on the Supabase-provisioned subdomain. Please refer to [Prepare to activate your domain](/docs/guides/platform/custom-domains#prepare-to-activate-your-domain) section in our documentation to learn more about the steps you need to follow.
    examples:
      - id: example-1
        name: Activate the custom hostname for a project
        code: supabase domains activate --project-ref abcdefghijklmnopqrst
    tags: []
    links: []
    usage: supabase domains activate [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-domains-create
    title: supabase domains create
    summary: Create a custom hostname
    description: Create a custom hostname for your Supabase project. Expects your custom hostname to have a CNAME record to your Supabase project's subdomain.
    examples:
      - id: example-1
        name: Create a custom hostname for a project
        code: supabase domains create --custom-hostname example.com --project-ref abcdefghijklmnopqrst
    tags: []
    links: []
    usage: supabase domains create [flags]
    subcommands: []
    flags:
      - id: custom-hostname
        name: --custom-hostname <string>
        description: The custom hostname to use for your Supabase project.
        required: true
        default_value: ''
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-domains-delete
    title: supabase domains delete
    summary: Delete the custom hostname config
    description: Deletes the custom hostname config for your project.
    examples:
      - id: example-1
        name: Delete the custom hostname config for a project
        code: supabase domains delete --project-ref abcdefghijklmnopqrst
    tags: []
    links: []
    usage: supabase domains delete [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-domains-get
    title: supabase domains get
    summary: Get the current custom hostname config
    description: Retrieve the custom hostname config for your project, as stored in the Supabase platform.
    examples:
      - id: example-1
        name: Get the custom hostname config for a project
        code: supabase domains get --project-ref abcdefghijklmnopqrst
    tags: []
    links: []
    usage: supabase domains get [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-domains-reverify
    title: supabase domains reverify
    summary: Re-verify the custom hostname config
    description: Re-verify the custom hostname config for your project.
    examples:
      - id: example-1
        name: Re-verify the custom hostname for a project
        code: supabase domains reverify --project-ref abcdefghijklmnopqrst
    tags: []
    links: []
    usage: supabase domains reverify [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-encryption
    title: supabase encryption
    summary: Manage encryption keys
    description: Manage encryption keys of Supabase projects
    tags:
      - management-api
    links: []
    subcommands:
      - supabase-encryption-get-root-key
      - supabase-encryption-update-root-key
    flags: []
  - id: supabase-encryption-get-root-key
    title: supabase encryption get-root-key
    summary: Get root encryption key
    description: Get the root encryption key of a Supabase project
    tags: []
    links: []
    usage: supabase encryption get-root-key [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-encryption-update-root-key
    title: supabase encryption update-root-key
    summary: Update the root encryption key
    description: Update root encryption key of a Supabase project
    tags: []
    links: []
    usage: supabase encryption update-root-key [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-feedback
    title: supabase feedback
    summary: Send feedback to the Supabase team
    description: Send feedback about the Supabase CLI to the Supabase team.
    tags:
      - other-commands
    links: []
    subcommands:
      - supabase-feedback-add
      - supabase-feedback-delete
    flags: []
  - id: supabase-feedback-add
    title: supabase feedback add
    summary: Send feedback to the Supabase team
    description: Send quick feedback about the Supabase CLI to the Supabase team.
    examples:
      - id: example-1
        name: Send quick feedback about a papercut in one line
        code: supabase feedback add "when I run multiple stacks in parallel I get port conflicts"
      - id: example-2
        name: Use -- when the message starts with a dash
        code: supabase feedback add -- "--yes should be the default in CI"
      - id: example-3
        name: Attribute the feedback to a project from an unlinked directory
        code: supabase feedback add --project-ref abcdefghijklmnopqrst "branching is slow here"
    tags: []
    links: []
    usage: supabase feedback add [message] ... [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref to attribute the feedback to (defaults to SUPABASE_PROJECT_ID, then the linked project).
        default_value: ''
  - id: supabase-feedback-delete
    title: supabase feedback delete
    summary: Delete previously submitted feedback
    description: Delete previously submitted feedback using its deletion token.
    examples:
      - id: example-1
        name: Delete feedback using the token printed when it was submitted
        code: supabase feedback delete 123e4567-e89b-12d3-a456-426614174000
    tags: []
    links: []
    usage: supabase feedback delete <token> [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project the feedback was submitted with.
        default_value: ''
  - id: supabase-functions
    title: supabase functions
    summary: Manage Supabase Edge functions
    description: |


      Manage Supabase Edge Functions.

      Supabase Edge Functions are server-less functions that run close to your users.

      Edge Functions allow you to execute custom server-side code without deploying or scaling a traditional server. They're ideal for handling webhooks, custom API endpoints, data validation, and serving personalized content.

      Edge Functions are written in TypeScript and run on Deno compatible edge runtime, which is a secure runtime with no package management needed, fast cold starts, and built-in security.
    tags:
      - management-api
    links: []
    subcommands:
      - supabase-functions-delete
      - supabase-functions-deploy
      - supabase-functions-download
      - supabase-functions-list
      - supabase-functions-new
      - supabase-functions-serve
    flags: []
  - id: supabase-functions-delete
    title: supabase functions delete
    summary: Delete a Function from Supabase
    description: Delete a Function from the linked Supabase project. This does NOT remove the Function locally.
    examples:
      - id: example-1
        name: Delete a deployed function from the linked project
        code: supabase functions delete hello-world
      - id: example-2
        name: Delete a deployed function from a specific project
        code: supabase functions delete hello-world --project-ref abcdefghijklmnopqrst
    tags: []
    links: []
    usage: supabase functions delete <Function name> [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-functions-deploy
    title: supabase functions deploy
    summary: Deploy a Function to Supabase
    description: Deploy a Function to the linked Supabase project.
    examples:
      - id: example-1
        name: Deploy a single function to the linked project
        code: supabase functions deploy hello-world
      - id: example-2
        name: Deploy all local functions to a specific project
        code: supabase functions deploy --project-ref abcdefghijklmnopqrst
    tags: []
    links: []
    usage: supabase functions deploy [Function name] ... [flags]
    subcommands: []
    flags:
      - id: import-map
        name: --import-map <string>
        description: Path to import map file.
        default_value: ''
      - id: jobs
        name: -j, --jobs <int>
        description: Maximum number of parallel jobs.
        default_value: '1'
      - id: no-verify-jwt
        name: --no-verify-jwt
        description: Disable JWT verification for the Function.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: prune
        name: --prune
        description: Delete Functions that exist in Supabase project but not locally.
        default_value: 'false'
      - id: use-api
        name: --use-api
        description: Bundle functions server-side without using Docker.
        default_value: 'false'
  - id: supabase-functions-download
    title: supabase functions download
    summary: Download a Function from Supabase
    description: Download the source code for a Function from the linked Supabase project. If no function name is provided, downloads all functions.
    examples:
      - id: example-1
        name: Download a single function from the linked project
        code: supabase functions download hello-world
      - id: example-2
        name: Download all functions from a specific project
        code: supabase functions download --project-ref abcdefghijklmnopqrst
    tags: []
    links: []
    usage: supabase functions download [Function name] [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: use-api
        name: --use-api
        description: Unbundle functions server-side without using Docker.
        default_value: 'false'
  - id: supabase-functions-list
    title: supabase functions list
    summary: List all Functions in Supabase
    description: List all Functions in the linked Supabase project.
    examples:
      - id: example-1
        name: List all deployed functions in the linked project
        code: supabase functions list
      - id: example-2
        name: List all deployed functions in a specific project
        code: supabase functions list --project-ref abcdefghijklmnopqrst
    tags: []
    links: []
    usage: supabase functions list [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-functions-new
    title: supabase functions new
    summary: Create a new Function locally
    description: |


      Creates a new Edge Function with boilerplate code in the `supabase/functions` directory.

      This command generates a starter TypeScript file with the necessary Deno imports and a basic function structure. The function is created as a new directory with the name you specify, containing an `index.ts` file with the function code.

      After creating the function, you can edit it locally and then use `supabase functions serve` to test it before deploying with `supabase functions deploy`.
    tags: []
    links: []
    usage: supabase functions new <Function name> [flags]
    subcommands: []
    flags:
      - id: auth
        name: --auth <[ none | apikey | user ]>
        description: use a specific auth mode
        default_value: apikey
        accepted_values:
          - id: none
            name: none
            type: '[ none | apikey | user ]'
          - id: apikey
            name: apikey
            type: '[ none | apikey | user ]'
          - id: user
            name: user
            type: '[ none | apikey | user ]'
  - id: supabase-functions-serve
    title: supabase functions serve
    summary: Serve all Functions locally
    description: |


      Serve all Functions locally.

      `supabase functions serve` command includes additional flags to assist developers in debugging Edge Functions via the v8 inspector protocol, allowing for debugging via Chrome DevTools, VS Code, and IntelliJ IDEA for example. Refer to the [docs guide](/docs/guides/functions/debugging-tools) for setup instructions.

      1. `--inspect`
         - Alias of `--inspect-mode brk`.

      2. `--inspect-mode [ run | brk | wait ]`
         - Activates the inspector capability.
         - `run` mode simply allows a connection without additional behavior. It is not ideal for short scripts, but it can be useful for long-running scripts where you might occasionally want to set breakpoints.
         - `brk` mode same as `run` mode, but additionally sets a breakpoint at the first line to pause script execution before any code runs.
         - `wait` mode similar to `brk` mode, but instead of setting a breakpoint at the first line, it pauses script execution until an inspector session is connected.

      3. `--inspect-main`
         - Can only be used when one of the above two flags is enabled.
         - By default, creating an inspector session for the main worker is not allowed, but this flag allows it.
         - Other behaviors follow the `inspect-mode` flag mentioned above.

      Additionally, the following properties can be customized via `supabase/config.toml` under `edge_runtime` section.

      1. `inspector_port`
         - The port used to listen to the Inspector session, defaults to 8083.
      2. `policy`
         - A value that indicates how the edge-runtime should forward incoming HTTP requests to the worker.
         - `per_worker` allows multiple HTTP requests to be forwarded to a worker that has already been created.
         - `oneshot` will force the worker to process a single HTTP request and then exit. (Debugging purpose, This is especially useful if you want to reflect changes you've made immediately.)
    tags: []
    links: []
    usage: supabase functions serve [Function name] ... [flags]
    subcommands: []
    flags:
      - id: env-file
        name: --env-file <string>
        description: Path to an env file. Overrides supabase/functions/.env and per-Function .env files.
        default_value: ''
      - id: import-map
        name: --import-map <string>
        description: Path to import map file.
        default_value: ''
      - id: inspect
        name: --inspect
        description: Alias of --inspect-mode brk.
        default_value: 'false'
      - id: inspect-main
        name: --inspect-main
        description: Allow inspecting the main worker.
        default_value: 'false'
      - id: inspect-mode
        name: --inspect-mode <[ run | brk | wait ]>
        description: Activate inspector capability for debugging.
        default_value: ''
        accepted_values:
          - id: run
            name: run
            type: '[ run | brk | wait ]'
          - id: brk
            name: brk
            type: '[ run | brk | wait ]'
          - id: wait
            name: wait
            type: '[ run | brk | wait ]'
      - id: no-verify-jwt
        name: --no-verify-jwt
        description: Disable JWT verification for the Function.
        default_value: 'false'
  - id: supabase-gen
    title: supabase gen
    summary: Run code generation tools
    description: |


      Automatically generates type definitions based on your Postgres database schema.

      This command connects to your database (local or remote) and generates typed definitions that match your database tables, views, and stored procedures. By default, it generates TypeScript definitions, but also supports Go and Swift.

      Generated types give you type safety and autocompletion when working with your database in code, helping prevent runtime errors and improving developer experience.

      The types respect relationships, constraints, and custom types defined in your database schema.
    tags:
      - local-dev
    links: []
    subcommands:
      - supabase-gen-bearer-jwt
      - supabase-gen-signing-key
      - supabase-gen-types
    flags: []
  - id: supabase-gen-bearer-jwt
    title: supabase gen bearer-jwt
    summary: Generate a Bearer Auth JWT for accessing Data API
    description: Generate a Bearer Auth JWT for accessing Data API
    tags: []
    links: []
    usage: supabase gen bearer-jwt [flags]
    subcommands: []
    flags:
      - id: exp
        name: --exp <string>
        description: Expiry timestamp for this token.
        default_value: ''
      - id: payload
        name: --payload <string>
        description: Custom claims in JSON format.
        default_value: '{}'
      - id: role
        name: --role <string>
        description: Postgres role to use.
        required: true
        default_value: ''
      - id: sub
        name: --sub <string>
        description: User ID to impersonate.
        default_value: anonymous
      - id: valid-for
        name: --valid-for <string>
        description: Validity duration for this token.
        default_value: 30m0s
  - id: supabase-gen-signing-key
    title: supabase gen signing-key
    summary: Generate a JWT signing key
    description: |-
      Securely generate a private JWT signing key for use in the CLI or to import in the dashboard.

      Supported algorithms:
        ES256 - ECDSA with P-256 curve and SHA-256 (recommended)
        RS256 - RSA with SHA-256
    examples:
      - id: example-1
        name: Generate an ES256 signing key and print it to stdout
        code: supabase gen signing-key
      - id: example-2
        name: Generate an RSA signing key
        code: supabase gen signing-key --algorithm RS256
      - id: example-3
        name: Append a new key to the configured signing key file
        code: supabase gen signing-key --append
    tags: []
    links: []
    usage: supabase gen signing-key [flags]
    subcommands: []
    flags:
      - id: algorithm
        name: --algorithm <[ ES256 | RS256 ]>
        description: Algorithm for signing key generation.
        default_value: ES256
        accepted_values:
          - id: ES256
            name: ES256
            type: '[ ES256 | RS256 ]'
          - id: RS256
            name: RS256
            type: '[ ES256 | RS256 ]'
      - id: append
        name: --append
        description: Append new key to existing keys file instead of overwriting.
        default_value: 'false'
  - id: supabase-gen-types
    title: supabase gen types
    summary: Generate types from Postgres schema
    description: Generate types from Postgres schema.
    examples:
      - id: example-1
        name: Generate types from the local dev database
        code: supabase gen types --local
      - id: example-2
        name: Generate Go types from the linked project
        code: supabase gen types --linked --lang=go
      - id: example-3
        name: Generate types from a project ID with specific schemas
        code: supabase gen types --project-id abc-def-123 --schema public --schema private
      - id: example-4
        name: Generate types from a database URL
        code: supabase gen types --db-url 'postgresql://...' --schema public --schema auth
    tags: []
    links: []
    usage: supabase gen types [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Generate types from a database url.
        default_value: ''
      - id: lang
        name: --lang <[ typescript | go | python | swift | dart ]>
        description: Output language of the generated types. (default typescript)
        default_value: typescript
        accepted_values:
          - id: typescript
            name: typescript
            type: '[ typescript | go | python | swift | dart ]'
          - id: go
            name: go
            type: '[ typescript | go | python | swift | dart ]'
          - id: python
            name: python
            type: '[ typescript | go | python | swift | dart ]'
          - id: swift
            name: swift
            type: '[ typescript | go | python | swift | dart ]'
          - id: dart
            name: dart
            type: '[ typescript | go | python | swift | dart ]'
      - id: linked
        name: --linked
        description: Generate types from the linked project.
        default_value: 'false'
      - id: local
        name: --local
        description: Generate types from the local dev database.
        default_value: 'false'
      - id: project-id
        name: --project-id <string>
        description: Generate types from a project ID.
        default_value: ''
      - id: query-timeout
        name: --query-timeout <string>
        description: Maximum timeout allowed for the database query. (default 15s)
        default_value: 15s
      - id: schema
        name: -s, --schema <strings>
        description: Comma separated list of schema to include.
        default_value: '[]'
      - id: swift-access-control
        name: --swift-access-control <[ internal | public | private | package ]>
        description: Access control for Swift generated types. (default internal)
        default_value: internal
        accepted_values:
          - id: internal
            name: internal
            type: '[ internal | public | private | package ]'
          - id: public
            name: public
            type: '[ internal | public | private | package ]'
          - id: private
            name: private
            type: '[ internal | public | private | package ]'
          - id: package
            name: package
            type: '[ internal | public | private | package ]'
  - id: supabase-init
    title: supabase init
    summary: Initialize a local project
    description: |


      Initialize configurations for Supabase local development.

      A `supabase/config.toml` file is created in your current working directory. This configuration is specific to each local project.

      > You may override the directory path by specifying the `SUPABASE_WORKDIR` environment variable or `--workdir` flag.

      In addition to `config.toml`, the `supabase` directory may also contain other Supabase objects, such as `migrations`, `functions`, `tests`, etc.

      To use OrioleDB as the Postgres storage engine, run `supabase init --use-orioledb`. The command writes the OrioleDB version to `db.orioledb_version` in `supabase/config.toml`; `--experimental` is not required.
    examples:
      - id: basic-usage
        name: Basic usage
        code: supabase init
        response: Finished supabase init.
      - id: from-workdir
        name: Initialize from an existing directory
        code: supabase init --workdir .
        response: Finished supabase init.
      - id: with-orioledb
        name: Initialize with OrioleDB
        code: supabase init --use-orioledb
        response: Finished supabase init.
    tags:
      - local-dev
    links: []
    usage: supabase init [flags]
    subcommands: []
    flags:
      - id: force
        name: --force
        description: Overwrite existing supabase/config.toml.
        default_value: 'false'
      - id: interactive
        name: -i, --interactive
        description: Enables interactive mode to configure IDE settings.
        default_value: 'false'
      - id: use-orioledb
        name: --use-orioledb
        description: Use OrioleDB storage engine for Postgres.
        default_value: 'false'
  - id: supabase-inspect
    title: supabase inspect
    summary: Inspect project tools
    description: Tools to inspect your Supabase project.
    tags:
      - local-dev
    links: []
    subcommands:
      - supabase-inspect-db
      - supabase-inspect-report
    flags: []
  - id: supabase-inspect-db
    title: supabase inspect db
    summary: Inspect database
    description: Tools to inspect your Supabase database.
    tags: []
    links: []
    subcommands:
      - supabase-inspect-db-bloat
      - supabase-inspect-db-blocking
      - supabase-inspect-db-calls
      - supabase-inspect-db-db-stats
      - supabase-inspect-db-index-stats
      - supabase-inspect-db-locks
      - supabase-inspect-db-long-running-queries
      - supabase-inspect-db-outliers
      - supabase-inspect-db-replication-slots
      - supabase-inspect-db-role-stats
      - supabase-inspect-db-table-stats
      - supabase-inspect-db-traffic-profile
      - supabase-inspect-db-vacuum-stats
    flags: []
  - id: supabase-inspect-db-bloat
    title: supabase inspect db bloat
    summary: Show relation bloat
    description: |


      This command displays an estimation of table "bloat" - Due to Postgres' [MVCC](https://www.postgresql.org/docs/current/mvcc.html) when data is updated or deleted new rows are created and old rows are made invisible and marked as "dead tuples". Usually the [autovaccum](https://supabase.com/docs/guides/platform/database-size#vacuum-operations) process will asynchronously clean the dead tuples. Sometimes the autovaccum is unable to work fast enough to reduce or prevent tables from becoming bloated. High bloat can slow down queries, cause excessive IOPS and waste space in your database.

      Tables with a high bloat ratio should be investigated to see if there are vacuuming is not quick enough or there are other issues.

      ```
          TYPE  │ SCHEMA NAME │        OBJECT NAME         │ BLOAT │ WASTE
        ────────┼─────────────┼────────────────────────────┼───────┼─────────────
          table │ public      │ very_bloated_table         │  41.0 │ 700 MB
          table │ public      │ my_table                   │   4.0 │ 76 MB
          table │ public      │ happy_table                │   1.0 │ 1472 kB
          index │ public      │ happy_table::my_nice_index │   0.7 │ 880 kB
      ```
    tags: []
    links: []
    usage: supabase inspect db bloat [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Inspect the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: linked
        name: --linked
        description: Inspect the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Inspect the local database.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-inspect-db-blocking
    title: supabase inspect db blocking
    summary: Show blocking queries
    description: |


      This command shows you statements that are currently holding locks and blocking, as well as the statement that is being blocked. This can be used in conjunction with `inspect db locks` to determine which statements need to be terminated in order to resolve lock contention.

      ```
          BLOCKED PID │ BLOCKING STATEMENT           │ BLOCKING DURATION │ BLOCKING PID │ BLOCKED STATEMENT                                                                      │ BLOCKED DURATION
        ──────────────┼──────────────────────────────┼───────────────────┼──────────────┼────────────────────────────────────────────────────────────────────────────────────────┼───────────────────
          253         │ select count(*) from mytable │ 00:00:03.838314   │        13495 │ UPDATE "mytable" SET "updated_at" = '2023─08─03 14:07:04.746688' WHERE "id" = 83719341 │ 00:00:03.821826
      ```
    tags: []
    links: []
    usage: supabase inspect db blocking [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Inspect the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: linked
        name: --linked
        description: Inspect the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Inspect the local database.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-inspect-db-calls
    title: supabase inspect db calls
    summary: Show queries by call count
    description: |


      This command is much like the `supabase inspect db outliers` command, but ordered by the number of times a statement has been called.

      You can use this information to see which queries are called most often, which can potentially be good candidates for optimisation.

      ```

                              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

      ```
    tags: []
    links: []
    usage: supabase inspect db calls [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Inspect the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: linked
        name: --linked
        description: Inspect the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Inspect the local database.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-inspect-db-db-stats
    title: supabase inspect db db-stats
    summary: Show database stats
    description: Show stats such as cache hit rates, total sizes, and WAL size.
    tags: []
    links: []
    usage: supabase inspect db db-stats [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Inspect the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: linked
        name: --linked
        description: Inspect the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Inspect the local database.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-inspect-db-index-stats
    title: supabase inspect db index-stats
    summary: Show index stats
    description: Show combined index size, usage percent, scan counts, and unused status.
    tags: []
    links: []
    usage: supabase inspect db index-stats [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Inspect the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: linked
        name: --linked
        description: Inspect the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Inspect the local database.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-inspect-db-locks
    title: supabase inspect db locks
    summary: Show exclusive locks
    description: |


      This command displays queries that have taken out an exclusive lock on a relation. Exclusive locks typically prevent other operations on that relation from taking place, and can be a cause of "hung" queries that are waiting for a lock to be granted.

      If you see a query that is hanging for a very long time or causing blocking issues you may consider killing the query by connecting to the database and running `SELECT pg_cancel_backend(PID);` to cancel the query. If the query still does not stop you can force a hard stop by running `SELECT pg_terminate_backend(PID);`

      ```
           PID   │ RELNAME │ TRANSACTION ID │ GRANTED │                  QUERY                  │   AGE
        ─────────┼─────────┼────────────────┼─────────┼─────────────────────────────────────────┼───────────
          328112 │ null    │              0 │ t       │ SELECT * FROM logs;                     │ 00:04:20
      ```
    tags: []
    links: []
    usage: supabase inspect db locks [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Inspect the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: linked
        name: --linked
        description: Inspect the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Inspect the local database.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-inspect-db-long-running-queries
    title: supabase inspect db long-running-queries
    summary: Show long-running queries
    description: |


      This command displays currently running queries, that have been running for longer than 5 minutes, descending by duration. Very long running queries can be a source of multiple issues, such as preventing DDL statements completing or vacuum being unable to update `relfrozenxid`.

      ```
        PID  │     DURATION    │                                         QUERY
      ───────┼─────────────────┼───────────────────────────────────────────────────────────────────────────────────────
       19578 | 02:29:11.200129 | EXPLAIN SELECT  "students".* FROM "students"  WHERE "students"."id" = 1450645 LIMIT 1
       19465 | 02:26:05.542653 | EXPLAIN SELECT  "students".* FROM "students"  WHERE "students"."id" = 1889881 LIMIT 1
       19632 | 02:24:46.962818 | EXPLAIN SELECT  "students".* FROM "students"  WHERE "students"."id" = 1581884 LIMIT 1
      ```
    tags: []
    links: []
    usage: supabase inspect db long-running-queries [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Inspect the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: linked
        name: --linked
        description: Inspect the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Inspect the local database.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-inspect-db-outliers
    title: supabase inspect db outliers
    summary: Show query outliers by time
    description: |


      This command displays statements, obtained from `pg_stat_statements`, ordered by the amount of time to execute in aggregate. This includes the statement itself, the total execution time for that statement, the proportion of total execution time for all statements that statement has taken up, the number of times that statement has been called, and the amount of time that statement spent on synchronous I/O (reading/writing from the file system).

      Typically, an efficient query will have an appropriate ratio of calls to total execution time, with as little time spent on I/O as possible. Queries that have a high total execution time but low call count should be investigated to improve their performance. Queries that have a high proportion of execution time being spent on synchronous I/O should also be investigated.

      ```

                       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
      ```
    tags: []
    links: []
    usage: supabase inspect db outliers [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Inspect the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: linked
        name: --linked
        description: Inspect the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Inspect the local database.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-inspect-db-replication-slots
    title: supabase inspect db replication-slots
    summary: Show replication slots
    description: |


      This command shows information about [logical replication slots](https://www.postgresql.org/docs/current/logical-replication.html) that are setup on the database. It shows if the slot is active, the state of the WAL sender process ('startup', 'catchup', 'streaming', 'backup', 'stopping') the replication client address and the replication lag in GB.

      This command is useful to check that the amount of replication lag is as low as possible, replication lag can occur due to network latency issues, slow disk I/O, long running transactions or lack of ability for the subscriber to consume WAL fast enough.

      ```
                             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
      ```
    tags: []
    links: []
    usage: supabase inspect db replication-slots [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Inspect the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: linked
        name: --linked
        description: Inspect the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Inspect the local database.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-inspect-db-role-stats
    title: supabase inspect db role-stats
    summary: Show role stats
    description: Show information about roles on the database.
    tags: []
    links: []
    usage: supabase inspect db role-stats [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Inspect the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: linked
        name: --linked
        description: Inspect the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Inspect the local database.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-inspect-db-table-stats
    title: supabase inspect db table-stats
    summary: Show table stats
    description: Show combined table size, index size, and estimated row count.
    tags: []
    links: []
    usage: supabase inspect db table-stats [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Inspect the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: linked
        name: --linked
        description: Inspect the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Inspect the local database.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-inspect-db-traffic-profile
    title: supabase inspect db traffic-profile
    summary: Show traffic profile
    description: |


      This command analyzes table I/O patterns to show read/write activity ratios based on block-level operations. It combines data from PostgreSQL's `pg_stat_user_tables` (for tuple operations) and `pg_statio_user_tables` (for block I/O) to categorize each table's workload profile.

      The command classifies tables into categories:

      - **Read-Heavy** - Read operations are more than 5x write operations (e.g., 1:10, 1:50)
      - **Write-Heavy** - Write operations are more than 20% of read operations (e.g., 1:2, 1:4, 2:1, 10:1)
      - **Balanced** - Mixed workload where writes are between 20% and 500% of reads
      - **Read-Only** - Only read operations detected
      - **Write-Only** - Only write operations detected

      ```
      SCHEMA │ TABLE        │ BLOCKS READ │ WRITE TUPLES │ BLOCKS WRITE │ ACTIVITY RATIO
      ───────┼──────────────┼─────────────┼──────────────┼──────────────┼────────────────────
      public │ user_events  │     450,234 │     9,004,680│       23,450 │ 20:1 (Write-Heavy)
      public │ users        │      89,203 │        12,451│        1,203 │ 7.2:1 (Read-Heavy)
      public │ sessions     │      15,402 │        14,823│        2,341 │ ≈1:1 (Balanced)
      public │ cache_data   │     123,456 │             0│            0 │ Read-Only
      auth   │ audit_logs   │           0 │        98,234│       12,341 │ Write-Only
      ```

      **Note:** This command only displays tables that have had both read and write activity. Tables with no I/O operations are not shown. The classification ratio threshold (default: 5:1) determines when a table is considered "heavy" in one direction versus balanced.
    tags: []
    links: []
    usage: supabase inspect db traffic-profile [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Inspect the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: linked
        name: --linked
        description: Inspect the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Inspect the local database.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-inspect-db-vacuum-stats
    title: supabase inspect db vacuum-stats
    summary: Show vacuum stats
    description: |


      This shows you stats about the vacuum activities for each table. Due to Postgres' [MVCC](https://www.postgresql.org/docs/current/mvcc.html) when data is updated or deleted new rows are created and old rows are made invisible and marked as "dead tuples". Usually the [autovaccum](https://supabase.com/docs/guides/platform/database-size#vacuum-operations) process will aysnchronously clean the dead tuples.

      The command lists when the last vacuum and last auto vacuum took place, the row count on the table as well as the count of dead rows and whether autovacuum is expected to run or not. If the number of dead rows is much higher than the row count, or if an autovacuum is expected but has not been performed for some time, this can indicate that autovacuum is not able to keep up and that your vacuum settings need to be tweaked or that you require more compute or disk IOPS to allow autovaccum to complete.

      ```
              SCHEMA        │              TABLE               │ LAST VACUUM │ LAST AUTO VACUUM │      ROW COUNT       │ DEAD ROW COUNT │ EXPECT AUTOVACUUM?
      ──────────────────────┼──────────────────────────────────┼─────────────┼──────────────────┼──────────────────────┼────────────────┼─────────────────────
       auth                 │ users                            │             │ 2023-06-26 12:34 │               18,030 │              0 │ no
       public               │ profiles                         │             │ 2023-06-26 23:45 │               13,420 │             28 │ no
       public               │ logs                             │             │ 2023-06-26 01:23 │            1,313,033 │      3,318,228 │ yes
       storage              │ objects                          │             │                  │             No stats │              0 │ no
       storage              │ buckets                          │             │                  │             No stats │              0 │ no
       supabase_migrations  │ schema_migrations                │             │                  │             No stats │              0 │ no

      ```
    tags: []
    links: []
    usage: supabase inspect db vacuum-stats [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Inspect the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: linked
        name: --linked
        description: Inspect the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Inspect the local database.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-inspect-report
    title: supabase inspect report
    summary: Generate a CSV output for all inspect commands
    description: Generate a CSV output for all inspect commands.
    tags: []
    links: []
    usage: supabase inspect report [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Inspect the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: linked
        name: --linked
        description: Inspect the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Inspect the local database.
        default_value: 'false'
      - id: output-dir
        name: --output-dir <string>
        description: Path to save CSV files in.
        default_value: '.'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-issue
    title: supabase issue
    summary: Open GitHub issue forms
    description: Open Supabase CLI GitHub issue forms.
    tags:
      - other-commands
    links: []
    subcommands:
      - supabase-issue-bug
      - supabase-issue-docs
      - supabase-issue-feature
    flags: []
  - id: supabase-issue-bug
    title: supabase issue bug
    summary: Open a bug report
    description: Open a GitHub bug report with local CLI details prefilled.
    examples:
      - id: example-1
        name: Open a prefilled bug report for a failing command
        code: supabase issue bug --command "supabase start" --actual-output "database failed to start"
      - id: example-2
        name: Print a prefilled issue URL with a crash report ID
        code: supabase issue bug --crash-report-id "abc123" --no-browser
    tags: []
    links: []
    usage: supabase issue bug [flags]
    subcommands: []
    flags:
      - id: actual-output
        name: --actual-output <string>
        description: Actual output or error text.
        default_value: ''
      - id: additional-context
        name: --additional-context <string>
        description: Extra context to prefill on the issue form.
        default_value: ''
      - id: area
        name: --area <string>
        description: Affected CLI area.
        default_value: ''
      - id: command
        name: --command <string>
        description: Command that failed.
        default_value: ''
      - id: crash-report-id
        name: --crash-report-id <string>
        description: Crash report ID printed by --create-ticket.
        default_value: ''
      - id: docker-services
        name: --docker-services <string>
        description: Relevant Docker service status or logs.
        default_value: ''
      - id: expected-behavior
        name: --expected-behavior <string>
        description: Expected behavior.
        default_value: ''
      - id: no-browser
        name: --no-browser
        description: Print the issue form URL without opening a browser.
        default_value: 'false'
      - id: reproduce
        name: --reproduce <string>
        description: Steps to reproduce.
        default_value: ''
  - id: supabase-issue-docs
    title: supabase issue docs
    summary: Open a documentation issue
    description: Open a GitHub documentation issue with useful context prefilled.
    examples:
      - id: example-1
        name: Open a prefilled documentation issue
        code: supabase issue docs --link "https://supabase.com/docs/guides/cli" --problem "The flag description is outdated"
    tags: []
    links: []
    usage: supabase issue docs [flags]
    subcommands: []
    flags:
      - id: additional-context
        name: --additional-context <string>
        description: Extra context to prefill on the issue form.
        default_value: ''
      - id: improvement
        name: --improvement <string>
        description: Suggested documentation improvement.
        default_value: ''
      - id: issue-type
        name: --issue-type <string>
        description: Documentation issue type.
        default_value: ''
      - id: link
        name: --link <string>
        description: Relevant documentation link.
        default_value: ''
      - id: no-browser
        name: --no-browser
        description: Print the issue form URL without opening a browser.
        default_value: 'false'
      - id: problem
        name: --problem <string>
        description: What is confusing, missing, or incorrect.
        default_value: ''
  - id: supabase-issue-feature
    title: supabase issue feature
    summary: Open a feature request
    description: Open a GitHub feature request with useful context prefilled.
    examples:
      - id: example-1
        name: Open a prefilled feature request
        code: supabase issue feature --existing-issues --problem "I need to rotate local secrets" --proposed-solution "Add a secrets rotate command"
    tags: []
    links: []
    usage: supabase issue feature [flags]
    subcommands: []
    flags:
      - id: additional-context
        name: --additional-context <string>
        description: Extra context to prefill on the issue form.
        default_value: ''
      - id: alternatives
        name: --alternatives <string>
        description: Alternatives considered.
        default_value: ''
      - id: area
        name: --area <string>
        description: Affected CLI area.
        default_value: ''
      - id: existing-issues
        name: --existing-issues
        description: Prefill the existing issues checklist.
        default_value: 'false'
      - id: no-browser
        name: --no-browser
        description: Print the issue form URL without opening a browser.
        default_value: 'false'
      - id: problem
        name: --problem <string>
        description: Problem the feature should solve.
        default_value: ''
      - id: proposed-solution
        name: --proposed-solution <string>
        description: Proposed solution.
        default_value: ''
  - id: supabase-link
    title: supabase link
    summary: Link to a Supabase project
    description: |


      Link your local development project to a hosted Supabase project.

      PostgREST configurations are fetched from the Supabase platform and validated against your local configuration file.

      Optionally, database settings can be validated if you provide a password. Your database password is saved in native credentials storage if available.

      > If you do not want to be prompted for the database password, such as in a CI environment, you may specify it explicitly via the `SUPABASE_DB_PASSWORD` environment variable.

      Some commands like `db dump`, `db push`, and `db pull` require your project to be linked first.
    examples:
      - id: basic-usage
        name: Basic usage
        code: supabase link --project-ref ********************
        response: |
          Enter your database password (or leave blank to skip): ********
          Finished supabase link.
      - id: without-password
        name: Link without database password
        code: supabase link --project-ref ******************** <<< ""
        response: |
          Enter your database password (or leave blank to skip):
          Finished supabase link.
      - id: using-alternate-dns
        name: Link using DNS-over-HTTPS resolver
        code: supabase link --project-ref ******************** --dns-resolver https
        response: |
          Enter your database password (or leave blank to skip):
          Finished supabase link.
    tags:
      - local-dev
    links: []
    usage: supabase link [ref-or-branch] [flags]
    subcommands: []
    flags:
      - id: password
        name: -p, --password <string>
        description: Password to your remote Postgres database.
        default_value: ''
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project, or the name of one of its branches.
        default_value: ''
      - id: skip-pooler
        name: --skip-pooler
        description: Use direct connection instead of pooler.
        default_value: 'false'
  - id: supabase-login
    title: supabase login
    summary: Authenticate using an access token
    description: |


      Connect the Supabase CLI to your Supabase account by logging in with your [personal access token](https://supabase.com/dashboard/account/tokens).

      Your access token is stored securely in [native credentials storage](https://github.com/zalando/go-keyring#dependencies). If native credentials storage is unavailable, it will be written to a plain text file at `<SUPABASE_HOME or ~/.supabase>/access-token`.

      > If this behavior is not desired, such as in a CI environment, you may skip login by specifying the `SUPABASE_ACCESS_TOKEN` environment variable in other commands.

      The Supabase CLI uses the stored token to access Management APIs for projects, functions, secrets, etc.
    examples:
      - id: basic-usage
        name: Basic usage
        code: supabase login
        response: |
          You can generate an access token from https://supabase.com/dashboard/account/tokens
          Enter your access token: sbp_****************************************
          Finished supabase login.
    tags:
      - local-dev
    links: []
    usage: supabase login [flags]
    subcommands: []
    flags:
      - id: name
        name: --name <string>
        description: Name that will be used to store token in your settings.
        default_value: built-in token name generator
      - id: no-browser
        name: --no-browser
        description: Do not open browser automatically.
        default_value: 'false'
      - id: token
        name: --token <string>
        description: Use provided token instead of automatic login flow.
        default_value: ''
  - id: supabase-logout
    title: supabase logout
    summary: Log out and delete access tokens locally
    description: Log out and delete access tokens locally.
    tags:
      - local-dev
    links: []
    usage: supabase logout [flags]
    subcommands: []
    flags: []
  - id: supabase-migration
    title: supabase migration
    summary: Manage database migration scripts
    description: Manage database migration scripts.
    tags:
      - local-dev
    links: []
    subcommands:
      - supabase-migration-down
      - supabase-migration-fetch
      - supabase-migration-list
      - supabase-migration-new
      - supabase-migration-repair
      - supabase-migration-squash
      - supabase-migration-up
    flags: []
  - id: supabase-migration-down
    title: supabase migration down
    summary: Resets applied migrations up to the last n versions
    description: Resets applied migrations up to the last n versions.
    tags: []
    links: []
    usage: supabase migration down [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Resets applied migrations on the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: last
        name: --last <int>
        description: Reset up to the last n migration versions.
        default_value: '1'
      - id: linked
        name: --linked
        description: Resets applied migrations on the linked project.
        default_value: 'false'
      - id: local
        name: --local
        description: Resets applied migrations on the local database.
        default_value: 'true'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-migration-fetch
    title: supabase migration fetch
    summary: Fetch migration files from history table
    description: Fetch migration files from history table.
    tags: []
    links: []
    usage: supabase migration fetch [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Fetches migrations from the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: linked
        name: --linked
        description: Fetches migration history from the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Fetches migration history from the local database.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-migration-list
    title: supabase migration list
    summary: List local and remote migrations
    description: |


      Lists migration history in both local and remote databases.

      Requires your local project to be linked to a remote database by running `supabase link`. For self-hosted databases, you can pass in the connection parameters using `--db-url` flag.

      > Note that URL strings must be escaped according to [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986).

      Local migrations are stored in `supabase/migrations` directory while remote migrations are tracked in `supabase_migrations.schema_migrations` table. Only the timestamps are compared to identify any differences.

      In case of discrepancies between the local and remote migration history, you can resolve them using the `migration repair` command.
    examples:
      - id: basic-usage
        name: Basic usage
        code: supabase migration list
        response: |2
                LOCAL      │     REMOTE     │     TIME (UTC)
          ─────────────────┼────────────────┼──────────────────────
                           │ 20230103054303 │ 2023-01-03 05:43:03
                           │ 20230103093141 │ 2023-01-03 09:31:41
            20230222032233 │                │ 2023-02-22 03:22:33
      - id: with-db-url
        name: Connect to self-hosted database
        code: supabase migration list --db-url 'postgres://postgres[:percent_encoded_password]@127.0.0.1[:port]/postgres'
        response: |2
                LOCAL      │     REMOTE     │     TIME (UTC)
          ─────────────────┼────────────────┼──────────────────────
            20230103054303 │ 20230103054303 │ 2023-01-03 05:43:03
            20230103093141 │ 20230103093141 │ 2023-01-03 09:31:41
    tags: []
    links: []
    usage: supabase migration list [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Lists migrations of the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: linked
        name: --linked
        description: Lists migrations applied to the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Lists migrations applied to the local database.
        default_value: 'false'
      - id: password
        name: -p, --password <string>
        description: Password to your remote Postgres database.
        default_value: ''
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-migration-new
    title: supabase migration new
    summary: Create an empty migration script
    description: |


      Creates a new migration file locally.

      A `supabase/migrations` directory will be created if it does not already exists in your current `workdir`. All schema migration files must be created in this directory following the pattern `<timestamp>_<name>.sql`.

      Outputs from other commands like `db diff` may be piped to `migration new <name>` via stdin.
    examples:
      - id: basic-usage
        name: Basic usage
        code: supabase migration new schema_test
        response: |
          Created new migration at supabase/migrations/20230306095710_schema_test.sql.
      - id: pipe-stdin
        name: With statements piped from stdin
        code: echo "create schema if not exists test;" | supabase migration new schema_test
        response: |
          Created new migration at supabase/migrations/20230306095710_schema_test.sql.
    tags: []
    links: []
    usage: supabase migration new <migration name> [flags]
    subcommands: []
    flags: []
  - id: supabase-migration-repair
    title: supabase migration repair
    summary: Repair the migration history table
    description: |


      Repairs the remote migration history table.

      Requires your local project to be linked to a remote database by running `supabase link`.

      If your local and remote migration history goes out of sync, you can repair the remote history by marking specific migrations as `--status applied` or `--status reverted`. Marking as `reverted` will delete an existing record from the migration history table while marking as `applied` will insert a new record.

      For example, your migration history may look like the table below, with missing entries in either local or remote.

      ```bash
      $ supabase migration list
              LOCAL      │     REMOTE     │     TIME (UTC)
        ─────────────────┼────────────────┼──────────────────────
                         │ 20230103054303 │ 2023-01-03 05:43:03
         20230103054315  │                │ 2023-01-03 05:43:15
      ```

      To reset your migration history to a clean state, first delete your local migration file.

      ```bash
      $ rm supabase/migrations/20230103054315_remote_commit.sql

      $ supabase migration list
              LOCAL      │     REMOTE     │     TIME (UTC)
        ─────────────────┼────────────────┼──────────────────────
                         │ 20230103054303 │ 2023-01-03 05:43:03
      ```

      Then mark the remote migration `20230103054303` as reverted.

      ```bash
      $ supabase migration repair 20230103054303 --status reverted
      Connecting to remote database...
      Repaired migration history: [20220810154537] => reverted
      Finished supabase migration repair.

      $ supabase migration list
              LOCAL      │     REMOTE     │     TIME (UTC)
        ─────────────────┼────────────────┼──────────────────────
      ```

      Now you can run `db pull` again to dump the remote schema as a local migration file.

      ```bash
      $ supabase db pull
      Connecting to remote database...
      Schema written to supabase/migrations/20240414044403_remote_schema.sql
      Update remote migration history table? [Y/n]
      Repaired migration history: [20240414044403] => applied
      Finished supabase db pull.

      $ supabase migration list
              LOCAL      │     REMOTE     │     TIME (UTC)
        ─────────────────┼────────────────┼──────────────────────
          20240414044403 │ 20240414044403 │ 2024-04-14 04:44:03
      ```
    examples:
      - id: basic-usage
        name: Mark a migration as reverted
        code: supabase migration repair 20230103054303 --status reverted
        response: |
          Repaired migration history: 20230103054303 => reverted
      - id: mark-applied
        name: Mark a migration as applied
        code: supabase migration repair 20230222032233 --status applied
        response: |
          Repaired migration history: 20230222032233 => applied
    tags: []
    links: []
    usage: supabase migration repair [version] ... [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Repairs migrations of the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: linked
        name: --linked
        description: Repairs the migration history of the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Repairs the migration history of the local database.
        default_value: 'false'
      - id: password
        name: -p, --password <string>
        description: Password to your remote Postgres database.
        default_value: ''
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: status
        name: --status <[ applied | reverted ]>
        description: Version status to update.
        required: true
        default_value: ''
        accepted_values:
          - id: applied
            name: applied
            type: '[ applied | reverted ]'
          - id: reverted
            name: reverted
            type: '[ applied | reverted ]'
  - id: supabase-migration-squash
    title: supabase migration squash
    summary: Squash migrations to a single file
    description: |


      Squashes local schema migrations to a single migration file.

      The squashed migration is equivalent to a schema only dump of the local database after applying existing migration files. This is especially useful when you want to remove repeated modifications of the same schema from your migration history.

      However, one limitation is that data manipulation statements, such as insert, update, or delete, are omitted from the squashed migration. You will have to add them back manually in a new migration file. This includes cron jobs, storage buckets, and any encrypted secrets in vault.

      By default, the latest `<timestamp>_<name>.sql` file will be updated to contain the squashed migration. You can override the target version using the `--version <timestamp>` flag.

      If your `supabase/migrations` directory is empty, running `supabase squash` will do nothing.
    tags: []
    links: []
    usage: supabase migration squash [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Squashes migrations of the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: linked
        name: --linked
        description: Squashes the migration history of the linked project.
        default_value: 'false'
      - id: local
        name: --local
        description: Squashes the migration history of the local database.
        default_value: 'true'
      - id: password
        name: -p, --password <string>
        description: Password to your remote Postgres database.
        default_value: ''
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: version
        name: --version <string>
        description: Squash up to the specified version.
        default_value: ''
  - id: supabase-migration-up
    title: supabase migration up
    summary: Apply pending migrations to local database
    description: Apply pending migrations to local database.
    tags: []
    links: []
    usage: supabase migration up [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Applies migrations to the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: include-all
        name: --include-all
        description: Include all migrations not found on remote history table.
        default_value: 'false'
      - id: linked
        name: --linked
        description: Applies pending migrations to the linked project.
        default_value: 'false'
      - id: local
        name: --local
        description: Applies pending migrations to the local database.
        default_value: 'true'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-network-bans
    title: supabase network-bans
    summary: Manage network bans
    description: |


      Network bans are IPs that get temporarily blocked if their traffic pattern looks abusive (e.g. multiple failed auth attempts).

      The subcommands help you view the current bans, and unblock IPs if desired.
    tags:
      - management-api
    links: []
    subcommands:
      - supabase-network-bans-get
      - supabase-network-bans-remove
    flags: []
  - id: supabase-network-bans-get
    title: supabase network-bans get
    summary: Get the current network bans
    description: Get the current network bans.
    tags: []
    links: []
    usage: supabase network-bans get [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: experimental
        name: --experimental
        description: enable experimental features
        required: true
        default_value: 'false'
  - id: supabase-network-bans-remove
    title: supabase network-bans remove
    summary: Remove a network ban
    description: Remove a network ban.
    tags: []
    links: []
    usage: supabase network-bans remove [flags]
    subcommands: []
    flags:
      - id: db-unban-ip
        name: --db-unban-ip <strings>
        description: IP to allow DB connections from.
        default_value: '[]'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: experimental
        name: --experimental
        description: enable experimental features
        required: true
        default_value: 'false'
  - id: supabase-network-restrictions
    title: supabase network-restrictions
    summary: Manage network restrictions
    description: Manage network restrictions.
    tags:
      - management-api
    links: []
    subcommands:
      - supabase-network-restrictions-get
      - supabase-network-restrictions-update
    flags: []
  - id: supabase-network-restrictions-get
    title: supabase network-restrictions get
    summary: Get the current network restrictions
    description: Get the current network restrictions.
    tags: []
    links: []
    usage: supabase network-restrictions get [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: experimental
        name: --experimental
        description: enable experimental features
        required: true
        default_value: 'false'
  - id: supabase-network-restrictions-update
    title: supabase network-restrictions update
    summary: Update network restrictions
    description: Update network restrictions.
    tags: []
    links: []
    usage: supabase network-restrictions update [flags]
    subcommands: []
    flags:
      - id: append
        name: --append
        description: Append to existing restrictions instead of replacing them.
        default_value: 'false'
      - id: bypass-cidr-checks
        name: --bypass-cidr-checks
        description: Bypass some of the CIDR validation checks.
        default_value: 'false'
      - id: db-allow-cidr
        name: --db-allow-cidr <strings>
        description: CIDR to allow DB connections from.
        default_value: '[]'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: experimental
        name: --experimental
        description: enable experimental features
        required: true
        default_value: 'false'
  - id: supabase-notebooks
    title: supabase notebooks
    summary: Manage Supabase notebooks
    description: 'Manage Supabase notebooks: SQL and markdown cells stored with your project, kept in supabase/notebooks/<name>.json.'
    tags:
      - management-api
    links: []
    subcommands:
      - supabase-notebooks-pull
      - supabase-notebooks-push
    flags: []
  - id: supabase-notebooks-pull
    title: supabase notebooks pull
    summary: Pull notebooks from Supabase
    description: Write the linked Supabase project's notebooks into supabase/notebooks. Without a notebook id, existing local files are preserved and only missing notebooks are written.
    examples:
      - id: example-1
        name: Pull every notebook from the linked project
        code: supabase notebooks pull
      - id: example-2
        name: Replace the local copy of one notebook by id
        code: supabase notebooks pull 44444444-4444-4444-8444-444444444444
    tags: []
    links: []
    usage: supabase notebooks pull [Notebook id] [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-notebooks-push
    title: supabase notebooks push
    summary: Push notebooks to Supabase
    description: Write supabase/notebooks into the linked Supabase project. If no notebook name is provided, pushes all of them and asks what to do about project notebooks the directory does not have.
    examples:
      - id: example-1
        name: Push every notebook in supabase/notebooks to the linked project
        code: supabase notebooks push
      - id: example-2
        name: Push a single notebook by name
        code: supabase notebooks push sales-dashboard
    tags: []
    links: []
    usage: supabase notebooks push [Notebook name] [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-orgs
    title: supabase orgs
    summary: Manage Supabase organizations
    description: Manage Supabase organizations
    tags:
      - management-api
    links: []
    subcommands:
      - supabase-orgs-create
      - supabase-orgs-list
    flags: []
  - id: supabase-orgs-create
    title: supabase orgs create
    summary: Create an organization
    description: Create an organization for the logged-in user.
    tags: []
    links: []
    usage: supabase orgs create <name> [flags]
    subcommands: []
    flags: []
  - id: supabase-orgs-list
    title: supabase orgs list
    summary: List all organizations
    description: List all organizations the logged-in user belongs.
    tags: []
    links: []
    usage: supabase orgs list [flags]
    subcommands: []
    flags: []
  - id: supabase-postgres-config
    title: supabase postgres-config
    summary: Manage Postgres database config
    description: Manage Postgres database config.
    tags:
      - management-api
    links: []
    subcommands:
      - supabase-postgres-config-delete
      - supabase-postgres-config-get
      - supabase-postgres-config-update
    flags: []
  - id: supabase-postgres-config-delete
    title: supabase postgres-config delete
    summary: Delete Postgres database config overrides
    description: Delete specific Postgres database config overrides.
    tags: []
    links: []
    usage: supabase postgres-config delete [flags]
    subcommands: []
    flags:
      - id: config
        name: --config <strings>
        description: Config keys to delete (comma-separated)
        default_value: '[]'
      - id: no-restart
        name: --no-restart
        description: Do not restart the database after deleting config.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: experimental
        name: --experimental
        description: enable experimental features
        required: true
        default_value: 'false'
  - id: supabase-postgres-config-get
    title: supabase postgres-config get
    summary: Get Postgres database config
    description: Get the current Postgres database config overrides.
    tags: []
    links: []
    usage: supabase postgres-config get [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: experimental
        name: --experimental
        description: enable experimental features
        required: true
        default_value: 'false'
  - id: supabase-postgres-config-update
    title: supabase postgres-config update
    summary: Update Postgres database config
    description: |


      Overriding the default Postgres config could result in unstable database behavior.
      Custom configuration also overrides the optimizations generated based on the compute add-ons in use.
    tags: []
    links: []
    usage: supabase postgres-config update [flags]
    subcommands: []
    flags:
      - id: config
        name: --config <strings>
        description: Config overrides specified as a 'key=value' pair
        default_value: '[]'
      - id: no-restart
        name: --no-restart
        description: Do not restart the database after updating config.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: replace-existing-overrides
        name: --replace-existing-overrides
        description: If true, replaces all existing overrides with the ones provided. If false (default), merges existing overrides with the ones provided.
        default_value: 'false'
      - id: experimental
        name: --experimental
        description: enable experimental features
        required: true
        default_value: 'false'
  - id: supabase-projects
    title: supabase projects
    summary: Manage projects
    description: |


      Provides tools for creating and managing your Supabase projects.

      This command group allows you to list all projects in your organizations, create new projects, delete existing projects, and retrieve API keys. These operations help you manage your Supabase infrastructure programmatically without using the dashboard.

      Project management via CLI is especially useful for automation scripts and when you need to provision environments in a repeatable way.
    tags:
      - management-api
    links: []
    subcommands:
      - supabase-projects-api-keys
      - supabase-projects-create
      - supabase-projects-delete
      - supabase-projects-list
    flags: []
  - id: supabase-projects-api-keys
    title: supabase projects api-keys
    summary: List API keys
    description: List all API keys for a Supabase project.
    examples:
      - id: example-1
        name: List all API keys for a project
        code: supabase projects api-keys --project-ref abcdefghijklmnopqrst
      - id: example-2
        name: List API keys with the secret keys revealed in full
        code: supabase projects api-keys --reveal --output json
    tags: []
    links: []
    usage: supabase projects api-keys [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: reveal
        name: --reveal
        description: Reveal the secret API keys in full (e.g. sb_secret_...).
        default_value: 'false'
  - id: supabase-projects-create
    title: supabase projects create
    summary: Create a project
    description: Create a project on Supabase.
    examples:
      - id: example-1
        name: Create a new project
        code: supabase projects create my-project --org-id cool-green-pqdr0qc --db-password ******** --region us-east-1
    tags: []
    links: []
    usage: supabase projects create [name] [flags]
    subcommands: []
    flags:
      - id: db-password
        name: --db-password <string>
        description: Database password of the project.
        default_value: ''
      - id: high-availability
        name: --high-availability
        description: Enable high availability for the project.
        default_value: 'false'
      - id: org-id
        name: --org-id <string>
        description: Organization ID to create the project in.
        default_value: ''
      - id: region
        name: --region <string>
        description: Select a region close to you for the best performance.
        default_value: ''
        accepted_values:
          - id: ap-east-1
            name: ap-east-1
            type: string
          - id: ap-northeast-1
            name: ap-northeast-1
            type: string
          - id: ap-northeast-2
            name: ap-northeast-2
            type: string
          - id: ap-south-1
            name: ap-south-1
            type: string
          - id: ap-southeast-1
            name: ap-southeast-1
            type: string
          - id: ap-southeast-2
            name: ap-southeast-2
            type: string
          - id: ca-central-1
            name: ca-central-1
            type: string
          - id: eu-central-1
            name: eu-central-1
            type: string
          - id: eu-central-2
            name: eu-central-2
            type: string
          - id: eu-north-1
            name: eu-north-1
            type: string
          - id: eu-west-1
            name: eu-west-1
            type: string
          - id: eu-west-2
            name: eu-west-2
            type: string
          - id: eu-west-3
            name: eu-west-3
            type: string
          - id: sa-east-1
            name: sa-east-1
            type: string
          - id: us-east-1
            name: us-east-1
            type: string
          - id: us-east-2
            name: us-east-2
            type: string
          - id: us-west-1
            name: us-west-1
            type: string
          - id: us-west-2
            name: us-west-2
            type: string
      - id: size
        name: --size <string>
        description: Select a desired instance size for your project.
        default_value: ''
        accepted_values:
          - id: large
            name: large
            type: string
          - id: medium
            name: medium
            type: string
          - id: micro
            name: micro
            type: string
          - id: 12xlarge
            name: 12xlarge
            type: string
          - id: 16xlarge
            name: 16xlarge
            type: string
          - id: 24xlarge
            name: 24xlarge
            type: string
          - id: 24xlarge_high_memory
            name: 24xlarge_high_memory
            type: string
          - id: 24xlarge_optimized_cpu
            name: 24xlarge_optimized_cpu
            type: string
          - id: 24xlarge_optimized_memory
            name: 24xlarge_optimized_memory
            type: string
          - id: 2xlarge
            name: 2xlarge
            type: string
          - id: 48xlarge
            name: 48xlarge
            type: string
          - id: 48xlarge_high_memory
            name: 48xlarge_high_memory
            type: string
          - id: 48xlarge_optimized_cpu
            name: 48xlarge_optimized_cpu
            type: string
          - id: 48xlarge_optimized_memory
            name: 48xlarge_optimized_memory
            type: string
          - id: 4xlarge
            name: 4xlarge
            type: string
          - id: 8xlarge
            name: 8xlarge
            type: string
          - id: small
            name: small
            type: string
          - id: xlarge
            name: xlarge
            type: string
  - id: supabase-projects-delete
    title: supabase projects delete
    summary: Delete a project
    description: Delete a Supabase project.
    examples:
      - id: example-1
        name: Delete a project by ref
        code: supabase projects delete abcdefghijklmnopqrst
    tags: []
    links: []
    usage: supabase projects delete [ref] [flags]
    subcommands: []
    flags: []
  - id: supabase-projects-list
    title: supabase projects list
    summary: List all projects
    description: List all Supabase projects the logged-in user can access.
    examples:
      - id: example-1
        name: List all projects
        code: supabase projects list
      - id: example-2
        name: Machine-readable JSON output
        code: supabase projects list --output-format json
    tags: []
    links: []
    usage: supabase projects list [flags]
    subcommands: []
    flags: []
  - id: supabase-pull
    title: supabase pull
    summary: Pull remote project state into the local checkout
    description: |


      Refreshes local project state from a linked Supabase project or branch in one step, instead of running `config pull`, `db pull`, `migration fetch`, and `functions download` individually. It runs four steps, always in this order: pull config into `supabase/config.toml`, optionally fetch the remote migration history table into `supabase/migrations`, pull the database schema into `supabase/migrations` (also updating that database's own migration history table), and download every Edge Function's source into `supabase/functions`. The order is fixed rather than parallel: the database step depends on `db.major_version` in the config file the first step may have just changed, and on the local migration history the second step may have just populated.

      Pass `--project-ref` to target a specific project, or the name (or UUID) of a branch of the currently linked project — values that are exactly 20 lowercase letters are always treated as project refs. Without it, the linked project is the target. `--remote-label` overrides the `[remotes.*]` block the config step would otherwise reuse or create for that target, identically to `config pull`'s own flag of the same name (see `supabase config pull`'s docs for the reuse/creation rules it follows).

      On a fresh checkout, the migration history step runs automatically even without `--with-migration-history`, whenever `supabase/migrations` is missing or a raw directory listing of it turns up no entries at all — the same "existing files" check `migration fetch` itself uses, so a directory holding only a `.gitkeep`/`README.md` already counts as non-empty for this purpose (the listing is unfiltered — any entry at all disqualifies it) and the two commands never disagree about it. There's nothing local to overwrite when the directory is truly empty or missing, and it's what lets the database step run at all: without it, `db pull` would hard-fail comparing an empty local directory against a remote project that already has migration history. Pass `--with-migration-history` to force a re-fetch whenever the directory already has any files in it, including only non-migration ones — unlike the bootstrap case, this DOES overwrite: any local migration file that shares a name with a remote history entry is replaced.

      `supabase pull` shows one confirmation before writing anything, covering all four steps. It opens by naming the target (`Pulling from project <ref>`, or with `(branch "<name>")` appended when the target is a branch), then lists the four steps in the order they run: the config step's part is a real diff, computed the same way `config diff`/`config pull` compute theirs (or "No config differences found." when there is nothing to change); the migration-history line only appears when that step will actually run this invocation, and calls out that it overwrites same-named local files when it's running because of `--with-migration-history` rather than the bootstrap case; the database line notes that it also updates the remote migration history table and requires Docker; the functions line describes the download. `--dry-run` prints this exact same disclosure body — not a placeholder or a status-only summary — before exiting without writing or changing anything. `--yes` skips the confirmation and takes its default answer.

      `supabase pull` checks THREE locations for uncommitted or untracked changes in git before writing: `supabase/config.toml` (or `config.json`), `supabase/migrations`, and `supabase/functions`. The config check only fires when the config step itself has work to write — a config that's already fully converged with the target never triggers it. The other two fire unconditionally: the database step always attempts to run and has no way to know in advance whether it will find schema drift and write into `supabase/migrations`, and the functions step always runs with no equivalent "nothing to do" signal available without calling the API first — so both are checked every run to avoid silently missing real uncommitted work. Each location's dirty state is tracked separately: the confirmation body and any abort message name exactly which path(s) are actually dirty, e.g. `supabase/config.toml has uncommitted or untracked changes...` for one, or `supabase/config.toml, supabase/migrations, and supabase/functions have uncommitted or untracked changes...` when all three are. `--force` writes even when any of the three is dirty — without it, an interactive run's confirmation defaults to declining instead of proceeding, and every other case (non-interactive, machine output format, or `--yes` on any TTY) aborts outright rather than silently overwriting local edits.

      **This command is not purely a local, read-only refresh.** Pulling the database schema also updates that database's own migration history table on the **remote** project — the same behavior `db pull` has always had — not just a local file write. The database step also requires Docker (it runs a shadow Postgres container, and — on the very first pull — a `pg_dump` container) to compute the schema diff. Without Docker running, that one step fails and is reported as such, but the other three steps (config, migration history, functions) still run and complete normally; a project with nothing in its database yet can still successfully pull its config and functions without Docker installed.

      If the database is already in sync with the local migrations, that step reports `unchanged` rather than failing — this differs from running `supabase db pull` directly, which treats "nothing to pull" as an error condition.

      Storage bucket definitions are not pulled by this command: the Management API doesn't currently return enough detail (file size limits, allowed MIME types, the storage backend path) to populate `storage.buckets` config faithfully.

      ## Example

      ```sh
      supabase pull
      ```

      Pulls config, database schema, and functions from the linked project, fetching migration history first if `supabase/migrations` is empty.

      ```sh
      supabase pull --project-ref staging
      ```

      Pulls from the `staging` branch of the linked project.

      ```sh
      supabase pull --dry-run
      ```

      Prints the full confirmation body — the target header, the real config diff (or "No config differences found."), the migration-history/database/functions lines (including the Docker mention and, if applicable, the uncommitted-changes warning) — without writing or changing anything.

      ```sh
      supabase pull --remote-label staging
      ```

      Pulls into the `[remotes.staging]` block instead of whatever block the target would otherwise reuse or create.

      Machine-readable output is available through `--output-format json|stream-json` — a single object (`schema_version`, `target`, `dry_run`, `confirmed`, `wrote`, `step_order`, `steps`, `counts`) with one entry per step under `steps`, keyed `config`, `migration_history`, `db`, and `functions`, each carrying its own `status` (`changed`, `unchanged`, `skipped`, `planned`, or `failed`), the paths it wrote, and a step-specific `detail` object. The legacy global `-o`/`--output` flag is not supported by this command; use `--output-format json|stream-json` instead.
    examples:
      - id: example-1
        name: Pull config, schema, and functions from the linked project
        code: supabase pull
      - id: example-2
        name: Pull from the 'staging' branch of the linked project
        code: supabase pull --project-ref staging
      - id: example-3
        name: Preview what would be pulled without writing anything
        code: supabase pull --dry-run
    tags:
      - other-commands
    links: []
    usage: supabase pull [flags]
    subcommands: []
    flags:
      - id: dry-run
        name: --dry-run
        description: Show what would be pulled without writing or changing anything.
        default_value: 'false'
      - id: force
        name: --force
        description: Write even when supabase/config.toml (or config.json), supabase/migrations, or supabase/functions has uncommitted or untracked changes in git.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project, or the name (or UUID) of one of its branches. Values that are exactly 20 lowercase letters are always treated as project refs.
        default_value: ''
      - id: remote-label
        name: --remote-label <string>
        description: Name of the [remotes.*] block the config step writes into, overriding the block it would otherwise reuse or create.
        default_value: ''
      - id: with-migration-history
        name: --with-migration-history
        description: Fetch the remote migration history table into supabase/migrations, even when it already has files. Runs automatically when supabase/migrations is missing or empty.
        default_value: 'false'
  - id: supabase-secrets
    title: supabase secrets
    summary: Manage Supabase secrets
    description: |


      Provides tools for managing environment variables and secrets for your Supabase project.

      This command group allows you to set, unset, and list secrets that are securely stored and made available to Edge Functions as environment variables.

      Secrets management through the CLI is useful for:

      - Setting environment-specific configuration
      - Managing sensitive credentials securely

      Secrets can be set individually or loaded from .env files for convenience.
    tags:
      - management-api
    links: []
    subcommands:
      - supabase-secrets-list
      - supabase-secrets-set
      - supabase-secrets-unset
    flags: []
  - id: supabase-secrets-list
    title: supabase secrets list
    summary: List all secrets on Supabase
    description: List all secrets in the linked project.
    examples:
      - id: example-1
        name: List all secrets for the linked project
        code: supabase secrets list
      - id: example-2
        name: List secrets for a specific project
        code: supabase secrets list --project-ref abcdefghijklmnopqrst
    tags: []
    links: []
    usage: supabase secrets list [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-secrets-set
    title: supabase secrets set
    summary: Set a secret(s) on Supabase
    description: Set a secret(s) to the linked Supabase project.
    examples:
      - id: example-1
        name: Set a secret by name and value
        code: supabase secrets set MY_SECRET=myvalue
      - id: example-2
        name: Set secrets from a .env file
        code: supabase secrets set --env-file .env
    tags: []
    links: []
    usage: supabase secrets set <NAME=VALUE> ... [flags]
    subcommands: []
    flags:
      - id: env-file
        name: --env-file <string>
        description: Read secrets from a .env file.
        default_value: ''
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-secrets-unset
    title: supabase secrets unset
    summary: Unset a secret(s) on Supabase
    description: Unset a secret(s) from the linked Supabase project.
    examples:
      - id: example-1
        name: Unset a secret by name
        code: supabase secrets unset MY_SECRET
      - id: example-2
        name: Unset multiple secrets
        code: supabase secrets unset MY_SECRET OTHER_SECRET
    tags: []
    links: []
    usage: supabase secrets unset [NAME] ... [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-seed
    title: supabase seed
    summary: Seed a Supabase project
    description: Seed a Supabase project from supabase/config.toml.
    tags:
      - local-dev
    links: []
    subcommands:
      - supabase-seed-buckets
    flags: []
  - id: supabase-seed-buckets
    title: supabase seed buckets
    summary: Seed buckets declared in [storage.buckets]
    description: Seed buckets declared in [storage.buckets].
    tags: []
    links: []
    usage: supabase seed buckets [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: linked
        name: --linked
        description: Seeds the linked project.
        default_value: 'false'
      - id: local
        name: --local
        description: Seeds the local database.
        default_value: 'true'
  - id: supabase-services
    title: supabase services
    summary: Show versions of all Supabase services
    description: Show versions of all Supabase services.
    tags:
      - local-dev
    links: []
    usage: supabase services [flags]
    subcommands: []
    flags: []
  - id: supabase-snippets
    title: supabase snippets
    summary: Manage Supabase SQL snippets
    description: Manage Supabase SQL snippets.
    tags:
      - management-api
    links: []
    subcommands:
      - supabase-snippets-download
      - supabase-snippets-list
    flags: []
  - id: supabase-snippets-download
    title: supabase snippets download
    summary: Download contents of a SQL snippet
    description: Download contents of the specified SQL snippet.
    examples:
      - id: example-1
        name: Download the SQL contents of the given snippet
        code: supabase snippets download <snippet-id>
    tags: []
    links: []
    usage: supabase snippets download <snippet-id> [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-snippets-list
    title: supabase snippets list
    summary: List all SQL snippets
    description: List all SQL snippets of the linked project.
    examples:
      - id: example-1
        name: List all SQL snippets
        code: supabase snippets list
      - id: example-2
        name: List snippets for a specific project
        code: supabase snippets list --project-ref <ref>
    tags: []
    links: []
    usage: supabase snippets list [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-ssl-enforcement
    title: supabase ssl-enforcement
    summary: Manage SSL enforcement
    description: Manage SSL enforcement configuration.
    tags:
      - management-api
    links: []
    subcommands:
      - supabase-ssl-enforcement-get
      - supabase-ssl-enforcement-update
    flags: []
  - id: supabase-ssl-enforcement-get
    title: supabase ssl-enforcement get
    summary: Get SSL enforcement configuration
    description: Get the current SSL enforcement configuration.
    tags: []
    links: []
    usage: supabase ssl-enforcement get [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: experimental
        name: --experimental
        description: enable experimental features
        required: true
        default_value: 'false'
  - id: supabase-ssl-enforcement-update
    title: supabase ssl-enforcement update
    summary: Update SSL enforcement configuration
    description: Update SSL enforcement configuration.
    tags: []
    links: []
    usage: supabase ssl-enforcement update [flags]
    subcommands: []
    flags:
      - id: disable-db-ssl-enforcement
        name: --disable-db-ssl-enforcement
        description: Whether the DB should disable SSL enforcement for all external connections.
        default_value: 'false'
      - id: enable-db-ssl-enforcement
        name: --enable-db-ssl-enforcement
        description: Whether the DB should enable SSL enforcement for all external connections.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: experimental
        name: --experimental
        description: enable experimental features
        required: true
        default_value: 'false'
  - id: supabase-sso
    title: supabase sso
    summary: Manage Single Sign-On (SSO) authentication
    description: Manage Single Sign-On (SSO) authentication for projects.
    tags:
      - management-api
    links: []
    subcommands:
      - supabase-sso-add
      - supabase-sso-info
      - supabase-sso-list
      - supabase-sso-remove
      - supabase-sso-show
      - supabase-sso-update
    flags: []
  - id: supabase-sso-add
    title: supabase sso add
    summary: Add a new SSO identity provider
    description: Add and configure a new connection to a SSO identity provider to your Supabase project.
    examples:
      - id: basic-usage
        name: Add with Metadata URL
        code: |-
          supabase sso add \
            --project-ref abcdefgijklmnopqrst \
            --type saml \
            --metadata-url 'https://...' \
            --domains company.com
        response: |-
          Information about the added identity provider. You can use
          company.com as the domain name on the frontend side to initiate a SSO
          request to the identity provider.
      - id: with-xml
        name: Add with Metadata File
        code: |-
          supabase sso add \
            --project-ref abcdefgijklmnopqrst \
            --type saml \
            --metadata-file /path/to/metadata/file.xml \
            --domains company.com
        response: |-
          Information about the added identity provider. You can use
          company.com as the domain name on the frontend side to initiate a SSO
          request to the identity provider.
    tags: []
    links: []
    usage: supabase sso add [flags]
    subcommands: []
    flags:
      - id: attribute-mapping-file
        name: --attribute-mapping-file <string>
        description: File containing a JSON mapping between SAML attributes to custom JWT claims.
        default_value: ''
      - id: domains
        name: --domains <strings>
        description: Comma separated list of email domains to associate with the added identity provider.
        default_value: '[]'
      - id: metadata-file
        name: --metadata-file <string>
        description: File containing a SAML 2.0 Metadata XML document describing the identity provider.
        default_value: ''
      - id: metadata-url
        name: --metadata-url <string>
        description: URL pointing to a SAML 2.0 Metadata XML document describing the identity provider.
        default_value: ''
      - id: name-id-format
        name: --name-id-format <string>
        description: URI reference representing the classification of string-based identifier information.
        default_value: ''
        accepted_values:
          - id: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
            name: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
            type: string
          - id: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
            name: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
            type: string
          - id: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
            name: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
            type: string
          - id: urn:oasis:names:tc:SAML:2.0:nameid-format:transient
            name: urn:oasis:names:tc:SAML:2.0:nameid-format:transient
            type: string
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: skip-url-validation
        name: --skip-url-validation
        description: Skip local validation of the SAML 2.0 Metadata URL (HTTPS requirement, live GET probe, and UTF-8 body decode). Use in air-gapped CI where the IDP is not reachable from the build agent.
        default_value: 'false'
      - id: type
        name: -t, --type <[ saml ]>
        description: Type of identity provider (according to supported protocol).
        required: true
        default_value: ''
        accepted_values:
          - id: saml
            name: saml
            type: '[ saml ]'
  - id: supabase-sso-info
    title: supabase sso info
    summary: Returns the SAML SSO settings required for the identity provider
    description: Returns all of the important SSO information necessary for your project to be registered with a SAML 2.0 compatible identity provider.
    examples:
      - id: basic-usage
        name: Show project information
        code: supabase sso info --project-ref abcdefghijklmnopqrst
        response: Information about your project's SAML 2.0 configuration.
    tags: []
    links: []
    usage: supabase sso info [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-sso-list
    title: supabase sso list
    summary: List all SSO identity providers
    description: List all SSO identity providers for a project.
    examples:
      - id: example-1
        name: List all SSO providers for a project
        code: supabase sso list --project-ref mwjylndxudmiehsxhmmz
    tags: []
    links: []
    usage: supabase sso list [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-sso-remove
    title: supabase sso remove
    summary: Remove an existing SSO identity provider
    description: Remove a connection to an already added SSO identity provider. Removing the provider will prevent existing users from logging in. Please treat this command with care.
    examples:
      - id: basic-usage
        name: Remove a provider
        code: |-
          supabase sso remove 6df4d73f-bf21-405f-a084-b11adf19fea5 \
            --project-ref abcdefghijklmnopqrst
        response: |-
          Information about the removed identity provider. It's a good idea to
          save this in case you need it later on.
    tags: []
    links: []
    usage: supabase sso remove <provider-id> [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-sso-show
    title: supabase sso show
    summary: Show information about an SSO identity provider
    description: Provides the information about an established connection to an identity provider. You can use --metadata to obtain the raw SAML 2.0 Metadata XML document stored in your project's configuration.
    examples:
      - id: basic-usage
        name: Show information
        code: |-
          supabase sso show 6df4d73f-bf21-405f-a084-b11adf19fea5 \
            --project-ref abcdefghijklmnopqrst
        response: Information about the identity provider in pretty output.
      - id: metadata-output
        name: Get raw SAML 2.0 Metadata XML
        code: |-
          supabase sso show 6df4d73f-bf21-405f-a084-b11adf19fea5 \
            --project-ref abcdefghijklmnopqrst \
            --metadata
        response: |-
          Raw SAML 2.0 XML assigned to this identity provider. This is the
          version used in the authentication project, and if using a SAML 2.0
          Metadata URL it may change depending on the caching information
          contained within the metadata.
    tags: []
    links: []
    usage: supabase sso show <provider-id> [flags]
    subcommands: []
    flags:
      - id: metadata
        name: --metadata
        description: Show SAML 2.0 XML Metadata only
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-sso-update
    title: supabase sso update
    summary: Update information about an SSO identity provider
    description: Update the configuration settings of a already added SSO identity provider.
    examples:
      - id: basic-usage
        name: Replace domains
        code: |-
          supabase sso update 6df4d73f-bf21-405f-a084-b11adf19fea5 \
            --project-ref abcdefghijklmnopqrst \
            --domains new-company.com,new-company.net
        response: Information about the updated provider.
      - id: add-domains
        name: Add an additional domain
        code: |-
          supabase sso update 6df4d73f-bf21-405f-a084-b11adf19fea5 \
            --project-ref abcdefghijklmnopqrst \
            --add-domains company.net
        response: Information about the updated provider.
      - id: remove-domains
        name: Remove a domain
        code: |-
          supabase sso update 6df4d73f-bf21-405f-a084-b11adf19fea5 \
            --project-ref abcdefghijklmnopqrst \
            --remove-domains company.org
        response: Information about the updated provider.
    tags: []
    links: []
    usage: supabase sso update <provider-id> [flags]
    subcommands: []
    flags:
      - id: add-domains
        name: --add-domains <strings>
        description: Add this comma separated list of email domains to the identity provider.
        default_value: '[]'
      - id: attribute-mapping-file
        name: --attribute-mapping-file <string>
        description: File containing a JSON mapping between SAML attributes to custom JWT claims.
        default_value: ''
      - id: domains
        name: --domains <strings>
        description: Replace domains with this comma separated list of email domains.
        default_value: '[]'
      - id: metadata-file
        name: --metadata-file <string>
        description: File containing a SAML 2.0 Metadata XML document describing the identity provider.
        default_value: ''
      - id: metadata-url
        name: --metadata-url <string>
        description: URL pointing to a SAML 2.0 Metadata XML document describing the identity provider.
        default_value: ''
      - id: name-id-format
        name: --name-id-format <string>
        description: URI reference representing the classification of string-based identifier information.
        default_value: ''
        accepted_values:
          - id: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
            name: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
            type: string
          - id: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
            name: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
            type: string
          - id: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
            name: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
            type: string
          - id: urn:oasis:names:tc:SAML:2.0:nameid-format:transient
            name: urn:oasis:names:tc:SAML:2.0:nameid-format:transient
            type: string
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: remove-domains
        name: --remove-domains <strings>
        description: Remove this comma separated list of email domains from the identity provider.
        default_value: '[]'
      - id: skip-url-validation
        name: --skip-url-validation
        description: Skip local validation of the SAML 2.0 Metadata URL (HTTPS requirement, live GET probe, and UTF-8 body decode). Use in air-gapped CI where the IDP is not reachable from the build agent.
        default_value: 'false'
  - id: supabase-start
    title: supabase start
    summary: Start local Supabase stack
    description: |


      Starts the Supabase local development stack.

      Requires `supabase/config.toml` to be created in your current working directory by running `supabase init`.

      All service containers are started by default. You can exclude those not needed by passing in `-x` flag. To exclude multiple containers, either pass in a comma separated string, such as `-x gotrue,imgproxy`, or specify `-x` flag multiple times.

      > It is recommended to have at least 7GB of RAM to start all services.

      Health checks are automatically added to verify the started containers. Use `--ignore-health-check` flag to ignore these errors.

      > If the CLI is running inside a dev container with the Docker socket bind-mounted, set the `SUPABASE_SERVICES_HOSTNAME` environment variable to the hostname reachable from inside that container, such as `host.docker.internal`.
    examples:
      - id: basic-usage
        name: Basic usage
        code: supabase start
        response: |
          Creating custom roles supabase/roles.sql...
          Applying migration 20220810154536_employee.sql...
          Seeding data supabase/seed.sql...
          Started supabase local development setup.
      - id: without-studio
        name: Start containers without studio and imgproxy
        code: supabase start -x studio,imgproxy
        response: |
          Excluding container: supabase/studio:20221214-4eecc99
          Excluding container: darthsim/imgproxy:v3.8.0
          Started supabase local development setup.
      - id: ignore-health-check
        name: Ignore service health checks
        code: supabase start --ignore-health-check
        response: |
          service not healthy: [supabase_storage_cli]
          Started supabase local development setup.
    tags:
      - local-dev
    links: []
    usage: supabase start [flags]
    subcommands: []
    flags:
      - id: exclude
        name: -x, --exclude <strings>
        description: Names of containers to not start. [gotrue,realtime,storage-api,imgproxy,kong,mailpit,postgrest,postgres-meta,studio,edge-runtime,logflare,vector,supavisor]
        default_value: '[]'
      - id: ignore-health-check
        name: --ignore-health-check
        description: Ignore unhealthy services and exit 0
        default_value: 'false'
  - id: supabase-status
    title: supabase status
    summary: Show status of local Supabase containers
    description: |


      Shows status of the Supabase local development stack.

      Requires the local development stack to be started by running `supabase start` or `supabase db start`.

      You can export the connection parameters for [initializing supabase-js](https://supabase.com/docs/reference/javascript/initializing) locally by specifying the `-o env` flag. Supported parameters include `JWT_SECRET`, `ANON_KEY`, and `SERVICE_ROLE_KEY`.
    examples:
      - id: basic-usage
        name: Basic usage
        code: supabase status
        response: |
          supabase local development setup is running.

                   API URL: http://127.0.0.1:54321
               GraphQL URL: http://127.0.0.1:54321/graphql/v1
                    DB URL: postgresql://postgres:postgres@127.0.0.1:54322/postgres
                Studio URL: http://127.0.0.1:54323
              Inbucket URL: http://127.0.0.1:54324
                JWT secret: super-secret-jwt-token-with-at-least-32-characters-long
                  anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0
          service_role key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImV4cCI6MTk4MzgxMjk5Nn0.EGIM96RAZx35lJzdJsyH-qQwv8Hdp7fsn3W0YpN81IU
      - id: output-env
        name: Format status as environment variables
        code: supabase status -o env
        response: |
          ANON_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0"
          API_URL="http://127.0.0.1:54321"
          DB_URL="postgresql://postgres:postgres@127.0.0.1:54322/postgres"
          GRAPHQL_URL="http://127.0.0.1:54321/graphql/v1"
          INBUCKET_URL="http://127.0.0.1:54324"
          JWT_SECRET="super-secret-jwt-token-with-at-least-32-characters-long"
          SERVICE_ROLE_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImV4cCI6MTk4MzgxMjk5Nn0.EGIM96RAZx35lJzdJsyH-qQwv8Hdp7fsn3W0YpN81IU"
          STUDIO_URL="http://127.0.0.1:54323"
      - id: output-custom-name
        name: Customize the names of exported variables
        code: supabase status -o env --override-name auth.anon_key=SUPABASE_ANON_KEY --override-name auth.service_role_key=SUPABASE_SERVICE_KEY
        response: |
          Stopped services: [supabase_inbucket_cli supabase_rest_cli supabase_studio_cli]
          SUPABASE_ANON_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0"
          DB_URL="postgresql://postgres:postgres@127.0.0.1:54322/postgres"
          GRAPHQL_URL="http://127.0.0.1:54321/graphql/v1"
          JWT_SECRET="super-secret-jwt-token-with-at-least-32-characters-long"
          SUPABASE_SERVICE_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImV4cCI6MTk4MzgxMjk5Nn0.EGIM96RAZx35lJzdJsyH-qQwv8Hdp7fsn3W0YpN81IU"
    tags:
      - local-dev
    links: []
    usage: supabase status [flags]
    subcommands: []
    flags:
      - id: override-name
        name: --override-name <strings>
        description: Override specific variable names.
        default_value: '[]'
  - id: supabase-stop
    title: supabase stop
    summary: Stop all local Supabase containers
    description: |


      Stops the Supabase local development stack.

      Requires `supabase/config.toml` to be created in your current working directory by running `supabase init`.

      All Docker resources are maintained across restarts. Use `--no-backup` flag to reset your local development data between restarts.

      Use the `--all` flag to stop all local Supabase projects instances on the machine. Use with caution with `--no-backup` as it will delete all supabase local projects data.
    examples:
      - id: basic-usage
        name: Basic usage
        code: supabase stop
        response: |
          Stopped supabase local development setup.
          Local data are backed up to docker volume.
      - id: clean-up
        name: Clean up local data after stopping
        code: supabase stop --no-backup
        response: |
          Stopped supabase local development setup.
    tags:
      - local-dev
    links: []
    usage: supabase stop [flags]
    subcommands: []
    flags:
      - id: all
        name: --all
        description: Stop all local Supabase instances from all projects across the machine.
        default_value: 'false'
      - id: no-backup
        name: --no-backup
        description: Deletes all data volumes after stopping.
        default_value: 'false'
      - id: project-id
        name: --project-id <string>
        description: Local project ID to stop.
        default_value: ''
  - id: supabase-storage
    title: supabase storage
    summary: Manage Supabase Storage objects
    description: Manage Supabase Storage objects.
    tags:
      - management-api
    links: []
    subcommands:
      - supabase-storage-cp
      - supabase-storage-ls
      - supabase-storage-mv
      - supabase-storage-rm
    flags: []
  - id: supabase-storage-cp
    title: supabase storage cp
    summary: Copy objects from src to dst path
    description: Copy objects from src to dst path.
    examples:
      - id: example-1
        name: Upload a local file to storage
        code: supabase storage cp readme.md ss:///bucket/readme.md
      - id: example-2
        name: Upload a directory recursively to storage
        code: supabase storage cp -r docs ss:///bucket/docs
      - id: example-3
        name: Download a directory from storage
        code: supabase storage cp -r ss:///bucket/docs .
    tags: []
    links: []
    usage: supabase storage cp <src> <dst> [flags]
    subcommands: []
    flags:
      - id: cache-control
        name: --cache-control <string>
        description: Custom Cache-Control header for HTTP upload. (default "max-age=3600")
        default_value: max-age=3600
      - id: content-type
        name: --content-type <string>
        description: Custom Content-Type header for HTTP upload. (default "auto-detect")
        default_value: auto-detect
      - id: jobs
        name: -j, --jobs <integer>
        description: Maximum number of parallel jobs. (default 1)
        default_value: '1'
      - id: linked
        name: --linked
        description: Connects to Storage API of the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Connects to Storage API of the local database.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: recursive
        name: -r, --recursive
        description: Recursively copy a directory.
        default_value: 'false'
      - id: experimental
        name: --experimental
        description: enable experimental features
        required: true
        default_value: 'false'
  - id: supabase-storage-ls
    title: supabase storage ls
    summary: List objects by path prefix
    description: List objects by path prefix.
    examples:
      - id: example-1
        name: List objects at a storage path
        code: supabase storage ls ss:///bucket/docs
    tags: []
    links: []
    usage: supabase storage ls [path] [flags]
    subcommands: []
    flags:
      - id: linked
        name: --linked
        description: Connects to Storage API of the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Connects to Storage API of the local database.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: recursive
        name: -r, --recursive
        description: Recursively list a directory.
        default_value: 'false'
      - id: experimental
        name: --experimental
        description: enable experimental features
        required: true
        default_value: 'false'
  - id: supabase-storage-mv
    title: supabase storage mv
    summary: Move objects from src to dst path
    description: Move objects from src to dst path.
    examples:
      - id: example-1
        name: Recursively move a directory within storage
        code: supabase storage mv -r ss:///bucket/docs ss:///bucket/www/docs
    tags: []
    links: []
    usage: supabase storage mv <src> <dst> [flags]
    subcommands: []
    flags:
      - id: linked
        name: --linked
        description: Connects to Storage API of the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Connects to Storage API of the local database.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: recursive
        name: -r, --recursive
        description: Recursively move a directory.
        default_value: 'false'
      - id: experimental
        name: --experimental
        description: enable experimental features
        required: true
        default_value: 'false'
  - id: supabase-storage-rm
    title: supabase storage rm
    summary: Remove objects by file path
    description: Remove objects by file path.
    examples:
      - id: example-1
        name: Recursively remove a directory from storage
        code: supabase storage rm -r ss:///bucket/docs
      - id: example-2
        name: Remove multiple files from storage
        code: supabase storage rm ss:///bucket/docs/example.md ss:///bucket/readme.md
    tags: []
    links: []
    usage: supabase storage rm <file> ... [flags]
    subcommands: []
    flags:
      - id: linked
        name: --linked
        description: Connects to Storage API of the linked project.
        default_value: 'true'
      - id: local
        name: --local
        description: Connects to Storage API of the local database.
        default_value: 'false'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: recursive
        name: -r, --recursive
        description: Recursively remove a directory.
        default_value: 'false'
      - id: experimental
        name: --experimental
        description: enable experimental features
        required: true
        default_value: 'false'
  - id: supabase-telemetry
    title: supabase telemetry
    summary: Manage telemetry
    description: Manage CLI telemetry settings.
    tags:
      - local-dev
    links: []
    subcommands:
      - supabase-telemetry-disable
      - supabase-telemetry-enable
      - supabase-telemetry-status
    flags: []
  - id: supabase-telemetry-disable
    title: supabase telemetry disable
    summary: Disable telemetry
    description: Disable CLI telemetry.
    tags: []
    links: []
    usage: supabase telemetry disable [flags]
    subcommands: []
    flags: []
  - id: supabase-telemetry-enable
    title: supabase telemetry enable
    summary: Enable telemetry
    description: Enable CLI telemetry.
    tags: []
    links: []
    usage: supabase telemetry enable [flags]
    subcommands: []
    flags: []
  - id: supabase-telemetry-status
    title: supabase telemetry status
    summary: Show telemetry status
    description: Show CLI telemetry status.
    tags: []
    links: []
    usage: supabase telemetry status [flags]
    subcommands: []
    flags: []
  - id: supabase-test
    title: supabase test
    summary: Run tests on local Supabase containers
    description: Run tests on local Supabase containers.
    tags:
      - local-dev
    links: []
    subcommands:
      - supabase-test-db
      - supabase-test-new
    flags: []
  - id: supabase-test-db
    title: supabase test db
    summary: Tests local database with pgTAP
    description: |


      Executes pgTAP tests against the local database.

      Requires the local development stack to be started by running `supabase start`.

      Runs `pg_prove` in a container with unit test files volume mounted from `supabase/tests` directory. The test file can be suffixed by either `.sql` or `.pg` extension.

      Since each test is wrapped in its own transaction, it will be individually rolled back regardless of success or failure.
    examples:
      - id: basic-usage
        name: Basic usage
        code: supabase test db
        response: |
          /tmp/supabase/tests/nested/order_test.pg .. ok
          /tmp/supabase/tests/pet_test.sql .......... ok
          All tests successful.
          Files=2, Tests=2,  6 wallclock secs ( 0.03 usr  0.01 sys +  0.05 cusr  0.02 csys =  0.11 CPU)
          Result: PASS
    tags: []
    links: []
    usage: supabase test db [path] ... [flags]
    subcommands: []
    flags:
      - id: db-url
        name: --db-url <string>
        description: Tests the database specified by the connection string (must be percent-encoded).
        default_value: ''
      - id: linked
        name: --linked
        description: Runs pgTAP tests on the linked project.
        default_value: 'false'
      - id: local
        name: --local
        description: Runs pgTAP tests on the local database.
        default_value: 'true'
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
  - id: supabase-test-new
    title: supabase test new
    summary: Create a new test file
    description: Create a new test file.
    tags: []
    links: []
    usage: supabase test new <name> [flags]
    subcommands: []
    flags:
      - id: template
        name: -t, --template <[ pgtap ]>
        description: Template framework to generate.
        default_value: pgtap
        accepted_values:
          - id: pgtap
            name: pgtap
            type: '[ pgtap ]'
  - id: supabase-unlink
    title: supabase unlink
    summary: Unlink a Supabase project
    description: Unlink a Supabase project.
    tags:
      - local-dev
    links: []
    usage: supabase unlink [flags]
    subcommands: []
    flags: []
  - id: supabase-vanity-subdomains
    title: supabase vanity-subdomains
    summary: Manage vanity subdomains
    description: |


      Manage vanity subdomains for Supabase projects.

      Usage of vanity subdomains and custom domains is mutually exclusive.
    tags:
      - management-api
    links: []
    subcommands:
      - supabase-vanity-subdomains-activate
      - supabase-vanity-subdomains-check-availability
      - supabase-vanity-subdomains-delete
      - supabase-vanity-subdomains-get
    flags: []
  - id: supabase-vanity-subdomains-activate
    title: supabase vanity-subdomains activate
    summary: Activate a vanity subdomain
    description: Activate a vanity subdomain for your Supabase project. This reconfigures your Supabase project to respond to requests on your vanity subdomain. After the vanity subdomain is activated, your project's auth services will no longer function on the {project-ref}.{supabase-domain} hostname.
    tags: []
    links: []
    usage: supabase vanity-subdomains activate [flags]
    subcommands: []
    flags:
      - id: desired-subdomain
        name: --desired-subdomain <string>
        description: The desired vanity subdomain to use for your Supabase project.
        required: true
        default_value: ''
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: experimental
        name: --experimental
        description: enable experimental features
        required: true
        default_value: 'false'
  - id: supabase-vanity-subdomains-check-availability
    title: supabase vanity-subdomains check-availability
    summary: Check subdomain availability
    description: Checks if a desired subdomain is available for use.
    tags: []
    links: []
    usage: supabase vanity-subdomains check-availability [flags]
    subcommands: []
    flags:
      - id: desired-subdomain
        name: --desired-subdomain <string>
        description: The desired vanity subdomain to use for your Supabase project.
        required: true
        default_value: ''
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: experimental
        name: --experimental
        description: enable experimental features
        required: true
        default_value: 'false'
  - id: supabase-vanity-subdomains-delete
    title: supabase vanity-subdomains delete
    summary: Delete the vanity subdomain
    description: Deletes the vanity subdomain for a project, and reverts to using the project ref for routing.
    tags: []
    links: []
    usage: supabase vanity-subdomains delete [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: experimental
        name: --experimental
        description: enable experimental features
        required: true
        default_value: 'false'
  - id: supabase-vanity-subdomains-get
    title: supabase vanity-subdomains get
    summary: Get the current vanity subdomain
    description: Get the current vanity subdomain.
    tags: []
    links: []
    usage: supabase vanity-subdomains get [flags]
    subcommands: []
    flags:
      - id: project-ref
        name: --project-ref <string>
        description: Project ref of the Supabase project.
        default_value: ''
      - id: experimental
        name: --experimental
        description: enable experimental features
        required: true
        default_value: 'false'
  - id: supabase-whoami
    title: supabase whoami
    summary: Show the current user
    description: Show information about the currently logged-in user.
    examples:
      - id: example-1
        name: Show the current user
        code: supabase whoami
      - id: example-2
        name: Show the current user as JSON
        code: supabase whoami --output-format json
    tags:
      - management-api
    links: []
    usage: supabase whoami [flags]
    subcommands: []
    flags: []