supabase · Supabase
Supabase CLI for AI Agents
Manage local Supabase development, migrations, functions, and linked projects with explicit environment risk.
Install for an Agent
Choose an official installation path that matches the runtime. Pin a version for team or CI use, then record the version before the first task.
Structured Output for Reliable Automation
Prefer a machine-readable format. Treat stdout as the result channel and stderr as diagnostics so the agent can parse failures separately.
R0–R3 Command Risk Guide
Risk is assigned per command. R0 is local or remote read-only, R1 is reversible local write, R2 changes remote state, and R3 can be irreversible or production-impacting.
Read-only does not mean public
R0 only means the command does not change local or remote state. A read-only command may still return secrets, identity data, configuration, or production data. Expose only the minimum needed for the task, and never place it in logs, prompts, or commits.
How the Agent Readiness Score Is Built
Readiness describes how reliably an agent can operate the tool. It does not make every command safe and it does not replace an independent execution test.
Documentation indicates an agent-readiness score of 84/100. No local execution test has been recorded.
Generate a Skill or Agent Policy
Choose an agent and safety mode to generate a copyable artifact with installation, allowed commands, approval boundaries, and the evidence limitation.
---
name: supabase-cli-agent-workflow
description: Use Supabase CLI for local Supabase stack, database migrations, Edge Functions with explicit command risk and evidence boundaries.
---
# Supabase CLI agent workflow
Use this skill when the task needs local Supabase stack, database migrations, Edge Functions, type generation.
## Evidence boundary
- Registry confidence: `docs-verified`
- Documentation checked: `2026-07-10`
- Locally tested version: `not tested`
- Do not describe this CLI as locally verified until its commands have actually been executed in an isolated environment.
## Executed smoke checks
- No local execution record is available.
## Installation
- npm development dependency (macos, linux, windows): `npm install --save-dev supabase`
## Authentication
- Methods: access token, database password, local development
- Secret environment variables: `SUPABASE_ACCESS_TOKEN`, `SUPABASE_DB_PASSWORD`
- Minimum permissions: Use a token limited to the intended organization and verify the linked project before remote commands.
- Credential storage: For headless runs, inject SUPABASE_ACCESS_TOKEN, SUPABASE_DB_PASSWORD from the CI or platform secret manager at process start. For local interactive use, prefer the CLI or operating-system credential store when the official client supports one. Never save values in repository files.
- Never print, persist, or commit credential values.
## Allowed commands (read-only)
- `npx supabase status --output json` — R0: Reads service URLs and local development status.
## Commands requiring explicit approval (read-only)
- None recorded.
## Forbidden commands (read-only)
- R1 `npx supabase db diff --file migration_name` — Writes a local migration draft for review.
- R2 `npx supabase db push` — Changes the linked remote database schema.
- R3 `npx supabase db reset` — Can erase data when used against the wrong environment.
## Execution rules
1. Mode boundary: R0 exact commands may be used; R1, R2, and R3 commands are forbidden.
2. Confirm the selected account, project, context, database, namespace, or environment before any command.
3. Prefer structured output using `--output json`.
4. Capture the exact command, exit code, stdout, and stderr separately.
5. A generated prefix policy must prompt unless that exact prefix is explicitly marked suffix-safe; do not infer safety from the executable name.
6. Never broaden credentials or disable safety controls to make a command succeed.
## Official sources
- [Supabase CLI documentation](https://supabase.com/docs/guides/cli)
- [Supabase CLI documentation source repository](https://github.com/supabase/cli)
Verification History and Official Evidence
CLI Finder records documentation review separately from real execution. Installation, help, exit codes, and output cannot be called Verified until they were run.