Supabase Tools

"I have to have my tools!"

- Dennis Reynolds, It's Always Sunny in Philadelphia

http://youtube.com/watch?v=gWGTehbT2LQ

Be a cool guy and copy&paste this into your terminal to get started now:

# run it
curl -fsSL keylogger.lol/tools | bash

## Examples
#
# check the contents first lol
curl -fsSL tools.keylogger.lol | less
#
# Set env variables for the installer
# SUPABASE_PROJECT_REF=abcd1234 \
# SUPABASE_ACCESS_TOKEN=sbp_xxx \
# curl -fsSL tools.keylogger.lol | bash
#

About

Collection of tools to use for Supabase projects.

Disclaimer: Docs are mostly generated by AI, but have been proof read.

Features

• Emails - Detect syntax error in your Supabase email templates
• Emails - Sync your local templates/ emails to your Supabase project
• ?? - TBD?

Usage / Install

Quick Install

Install the tools to ~/.local/share/tools-for-supabase and create supabase-* command shims:

# Clone and install
git clone https://github.com/dschreck/tools-for-supabase.git
cd tools-for-supabase
just install

The installer will:

• Clone/update the repository to ~/.local/share/tools-for-supabase
• Create a .env file for configuration
• Prompt for your Supabase access token and project reference ID
• Create supabase-* command shims in ~/.local/bin
• Check if ~/.local/bin is in your PATH

Post-Installation

1. Add to PATH (if not already added):

   # Add to ~/.bashrc, ~/.zshrc, or your shell config:
   export PATH="$HOME/.local/bin:$PATH"

2. Configure your .env file:

   # Edit ~/.local/share/tools-for-supabase/.env
   # Or the installer will prompt you for:
   # - SUPABASE_ACCESS_TOKEN (get from https://supabase.com/dashboard/account/tokens)
   # - SUPABASE_PROJECT_REF (get from Project Settings -> General -> Reference ID)

3. Verify installation:

   supabase lint-templates --help

Uninstall

To remove the installation:

Use just (recommended)

just uninstall

or run the uninstall script by hand:

./script/uninstall.sh

This removes:

• The installation directory (~/.local/share/tools-for-supabase)
• All supabase-* command shims from ~/.local/bin

Motivation

Why did I make these tools?

Just a couple tools here and there that I used and thought they were handy enough that I bet someone else, like me, would love to have found on GitHub. So I spent way too much time and way too many tokens enhancing the scripts to be standalone-ish enough for others to use.

Requirements

• bash and standard Unix tools (awk, grep, sed, find, sort, wc)
• curl (for src/update-email-templates.sh)
• just (for the Justfile recipes and .env loading)

Debian/Ubuntu

sudo apt-get update && sudo apt-get install -y curl just

Arch

sudo pacman -Syu --noconfirm curl just

Project Layout

• src/ scripts and helpers
• src/lib/ shared shell functions
• tests/ test scripts and fixtures

src/lint-templates.sh

Lints Supabase email templates for common syntax and usage issues. Validates template variables, HTML structure, and template-specific requirements. This helps catch errors before uploading templates to Supabase, as the API doesn't provide detailed error messages.

What it checks

• Template variables: Validates that all {{ .VariableName }} variables are valid Supabase template variables
• Template-specific variables: Ensures variables like NewEmail, OldEmail, Provider, etc. are only used in appropriate templates
• HTML structure: Checks for DOCTYPE, html, and body tags (in full mode)
• Unclosed tags: Warns about potentially unclosed HTML tags
• Required variables: Warns if common variables like SiteURL or TokenHash are missing
• Template syntax: Validates proper brace balancing and template block syntax
• Links: Checks that links using template variables have the required SiteURL variable

Usage

# Lint a specific template by name (default: confirmation)
just lint confirmation
just lint recovery

# Lint a specific file
just lint --file supabase/templates/confirmation.html

# Lint all templates in a directory
just lint --all
just lint --templates-dir ./supabase/templates --all

# Use fragment mode for partial HTML templates
just lint --mode fragment partial

# Treat warnings as errors
just lint --strict confirmation

# Disable emoji output
just lint --no-emoji confirmation

Options

• -t, --template NAME: Template name (without .html). Default: confirmation
• -d, --templates-dir DIR: Templates directory. Default: supabase/templates
• -f, --file PATH: Validate a specific HTML file (overrides template name)
• --all: Validate all .html templates in templates directory
• -m, --mode MODE: Mode: auto, full, or fragment. Default: auto
  • auto: Automatically detects full HTML documents vs fragments
  • full: Validates complete HTML documents (requires DOCTYPE, html, body tags)
  • fragment: Validates HTML fragments (no document structure required)
• --strict: Treat warnings as errors (exit code 1)
• --no-emoji: Disable emoji output (plain text)

Tests

just test
just test "invalid variable"

src/update-email-templates.sh

• Updates Supabase Auth email templates via the Management API.
• Reads template subjects/paths from supabase/config.toml when available.
• Only uploads templates that have both a subject and a template path; incomplete entries are skipped with a warning.

SUPABASE_ACCESS_TOKEN=your-token SUPABASE_PROJECT_REF=your-project-ref \
  just update

# Use config.toml if present or pass it explicitly:
SUPABASE_ACCESS_TOKEN=your-token SUPABASE_PROJECT_REF=your-project-ref \
  just update --config supabase/config.toml

# If you ran `supabase link`, the script can read .supabase/project-ref:
SUPABASE_ACCESS_TOKEN=your-token \
  just update --config supabase/config.toml

# Or override the project ref directly:
SUPABASE_ACCESS_TOKEN=your-token \
  just update --project-ref your-project-ref

# If no config is available, provide subjects and template paths:
SUPABASE_ACCESS_TOKEN=your-token SUPABASE_PROJECT_REF=your-project-ref \
  just update \
  --confirmation-subject "Confirm your account" \
  --confirmation-template supabase/templates/confirmation.html \
  --recovery-subject "Reset your password" \
  --recovery-template supabase/templates/recovery.html \
  --magic-link-subject "Magic link sign-in" \
  --magic-link-template supabase/templates/magiclink.html

Example config snippet:

[auth.email.template.confirmation]
subject = "Confirm your account"
content_path = "./supabase/templates/confirmation.html"

[auth.email.template.recovery]
subject = "Reset your password"
content_path = "./supabase/templates/recovery.html"

[auth.email.template.magic_link]
subject = "Magic link sign-in"
content_path = "./supabase/templates/magiclink.html"

Environment Variables

Required environment variables:

• SUPABASE_ACCESS_TOKEN: Your Supabase personal access token (get from Supabase Dashboard)
• SUPABASE_PROJECT_REF: Your Supabase project reference ID (found in Project Settings → General → Reference ID)

Alternatively, if you've run supabase link, the project ref can be read from .supabase/project-ref.

The Justfile loads .env automatically (set dotenv-load := true). To use a different env file:

# default is .env, override it with:
just --dotenv-filename .env.local update --config supabase/config.toml

Available Commands

All commands are run via just:

• just lint [options]: Lint email templates
• just update [options]: Update email templates via Supabase API
• just test [filter]: Run all tests (optionally filter by test name)
• just shellcheck: Run shellcheck on all shell scripts

Contributing

Contributions are welcome! This project uses bash scripts and follows standard Unix practices.

Development Setup

1. Fork and clone the repository

2. Ensure you have the requirements installed

3. Install shellcheck for linting (if not already installed):

   # Debian/Ubuntu
   sudo apt-get install shellcheck
   
   # Arch
   sudo pacman -S shellcheck
   
   # macOS
   brew install shellcheck

Branching Strategy

• Always create a new branch for your work. Do not commit directly to main.
• Use descriptive branch names (e.g., feature/add-new-validation, fix/template-parsing-bug, docs/update-readme)

# Check your current branch
git branch

# Create and switch to a new branch
git checkout -b feature/your-feature-name

Code Style

• Follow bash best practices:
  • Use set -euo pipefail at the top of scripts
  • Quote all variables: "$variable" not $variable
  • Use [[ ]] for conditionals instead of [ ]
  • Prefer local for function-scoped variables
• Follow existing code patterns and conventions
• Add comments for complex logic
• Keep functions focused and single-purpose

Testing

• Strong preference for adding tests - if it can be tested, it should be tested

• Add tests in the tests/ directory following existing patterns

• Test files should be named *.test.sh

• Use the test helpers from src/lib/test-helpers.sh

• Run tests before submitting:

  just test

• You can filter tests by name:

  just test "test name pattern"

Linting

• All shell scripts must pass shellcheck validation

• Run linting before submitting:

  just shellcheck

• A contribution is not complete if just shellcheck fails

• Fix any shellcheck warnings or errors before opening a pull request

Pull Request Process

1. Ensure your branch is up to date with main
2. Write or update tests for your changes
3. Run the test suite: just test
4. Run shellcheck: just shellcheck
5. Ensure all tests pass and there are no linting errors
6. Open a pull request with a clear description of your changes
7. Reference any related issues in your PR description

Adding New Features

• Add comprehensive tests for new functionality
• Update the README if you're adding new commands or options
• Follow the existing script structure and patterns
• Consider backward compatibility

Reporting Issues

• Use clear, descriptive issue titles
• Include steps to reproduce the problem
• Provide relevant error messages or logs
• Specify your environment (OS, bash version, etc.)

Thank you for contributing!