supabase-environments_skill

Overview

This skill is an internal development guide for building the Supabase CLI environments subsystem. It documents the three-environment model, variable resolution, pull/push workflows, secret handling, branch overrides, and local file conventions. Use it when implementing env CLI commands or the environment variable infrastructure.

How this skill works

The guide prescribes a flat, three-environment model (development, preview, production) with strict protections for defaults and no inheritance between environments. It defines pull and push semantics: pull is a full file replacement with server-side branch-override resolution; push displays a diff and performs a bulk upsert of base variable values. It also specifies secret handling (write-only secrets), local file layout (.env and .env.local), canonical variable naming, and branch-specific per-variable overrides.

When to use it

• Implementing env CLI commands (pull, push, list, set, unset, create, delete, seed)
• Designing variable resolution logic for local and deployed contexts
• Handling write-only secret variables and interactive push prompts
• Implementing branch-to-environment mapping and branch-specific overrides
• Designing pull/push workflows with diff displays and confirmation

Best practices

• Protect the three default environments: do not allow rename or delete of development/preview/production
• Treat environments as flat independent sets — avoid inheritance or fallback chains
• Make secrets write-only: exclude them from pull/list and require explicit interactive confirmation when pushing
• Push operations must show a clear diff and use bulk upsert API calls rather than one-at-a-time updates
• Keep only two local files (.env and .env.local), follow OS/.env.local/.env resolution order

Example use cases

• Implementing push: compute diff, display additions/changes/removals, request confirmation, send a single bulk upsert request
• Implementing pull: fetch server-resolved variables (including branch overrides), replace local .env file atomically
• Creating branch-specific overrides: use env set --branch to set per-variable overrides without affecting base values
• Seeding a new environment: run interactive keep/edit/skip flow to populate variables consistently
• Linking a project: prompt to push local variables to remote when transitioning from local-first to remote-first mode