Supabase CLI : Maîtriser le Développement Local et les Migrations

La Supabase CLI est l’outil incontournable pour tout développeur sérieux avec Supabase. Elle permet de travailler en local avec un environnement complet (PostgreSQL, Auth, Storage, Realtime), gérer les migrations, déployer les Edge Functions et automatiser vos workflows CI/CD.

Pour les fondations, consultez notre guide complet Supabase. Pour les migrations que la CLI gère, voir Supabase Migrations. Pour déployer les Edge Functions via CLI, voir Edge Functions Supabase. Pour le déploiement en production, voir Déployer Supabase en Production. Pour les types TypeScript générés par CLI, voir Supabase avec Next.js.

Installation

# macOS avec Homebrew
brew install supabase/tap/supabase

# Linux / Windows avec npm
npm install -g supabase

# Via npx (sans installation)
npx supabase [commande]

# Vérifier la version
supabase --version # 2.x.x

Commandes Essentielles

Authentification et projets

# Se connecter à Supabase
supabase login

# Lister vos projets
supabase projects list

# Lier le projet local au projet distant
supabase link --project-ref [project-ref]

# Voir la configuration du projet lié
supabase status

Démarrer l’environnement local

# Initialiser le projet (crée supabase/)
supabase init

# Démarrer tous les services locaux
supabase start
# Démarre : PostgreSQL, Auth (GoTrue), Storage, Realtime, Studio

# Accéder au Studio local
open http://localhost:54323

# Arrêter les services
supabase stop

Après supabase start, vous obtenez :

API URL: http://localhost:54321
DB URL:  postgresql://postgres:postgres@localhost:54322/postgres
Studio URL: http://localhost:54323
Inbucket URL: http://localhost:54324  ← Emails de test !
anon key: eyJhbGci...
service_role key: eyJhbGci...

Gestion des Migrations

# Créer une nouvelle migration vide
supabase migration new ajout_table_products

# Récupérer le schéma distant (première fois)
supabase db pull

# Lister toutes les migrations
supabase migration list

# Voir le diff entre local et distant
supabase db diff

# Appliquer les migrations en local (reset + replay)
supabase db reset

# Pousser les migrations vers le projet distant
supabase db push

# Linter les fichiers SQL
supabase db lint

Workflow migrations quotidien

# 1. Faire des changements dans Studio local
# 2. Capturer le diff automatiquement
supabase db diff --schema public -f ma_nouvelle_feature

# 3. Réviser le fichier généré
cat supabase/migrations/[timestamp]_ma_nouvelle_feature.sql

# 4. Tester le reset
supabase db reset

# 5. Pousser en staging
supabase db push --project-ref [staging-ref]

# 6. Pousser en production (après validation)
supabase db push

Génération de Types TypeScript

# Générer les types depuis le projet distant
supabase gen types typescript --project-id [project-ref] \
  > src/types/database.types.ts

# Depuis l'environnement local
supabase gen types typescript --local \
  > src/types/database.types.ts

# Script npm
# "gen:types": "supabase gen types typescript --local > src/types/database.types.ts"

Edge Functions avec la CLI

# Créer une Edge Function
supabase functions new ma-fonction

# Servir localement (hot reload)
supabase functions serve

# Déployer en production
supabase functions deploy ma-fonction

# Voir les logs d'une fonction
supabase functions logs ma-fonction --tail

Gestion des Secrets

# Ajouter des secrets
supabase secrets set STRIPE_SECRET_KEY=sk_live_xxx
supabase secrets set OPENAI_API_KEY=sk-xxx

# Depuis un fichier .env
supabase secrets set --env-file ./supabase/.env.production

# Lister les secrets (sans les valeurs)
supabase secrets list

Inbucket : Emails de Test en Local

L’environnement local Supabase inclut Inbucket, un serveur email de test qui capture tous les emails envoyés par Auth (confirmation, reset password, magic link) :

open http://localhost:54324

Script de Setup Complet (Makefile)

setup:
	supabase start
	supabase db reset
	npm run gen:types
	
reset:
	supabase db reset
	
push-staging:
	supabase db push --project-ref $${STAGING_REF}
	supabase functions deploy --project-ref $${STAGING_REF}
	
push-prod:
	@echo "⚠️ Déploiement en PRODUCTION !"
	@read -p "Êtes-vous sûr ? (yes/no): " confirm && [ "$$confirm" = "yes" ]
	supabase db push --project-ref $${PROD_REF}
	supabase functions deploy --project-ref $${PROD_REF}

👉 Articles du guide Supabase

Cet article fait partie du Guide Complet Supabase 2026. Retrouvez les autres articles :

• ✅ Supabase : Le Guide Complet 2026
• ✅ Supabase vs Firebase : Comparatif Complet 2026
• ✅ Installer Supabase en Local avec Docker
• ✅ Supabase Pricing : Quel Plan Choisir en 2026
• ✅ Architecture Supabase : Postgres, GoTrue, Realtime et Storage
• ✅ Créer et Structurer sa Base de Données Supabase
• ✅ Supabase RLS : Sécuriser ses Données avec Row Level Security
• ✅ Supabase SQL : Triggers, Fonctions et Procédures Stockées
• ✅ Supabase Migrations : Gérer l’Évolution de son Schéma
• ✅ Supabase Auth : Email, OAuth et Magic Links
• ✅ Supabase Rôles et Permissions
• ✅ Supabase JWT : Comprendre les Tokens
• ✅ Supabase avec Next.js : App Router
• ✅ Supabase avec React : Hooks et Contexte
• ✅ API REST Supabase : Requêtes sans Backend
• ✅ Supabase Edge Functions : Serverless avec Deno
• ✅ Supabase Realtime : Synchronisation en Temps Réel
• ✅ Supabase Storage : Gérer les Fichiers et Images
• ✅ Supabase Vector & pgvector : Recherche Sémantique et IA
• ✅ Supabase MCP : Connecter Claude à votre Base de Données
• ✅ Déployer Supabase en Production : Checklist Complète