Zuvo Docs

Guide

Zuvo CLI

Develop locally, deploy to the Zuvo Platform, and set up CI/CD workflows

The Zuvo CLI enables you to run the entire Zuvo stack locally, on your machine or in a CI environment. With two commands, you can set up and start a new local project:

  1. supabase init to create a new local project
  2. supabase start to launch the Zuvo services

Installing the Zuvo CLI

npm

Install the CLI as a project dev dependency. This adds it to a single project rather than installing a global command:

npm install supabase --save-dev
# or: pnpm add -D supabase / yarn add -D supabase / bun add -D supabase

Pin the version in package.json so your whole team uses the same CLI version. Then run every command through your package runner:

npx supabase --help
# or: pnpm supabase / yarn supabase / bunx supabase
macOS

Install the CLI with Homebrew:

brew install supabase/tap/supabase
Windows

Install the CLI with Scoop:

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

The CLI is available via Homebrew and Linux packages.

Homebrew

brew install supabase/tap/supabase

Linux packages

Linux packages are provided in Releases. To install, download the .apk/.deb/.rpm file depending on your package manager and run one of the following:

  • sudo apk add --allow-untrusted <...>.apk
  • sudo dpkg -i <...>.deb
  • sudo rpm -i <...>.rpm

Beta channel

Pre-release CLI builds ship from the development branch (X.Y.Z-beta.N versions). Use the npm beta dist-tag, or install supabase-beta via Homebrew / Scoop (separate packages from stable).

npm

Install as a dev dependency:

npm install supabase@beta --save-dev

Or run without installing:

npx supabase@beta --help
macOS
brew install supabase/tap/supabase-beta
brew link --overwrite supabase-beta
Windows
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase-beta
Linux

Homebrew

brew install supabase/tap/supabase-beta
brew link --overwrite supabase-beta

Linux packages

Beta builds are attached to GitHub pre-releases. Download the .apk, .deb, or .rpm for your platform and install with the same commands as Linux packages above.

Updating the Zuvo CLI

When a new version is released, you can update the CLI using the same channels.

npm

Update the CLI with npm:

npm update supabase --save-dev

Update to the latest beta release or switch a stable install to the beta channel with:

npm install supabase@beta --save-dev
macOS
brew upgrade supabase

Beta channel:

brew upgrade supabase-beta
Windows
scoop update supabase

Beta channel:

scoop update supabase-beta
Linux

Homebrew

brew upgrade supabase

Beta channel:

brew upgrade supabase-beta

Linux packages

  1. Download the latest package from the Zuvo CLI releases page
  2. Install the package using the same commands as the initial installation:
    • sudo apk add --allow-untrusted <...>.apk
    • sudo dpkg -i <...>.deb
    • sudo rpm -i <...>.rpm

If you have any Zuvo containers running locally, stop them and delete their data volumes before proceeding with the upgrade. This ensures that Zuvo managed services can apply new migrations on a clean state of the local database.

Running a local Zuvo project

The most common thing you'll do with the CLI is run the full Zuvo stack (Postgres, Auth, Storage, and the rest) on your own machine. That stack runs in Docker containers, so you need a container runtime installed first. Follow the official guide to install and configure Docker Desktop on your machine.

Alternately, you can use a different container tool that offers Docker compatible APIs.

With a container runtime running, go to the folder where you want to create your project and initialize it:

supabase init

This creates a new supabase folder. It's safe to commit this folder to version control.

Now, from the same folder, start the Zuvo stack:

supabase start

This takes time on your first run because the CLI needs to download the Docker images to your local machine. The CLI includes the entire Zuvo stack, and a few additional images useful for local development (like a local SMTP server and a database diff tool).

Access your project's services

Once all the Zuvo services are running, you'll see output containing your local Zuvo credentials. It should look like the below, with urls and keys that you use in your local project:

Started supabase local development setup.

╭──────────────────────────────────────╮
│ 🔧 Development Tools                 │
├─────────┬────────────────────────────┤
│ Studio  │ http://127.0.0.1:54323     │
│ Mailpit │ http://127.0.0.1:54324     │
│ MCP     │ http://127.0.0.1:54321/mcp │
╰─────────┴────────────────────────────╯

╭──────────────────────────────────────────────────────╮
│ 🌐 APIs                                              │
├────────────────┬─────────────────────────────────────┤
│ Project URL    │ http://127.0.0.1:54321              │
│ REST           │ http://127.0.0.1:54321/rest/v1      │
│ GraphQL        │ http://127.0.0.1:54321/graphql/v1   │
│ Edge Functions │ http://127.0.0.1:54321/functions/v1 │
╰────────────────┴─────────────────────────────────────╯

╭───────────────────────────────────────────────────────────────╮
│ ⛁ Database                                                    │
├─────┬─────────────────────────────────────────────────────────┤
│ URL │ postgresql://postgres:postgres@127.0.0.1:54322/postgres │
╰─────┴─────────────────────────────────────────────────────────╯

╭──────────────────────────────────────────────────────────────╮
│ 🔑 Authentication Keys                                       │
├─────────────┬────────────────────────────────────────────────┤
│ Publishable │ sb_publishable_...                             │
│ Secret      │ sb_secret_...                                  │
╰─────────────┴────────────────────────────────────────────────╯
Studio
# Default URL:
http://localhost:54323

The local development environment includes Zuvo Studio, a graphical interface for working with your database.

Local Studio

Postgres
# Default URL:
postgresql://postgres:postgres@localhost:54322/postgres

The local Postgres instance can be accessed through psql or any other Postgres client, such as pgAdmin. For example:

psql 'postgresql://postgres:postgres@localhost:54322/postgres'
API Gateway
# Default URL:
http://localhost:54321

If you are accessing these services without the client libraries, you may need to pass the client keys as an Authorization header. Learn more about JWT headers.

curl 'http://localhost:54321/rest/v1/' \
    -H "apikey: sb_publishable_..."

http://localhost:54321/rest/v1/           # REST (PostgREST)
http://localhost:54321/realtime/v1/       # Realtime
http://localhost:54321/storage/v1/        # Storage
http://localhost:54321/auth/v1/           # Auth (GoTrue)
Analytics

Local logs rely on the Zuvo Analytics Server which accesses the docker logging driver by either volume mounting /var/run/docker.sock domain socket on Linux and macOS, or exposing tcp://localhost:2375 daemon socket on Windows. These settings must be configured manually after installing the Zuvo CLI.

All logs are stored in the local database under the _analytics schema.

Stopping local services

When you are finished working on your Zuvo project, you can stop the stack (without resetting your local database):

supabase stop

Telemetry

The Zuvo CLI collects telemetry data about general usage. Participating in this program is optional, and you can opt out at any time.

How to opt out

You can disable telemetry by running:

supabase telemetry disable

You can check the current status and re-enable with:

supabase telemetry status
supabase telemetry enable

You can also opt out using the SUPABASE_TELEMETRY_DISABLED=1 environment variable. The broader DO_NOT_TRACK=1 convention is also respected.

Learn more