name: supabase-cli-linked-query

description: Run SQL queries against Supabase Cloud using CLI --linked flag. Config saves to CWD, not a fixed path.

Supabase CLI — linked project queries

Use when: you need to run SQL against a Supabase Cloud project using the CLI (not local).

Key discovery

supabase db query --linked does NOT use --project-ref flag. Instead it reads the linked project from a local config file.

The config is saved to ./.supabase/config.toml in the current working directory at the time you run supabase link. It is NOT saved to /tmp/supabase/.

This means:

• - If you run supabase link from /tmp, subsequent supabase db query --linked commands must ALSO be run from /tmp (or any dir that has a .supabase/config.toml pointing to the right project).
• - If you cd to a different directory, the link is lost.

Setup + Query pattern

`bash

1. Link the project (choose a working dir and stay in it)

cd /tmp

SUPABASE_ACCESS_TOKEN="sbp_..." supabase link --project-ref --password ""

2. Run queries from the SAME directory

cd /tmp # must be same as above

SUPABASE_ACCESS_TOKEN="sbp_..." supabase db query --linked "SELECT * FROM profiles LIMIT 5;"

3. For project-ref-less commands, you can also set env var

SUPABASE_ACCESS_TOKEN="sbp_..." supabase db query --linked "SELECT 1;"

`

Common errors

• - failed to connect to postgres: dial tcp 127.0.0.1:54322 → wrong directory. cd to where you ran supabase link.
• - No suitable key or wrong key type with anon key on REST API → use service role key for direct DB queries, or use CLI with --linked.
• - column "email" does not exist on profiles → profiles table in this project has no email column. Query auth.users instead: SELECT id, email FROM auth.users WHERE email = 'user@example.com';

Finding existing links

`bash

find /tmp -name "config.toml" -path "/.supabase/"

Also common: /var/www//.supabase/config.toml

`

Note on schema discovery

When unsure of column names, discover first:

`sql

SELECT column_name, data_type FROM information_schema.columns

WHERE table_name = 'my_table' ORDER BY ordinal_position;

`

Alternative: Supabase Management API (faster for direct Postgres)

The Management API bypasses CLI config entirely. Use this when CLI link is inconvenient or when GET /rest/v1/ returns empty [] due to RLS.

Power query — Management API (no RLS, no anon-key filtering):

`bash

curl -s -X POST "https://api.supabase.com/v1/projects//database/query" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

--data-raw '{"query": "SELECT id, email, role FROM public.profiles LIMIT 20;"}'

`

Where is the Supabase Management API personal access token (starts with sbp_).

This always returns raw Postgres rows — no supabase link, no CWD, no RLS. Useful for quick ad-hoc debugging.