Supabase CLI는 Supabase 스택 전체를 로컬 환경 또는 CI/CD 환경에서 실행할 수 있도록 설계된 command-line interface 도구입니다. 이 도구의 핵심 방법론은 Docker 컨테이너를 활용하여 Supabase의 다양한 서비스를 로컬에서 에뮬레이트하는 것입니다.

로컬 개발을 시작하기 위해 사용자는 두 가지 주요 명령어를 사용합니다:

1. supabase init: 현재 디렉터리에 supabase 폴더를 생성하여 새로운 로컬 프로젝트를 초기화합니다. 이 폴더는 버전 관리 시스템에 커밋해도 안전합니다.
2. supabase start: 필요한 Docker 이미지를 다운로드하고 Supabase 서비스 스택을 시작합니다. 여기에는 Postgres 데이터베이스, API Gateway, Supabase Studio, 분석 도구뿐만 아니라 로컬 SMTP 서버(Mailpit) 및 데이터베이스 diff 도구와 같은 개발에 유용한 추가 이미지들이 포함됩니다.

Supabase CLI는 npx 또는 bunx를 접두사로 사용하여 실행하거나, npm install supabase --save-dev 명령어로 개발 종속성으로 설치할 수 있습니다. npx 또는 npm을 통해 실행하는 경우 Node.js 20 버전 이상이 필요합니다.

CLI를 업데이트할 때는, 새로운 마이그레이션을 로컬 데이터베이스에 깔끔하게 적용하기 위해, 기존에 실행 중인 모든 Supabase 컨테이너를 중지하고 데이터 볼륨을 삭제하는 것이 권장됩니다. 이 과정에서 로컬 스키마 및 데이터 변경 사항을 백업하기 위해 supabase db diff -f my_schema와 $supabase db dump --local --data-only > supabase/seed.sql$ 명령어를 사용할 수 있으며, 이후 supabase stop --no-backup 명령어로 컨테이너를 중지하고 데이터를 삭제합니다.

로컬 Supabase 스택은 Docker Desktop 또는 Rancher Desktop, Podman, OrbStack, colima와 같이 Docker 호환 API를 제공하는 다른 컨테이너 도구를 필요로 합니다. supabase start 명령이 성공적으로 완료되면, 로컬 개발에 필요한 API URL, DB URL, Studio URL, Mailpit URL, anon key, service_role key와 같은 credentials이 터미널에 출력됩니다. 특히 http://localhost:54323에서 접근 가능한 Supabase Studio는 로컬 데이터베이스를 시각적으로 관리할 수 있는 GUI를 제공합니다. 작업이 끝나면 supabase stop 명령어로 로컬 데이터베이스를 재설정하지 않고 스택을 중지할 수 있습니다.