Supabase KeepAlive CLI

A command-line tool to initialize, link, and monitor your Supabase project uptime using automated keep-alive health checks on the KeepAlive dashboard.

🚀 Getting Started

npx supabase-keepalive init

What happens, step by step:

1. Authentication — opens your browser to sign in to your KeepAlive dashboard account (only asked once; cached locally afterwards).
2. Connect Supabase Account (optional but recommended) — you paste a Supabase access token (sbp_..., generated at supabase.com/dashboard/account/tokens) and every Supabase project you own gets imported automatically. If you're already connected, this step silently re-syncs instead of asking again.
3. Project Discovery — scans the current folder's .env files for a Supabase URL. If this folder isn't itself a Supabase project (e.g. you only wanted step 2), the command finishes here — that's not an error.
4. Scheduler Detection — checks for a .github folder or wrangler.toml/.jsonc/.json to recommend either GitHub Actions or Cloudflare Workers.
5. Linking — registers this folder's project with your dashboard.
6. Configure Scheduler — sets up automated checks for this project:
   • GitHub Actions: writes .github/workflows/keepalive.yml directly into this repo. You still need to commit/push it and add one GitHub repo secret (the CLI prints the exact name, value, and — when it can detect your GitHub remote — a direct link to the secrets page).
   • Cloudflare Workers: prompts you to paste a Cloudflare API token + Account ID (once), then deploys a small Worker with a Cron Trigger via Cloudflare's API — no files written to your repo, no manual dashboard clicking on Cloudflare's side.

Either way, once step 6 finishes, that project gets pinged automatically every 30 minutes, forever, with no further action from you.

🔑 About the KEEPALIVE_API_KEY secret

If you set up GitHub Actions, the generated workflow authenticates using a secret named KEEPALIVE_API_KEY — this is not your Supabase or GitHub password, it's a Personal Access Token scoped to this dashboard, used only so an automated GitHub Action can trigger a health check without you being logged in. The CLI prints the value once; add it under your repo's Settings → Secrets and variables → Actions → New repository secret. If it ever leaks, revoke it from your dashboard's Settings page and generate a new one — nothing else needs to change.

⚙️ Commands

1. init

Runs the full flow described above.

npx supabase-keepalive init

2. status

Query the live status, uptime percentages, and last health-check logs for all your registered projects.

npx supabase-keepalive status

3. link

Manually link a Supabase project URL without running full auto-discovery (no scheduler setup).

npx supabase-keepalive link --url https://your-project.supabase.co

🔒 Security

Supabase KeepAlive uses cryptographically secure Personal Access Tokens (API Keys) stored locally in ~/.supabase-keepalive/config.json. All API requests are verified using SHA-256 key hashing on our server to isolate data securely between tenants. Cloudflare/Supabase tokens you connect are encrypted before storage and are only ever used server-side for the specific API calls described above.