Supabase Session

A small Bash CLI for switching between multiple Supabase CLI login tokens using human-readable aliases.

Under the hood it runs:

supabase login --token <token>

The token itself is hidden during normal usage. You select sessions by alias through an interactive selector inspired by supabase link.

Install

Make the script executable:

chmod +x ./supabase-session

Run it directly:

./supabase-session help

Optional: move it somewhere on your PATH:

mkdir -p ~/.local/bin
cp ./supabase-session ~/.local/bin/supabase-session

Then make sure ~/.local/bin is in your shell path.

Requirements

• Bash
• Supabase CLI installed and available as supabase
• One of these token storage backends:
  • macOS Keychain via security, preferred on macOS
  • pass
  • plaintext fallback, only after explicit confirmation

Setup

Generate a Supabase access token

Before adding a session, create a Supabase access token from the Supabase dashboard:

1. Open the Supabase dashboard in your browser.
2. Go to Account preferences.
3. Open Access Tokens.
4. Click Generate new token.
5. Give the token a descriptive name, copy it once, and keep it private.

Paste that token only into the hidden Access token: prompt from supabase-session add. Do not paste access tokens into chat, issues, commits, or logs.

Add your first session

Add your first Supabase session:

supabase-session add

You will be prompted for:

Alias: Client A Production
Access token: sbp_...

The alias is what you will see in the picker. The token is stored in the selected secret backend.

Usage

Switch sessions

supabase-session use

Interactive controls:

↑/k up • ↓/j down • / filter • q quit • Enter select

After selection, the script runs:

supabase login --token <stored-token>

List aliases

supabase-session list

Example:

1. Client A Production
2. Personal Sandbox
3. Agency Shared Dev

List with masked tokens

supabase-session list --verbose

Example:

1. Client A Production    token: sbp_****abcd

Rename an alias

supabase-session rename

Remove a session

supabase-session remove

or:

supabase-session rm

Show current tracked session

supabase-session current

This shows the last alias selected through supabase-session use.

Storage

Metadata is stored at:

~/.config/supabase-session/config.tsv

This file stores non-secret metadata only:

id<TAB>alias<TAB>created_at<TAB>last_used_at<TAB>backend

Tokens are stored separately in a secret backend.

Backend detection order:

1. SUPABASE_SESSION_SECRET_BACKEND, if set
2. macOS Keychain on macOS
3. pass, if installed
4. plaintext fallback with confirmation

Environment variables

Force a backend:

export SUPABASE_SESSION_SECRET_BACKEND=keychain

Supported values:

keychain
pass
plain

Allow plaintext fallback without an interactive confirmation:

export SUPABASE_SESSION_ALLOW_PLAINTEXT=1

Use this only in trusted local/dev environments.

Tips

• Use descriptive aliases like Client A Production, Personal Sandbox, or Agency Shared Dev.
• Prefer one token per account/context so switching is obvious.
• Use supabase-session list --verbose if you need to distinguish similar aliases without exposing the full token.
• If the selector has many entries, press / and type part of an alias to filter.
• Keep your Supabase access tokens scoped and rotated according to your team’s security policy.
• Do not commit ~/.config/supabase-session or plaintext token storage directories.

AI assistant integration

This repo includes instruction files and a packaged skill so common AI coding tools know how to use supabase-session safely without exposing tokens:

• AGENTS.md for OpenAI Codex-style agents
• CLAUDE.md for Claude Code
• GEMINI.md for Gemini CLI
• QWEN.md for Qwen Code-style agents
• CONVENTIONS.md plus .aider.conf.yml for aider
• .github/copilot-instructions.md for GitHub Copilot
• .cursor/rules/supabase-session.mdc for Cursor
• .windsurf/rules/supabase-session.md for Windsurf
• skills/supabase-session-cli/SKILL.md as the source skill
• dist/supabase-session-cli.skill as the packaged installable skill

The shared guidance is: list aliases with supabase-session list, switch with supabase-session use, and never paste Supabase access tokens into AI chat.

Troubleshooting

supabase CLI not found in PATH

Install the Supabase CLI or update your shell PATH so supabase is available.

Check with:

supabase --version

Plaintext storage warning

If neither Keychain nor pass is available, the script asks before storing tokens in plaintext.

For better security, install/configure pass or use macOS Keychain.

Reset all local sessions

Remove the config directory:

rm -rf ~/.config/supabase-session

If you used plaintext fallback, also remove:

rm -rf ~/.local/share/supabase-session

If you used Keychain or pass, remove stored secrets through those tools as needed.