openref: 0.1

info:
  id: reference/cli
  title: About
  description: |
    The Supabase CLI can be found in our [CLI](https://github.com/supabase/cli) repository.

    - [x] Running Supabase locally
    - [x] Managing database migrations
    - [x] Pushing your local changes to production
    - [ ] Manage your Supabase Account
    - [ ] Manage your Supabase Projects
    - [ ] Generating types directly from your database schema
    - [ ] Generating API and validation schemas from your database

    ## Getting started

    ```bash
    supabase help
    ```

    Follow the [Local Development guide](/docs/guides/local-development) for a quick overview of the CLI functionality.

    ## Installing the CLI

    ### macOS

    Available via [Homebrew](https://brew.sh). To install:

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

    To upgrade:

    ```sh
    brew upgrade supabase
    ```

    ### Windows

    Available via [Scoop](https://scoop.sh). To install:

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

    To upgrade:

    ```powershell
    scoop update supabase
    ```

    ### Linux

    Available via [Homebrew](https://brew.sh) and Linux packages.

    #### via Homebrew

    To install:

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

    To upgrade:

    ```sh
    brew upgrade supabase
    ```

    #### via Linux packages

    Linux packages are provided in [Releases](https://github.com/supabase/cli/releases).
    To install, download the `.apk`/`.deb`/`.rpm` file depending on your package manager 
    and run `sudo apk add --allow-untrusted <...>.apk`/`sudo dpkg -i <...>.deb`/`sudo rpm -i <...>.rpm` respectively.

    ## Support

    Report issues to our [issue tracker](https://github.com/supabase/cli/issues).
    
  definition: spec/combined.json
  libraries:
    - name: 'sh'
      id: 'sh'
      version: '0.0.1'
  docs:
    path: reference/cli/
    sidebar:
      - name: 'About'
        items:
          - index
      - name: 'Command reference'
        items:
          - supabase help
          - supabase init
          - supabase start
          - supabase db branch list
          - supabase db branch create
          - supabase db branch delete
          - supabase db switch
          - supabase db changes
          - supabase db commit
          - supabase db reset
          - supabase db remote set
          - supabase db remote commit
          - supabase db push
          - supabase migration new
      - name: 'Config reference'
        items:
          - Config reference

pages:
  supabase help:
    description: |
      Help provides help for any command in the application.

      Simply type supabase help `[path to command]` for full details.
    examples:
      - name: Usage
        sh: |
          ```sh
          supabase help [command]
          ```

  supabase init:
    description: |
      Initialize a project to use Supabase CLI.
    examples:
      - name: Usage
        sh: |
          ```sh
          supabase init
          ```

  supabase start:
    description: |
      Start the Supabase local development setup.
    examples:
      - name: Usage
        sh: |
          ```sh
          supabase start
          ```

  supabase db branch list:
    description: |
      List branches.
    examples:
      - name: Usage
        sh: |
          ```sh
          supabase db branch list
          ```

  supabase db branch create:
    description: |
      Create a branch.
    examples:
      - name: Usage
        sh: |
          ```sh
          supabase db branch create <branch name>
          ```

  supabase db branch delete:
    description: |
      Delete a branch.
    examples:
      - name: Usage
        sh: |
          ```sh
          supabase db branch delete <branch name>
          ```

  supabase db switch:
    description: |
      Switch branches.
    examples:
      - name: Usage
        sh: |
          ```sh
          supabase db switch <branch name>
          ```

  supabase db changes:
    description: |
      Diffs the local database with current migrations, then print the diff to standard output.
    examples:
      - name: Usage
        sh: |
          ```sh
          supabase db changes
          ```

  supabase db commit:
    description: |
      Diffs the local database with current migrations, writing it as a new migration.
    examples:
      - name: Usage
        sh: |
          ```sh
          supabase db commit <migration name>
          ```

  supabase db reset:
    description: |
      Resets the local database to reflect current migrations. Any changes on the local database that is not committed will be lost.
    examples:
      - name: Usage
        sh: |
          ```sh
          supabase db reset
          ```

  supabase db remote set:
    description: |
      Set the remote database to push migrations to.
    examples:
      - name: Usage
        sh: |
          ```sh
          supabase db remote set <remote database connection url>
          ```
      - name: Connection string format
        sh: |
          ```sh
          supabase db remote set postgresql://postgres:[YOUR-PASSWORD]@db.azeazeiqsdiqswdsqdxc.supabase.co:5432/postgres
          ```

  supabase db remote commit:
    description: |
      Commit changes on the remote database since the last pushed migration.
    examples:
      - name: Usage
        sh: |
          ```sh
          supabase db remote commit
          ```

  supabase db push:
    description: |
      Push new migrations to the remote database.
    examples:
      - name: Usage
        sh: |
          ```sh
          supabase db push
          ```

  supabase migration new:
    description: |
      Create an empty migration.
    examples:
      - name: Usage
        sh: |
          ```sh
          supabase migration new <migration name>
          ```

  Config reference:
    description: |
      The config file resides in `supabase/config.json` after you run `supabase init`.

      ### `projectId` 
      
      `required`

      A string used to distinguish different Supabase projects on the same host. Defaults to the working directory name when running `supabase init`.

      ### `ports.api`
      
      `required`

      Host port used for the API URL. Defaults to `54321`.

      ### `ports.db`
      
      `required`

      Host port used for the DB URL. Defaults to `54322`.

      ### `ports.studio` 
      
      `required`

      Host port used for Supabase Studio. Defaults to `54323`.

      ### `ports.inbucket` 
      
      `optional`

      Host port used for the web interface of Inbucket email testing server. When not specified, emails are automatically confirmed. When specified, emails are not sent to the recipient, but rather monitored and accessible via the web interface.

      ### `dbVersion` 
      
      `required`

      Server version number used for the database. This needs to match the server version number of the remote database you intend to link to with `supabase db remote set`. You can retrieve it by running `SHOW server_version_num`.