Skip to content

docs(cli): correct inaccurate SIDE_EFFECTS.md and AGENTS.md claims #5813

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Coly010 merged 1 commit into from
Jul 7, 2026
Merged

docs(cli): correct inaccurate SIDE_EFFECTS.md and AGENTS.md claims #5813

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions apps/cli/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,14 +90,14 @@ Always check `src/shared/` before writing new infrastructure. Do not duplicate w

Also check the following `legacy/` infrastructure before writing equivalent helpers from scratch:

| Path | What it provides |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `legacy/config/legacy-cli-config.layer.ts` | `LegacyCliConfig` — resolves `SUPABASE_PROFILE` (built-in name **or** YAML file path), `--workdir`, `--experimental`, project-id from `supabase/config.toml` |
| `legacy/config/legacy-project-ref.layer.ts` | `LegacyProjectRefResolver` — `--project-ref` flag → env → linked-project.json → config fallback chain; matches Go's resolver order |
| `legacy/telemetry/legacy-telemetry-state.layer.ts` | `LegacyTelemetryState.flush` — writes `~/.supabase/telemetry.json`, runs in every command's `Effect.ensuring` |
| `legacy/telemetry/legacy-linked-project-cache.layer.ts` | `LegacyLinkedProjectCache.cache(ref)` — writes `~/.supabase/<workdir-hash>/linked-project.json` after `--project-ref` resolves; bypasses generated schema validation (uses raw HTTP client) |
| `legacy/auth/legacy-http-debug.layer.ts` | `legacyHttpClientLayer` — wraps the HTTP transport with a `--debug` stderr logger in Go's `log.LstdFlags` format |
| `legacy/output/legacy-glamour-table.ts` | `renderGlamourTable(headers, rows)` — byte-exact ASCII match for Go's `glamour.RenderTable(..., AsciiStyle)` |
| Path | What it provides |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `legacy/config/legacy-cli-config.layer.ts` | `LegacyCliConfig` — resolves `SUPABASE_PROFILE` (built-in name **or** YAML file path), `--workdir`, `--experimental`, project-id from `supabase/config.toml` |
| `legacy/config/legacy-project-ref.layer.ts` | `LegacyProjectRefResolver` — `--project-ref` flag → env → `supabase/.temp/project-ref` file → prompt; matches Go's resolver order |
| `legacy/telemetry/legacy-telemetry-state.layer.ts` | `LegacyTelemetryState.flush` — writes `~/.supabase/telemetry.json`, runs in every command's `Effect.ensuring` |
| `legacy/telemetry/legacy-linked-project-cache.layer.ts` | `LegacyLinkedProjectCache.cache(ref)` — writes `<workdir>/supabase/.temp/linked-project.json` after `--project-ref` resolves; bypasses generated schema validation (uses raw HTTP client) |
| `legacy/auth/legacy-http-debug.layer.ts` | `legacyHttpClientLayer` — wraps the HTTP transport with a `--debug` stderr logger in Go's `log.LstdFlags` format |
| `legacy/output/legacy-glamour-table.ts` | `renderGlamourTable(headers, rows)` — byte-exact ASCII match for Go's `glamour.RenderTable(..., AsciiStyle)` |

---

Expand Down Expand Up @@ -286,7 +286,7 @@ The legacy shell sends the same PostHog events to the same product analytics pip

| Command | Event | Identity / groups | Go source |
| ------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- |
| `login` | `cli_login_completed` | `analytics.alias(gotrueId, deviceId)` + `analytics.identify(gotrueId)` after token persists | `internal/login/login.go:283-296` |
| `login` | `cli_login_completed` | `analytics.alias(gotrueId, deviceId)` after token persists | `internal/login/login.go:283-296` |
| `link` | `cli_project_linked` | `analytics.groupIdentify("organization", slug, …)` + `analytics.groupIdentify("project", ref, …)` after link write | `internal/link/link.go:60` |
| `start` | `cli_stack_started` | none — fired after stack health check passes | `internal/start/start.go:1245` |
| `sso/{list,create,update,remove}`, `branches/{create,update}` | `cli_upgrade_suggested` | none — payload is `{feature_key, org_slug}`, fired inside billing-gate error branch | 7 call-sites under `internal/{sso,branches}/` |
Expand Down
10 changes: 5 additions & 5 deletions apps/cli/src/legacy/commands/branches/update/SIDE_EFFECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,10 @@ Same auth and project-ref resolution chain as every Management-API legacy comman

## Files Written

| Path | Format | When |
| ------------------------------------------------ | ------ | ------------------------------------------------------------------------ |
| `~/.supabase/<workdir-hash>/linked-project.json` | JSON | always (in `Effect.ensuring`) after `--project-ref` resolves — Go parity |
| `~/.supabase/telemetry.json` | JSON | always (in `Effect.ensuring`) at end of command — Go parity |
| Path | Format | When |
| ---------------------------------------------- | ------ | ------------------------------------------------------------------------ |
| `<workdir>/supabase/.temp/linked-project.json` | JSON | always (in `Effect.ensuring`) after `--project-ref` resolves — Go parity |
| `~/.supabase/telemetry.json` | JSON | always (in `Effect.ensuring`) at end of command — Go parity |

## API Routes

Expand Down Expand Up @@ -51,4 +51,4 @@ In Go encoder modes, the header goes to stderr followed by the encoded payload o

## Notes

The upgrade-suggest call uses the parent project ref (resolved from `--project-ref`) rather than the branch's project ref. Both refs belong to the same organization, so the entitlement check returns the same `org_slug` either way; this also sidesteps a known API schema constraint where `getProject` strictly requires a `^[a-z]{20}$` ref.
The upgrade-suggest call uses the branch's own resolved project ref (`legacyResolveBranchProjectRef`), matching Go's `update.go:26` (`pause.GetBranchProjectRef`) — not the parent `--project-ref` value — so the entitlements check is scoped to the branch's org.
24 changes: 17 additions & 7 deletions apps/cli/src/legacy/commands/completion/SIDE_EFFECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,10 @@

## Exit Codes

| Code | Condition |
| ---- | ------------------------------------------------------------------ |
| `0` | success — completion script for the chosen shell printed to stdout |
| `1` | invocation error (missing or unknown shell subcommand) |
| Code | Condition |
| ---- | -------------------------------------------------------------------------------------------------------------------- |
| `0` | success — completion script for the chosen shell printed to stdout |
| `1` | unknown shell subcommand, or bare `completion` with no shell subcommand — **known divergence, see Notes (CLI-1906)** |

## Output

Expand Down Expand Up @@ -58,9 +58,19 @@ straight to the Go binary.
- Effect CLI's `--completions` global flag remains exposed at the root for `next/`
users; it does not satisfy the legacy parity contract and is not what this
subcommand routes through.
- The Go CLI exits non-zero when called without a shell subcommand (e.g.
`supabase completion`). Effect CLI surfaces the same condition through its usual
"missing subcommand" help-with-exit-1 behavior.
- **Known divergence (CLI-1906):** Go's cobra CLI exits `0` on both bare
`completion` (no shell subcommand) AND `completion <unknown-shell>` — cobra
treats an unrecognized subcommand name the same as a missing one: a
non-`Runnable()` command with no `RunE` returns `flag.ErrHelp`, which cobra
maps to printing help and returning a nil error (verified against the
compiled Go binary for both cases: `completion` and `completion
bogus-shell` both exit `0`). The legacy TS shell currently exits `1` for
both invocations; this is a real, systemic exit-code bug in the shared CLI
harness (`shared/cli/run.ts`), not `completion`-specific — it reproduces on
any bare or unrecognized-subcommand invocation of a group command with
subcommands (e.g. `branches`, `branches bogus-subcommand`). See CLI-1906 for
the fix; this doc describes current (buggy) behavior, not the intended
target.
- Each of `bash`/`zsh`/`fish`/`powershell` declares `--no-descriptions` (cobra's
auto-registered flag, `completions.go` in `spf13/cobra`) and forwards it to the
Go binary, so the emitted script omits completion descriptions exactly as it
Expand Down
23 changes: 12 additions & 11 deletions apps/cli/src/legacy/commands/config/push/SIDE_EFFECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,20 +7,21 @@ local → if changed, print the unified diff and confirm → PATCH/PUT/POST.

## Files Read

| Path | Format | When |
| ------------------------------------------------ | ------------------------- | --------------------------------------------------------------- |
| `<workdir>/supabase/config.toml` | TOML | always, before any network call (parse error aborts, exit 1) |
| `<workdir>/supabase/.env`, `.env.local` | dotenv | always, to resolve `env(VAR)` references inside `config.toml` |
| Auth email template HTML (`content_path`) | HTML | when `auth.enabled`; paths resolved per Go rules (see below) |
| `~/.supabase/<workdir-hash>/linked-project.json` | JSON | project-ref fallback (flag → `SUPABASE_PROJECT_ID` → this file) |
| `~/.supabase/access-token` | plain text (token string) | when `SUPABASE_ACCESS_TOKEN` unset and keyring unavailable |
| Path | Format | When |
| ---------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<workdir>/supabase/config.toml` | TOML | always, before any network call (parse error aborts, exit 1) |
| `<workdir>/supabase/.env`, `.env.local` | dotenv | always, to resolve `env(VAR)` references inside `config.toml` |
| Auth email template HTML (`content_path`) | HTML | when `auth.enabled`; paths resolved per Go rules (see below) |
| `<workdir>/supabase/.temp/project-ref` | plain text | project-ref fallback (flag → `SUPABASE_PROJECT_ID` → this file) |
| `<workdir>/supabase/.temp/linked-project.json` | JSON | existence check only, to decide whether the cache write below is skipped (mirrors Go's `ensureProjectGroupsCached` telemetry cache — see `db/lint`'s Notes for the full mechanism) |
| `~/.supabase/access-token` | plain text (token string) | when `SUPABASE_ACCESS_TOKEN` unset and keyring unavailable |

## Files Written

| Path | Format | When |
| ------------------------------------------------ | ------ | ---------------------------------------------------------------------- |
| `~/.supabase/<workdir-hash>/linked-project.json` | JSON | `Effect.ensuring` after run (success **and** failure), if ref resolved |
| `~/.supabase/telemetry.json` | JSON | `Effect.ensuring` after run (success **and** failure) |
| Path | Format | When |
| ---------------------------------------------- | ------ | ---------------------------------------------------------------------- |
| `<workdir>/supabase/.temp/linked-project.json` | JSON | `Effect.ensuring` after run (success **and** failure), if ref resolved |
| `~/.supabase/telemetry.json` | JSON | `Effect.ensuring` after run (success **and** failure) |

No writes to `config.toml`.

Expand Down
6 changes: 3 additions & 3 deletions apps/cli/src/legacy/commands/db/branch/create/SIDE_EFFECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@

## Files Written

| Path | Format | When |
| ------------------------------------------------ | --------- | ------ |
| `<workdir>/.branches/<branch-name>/` (directory) | directory | always |
| Path | Format | When |
| --------------------------------------------------------- | --------- | ------ |
| `<workdir>/supabase/.branches/<branch-name>/` (directory) | directory | always |

## API Routes

Expand Down
6 changes: 3 additions & 3 deletions apps/cli/src/legacy/commands/db/branch/delete/SIDE_EFFECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@

## Files Written

| Path | Format | When |
| ------------------------------------------------ | --------- | ------- |
| `<workdir>/.branches/<branch-name>/` (directory) | directory | removed |
| Path | Format | When |
| --------------------------------------------------------- | --------- | ------- |
| `<workdir>/supabase/.branches/<branch-name>/` (directory) | directory | removed |

## API Routes

Expand Down
2 changes: 1 addition & 1 deletion apps/cli/src/legacy/commands/db/branch/list/SIDE_EFFECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,4 +48,4 @@ Not applicable.
## Notes

- Deprecated in the Go CLI: use `branches list` instead.
- This is a local-only operation listing branches in `<workdir>/.branches/`.
- This is a local-only operation listing branches in `<workdir>/supabase/.branches/`.
6 changes: 3 additions & 3 deletions apps/cli/src/legacy/commands/db/branch/switch/SIDE_EFFECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@

## Files Written

| Path | Format | When |
| ------------------------------------ | ---------- | ------ |
| `<workdir>/.supabase/current-branch` | plain text | always |
| Path | Format | When |
| ---------------------------------------------- | ---------- | ------ |
| `<workdir>/supabase/.branches/_current_branch` | plain text | always |

## API Routes

Expand Down
13 changes: 8 additions & 5 deletions apps/cli/src/legacy/commands/db/lint/SIDE_EFFECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,18 @@ Native TypeScript port of Go's `internal/db/lint`.

## Files Written

| Path | Format | When |
| ---------------------------- | ------ | ---------------------------------------------------- |
| `~/.supabase/telemetry.json` | JSON | always (PostHog state flush, Go `PersistentPostRun`) |
| Path | Format | When |
| ---------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| `<workdir>/supabase/.temp/linked-project.json` | JSON | `--linked` only, via `LegacyLinkedProjectCache.cache` (Go's `ensureProjectGroupsCached`, `cmd/root.go:174,212-234`) |
| `~/.supabase/telemetry.json` | JSON | always (PostHog state flush, Go `PersistentPostRun`) |

No user data is written: the lint runs inside a transaction that is **always
rolled back** (`BEGIN` … `ROLLBACK`), matching Go — including
`CREATE EXTENSION plpgsql_check`, which is issued on the same connection inside
the open transaction and so is rolled back too. `db lint` does not write the
linked-project cache (it has no `LegacyLinkedProjectCache` dependency).
the open transaction and so is rolled back too. `db lint` DOES write the
linked-project cache when run with `--linked` (matching Go's
`ensureProjectGroupsCached`); the default `--local` and `--db-url` paths never
populate a project ref, so no cache write occurs there.

## API Routes

Expand Down
5 changes: 4 additions & 1 deletion apps/cli/src/legacy/commands/db/remote/commit/SIDE_EFFECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,10 @@

### `--output-format text` (Go CLI compatible)

Prints `Finished supabase db pull.` on success.
Prints `Schema written to <path>` to stderr on success (from the shared
`pull.Run`, `internal/db/pull/pull.go:72`); no stdout confirmation message is
printed. The `Finished supabase db pull.` PostRun message belongs only to
`db pull` (`cmd/db.go:198-200`), not `db remote commit`.

### `--output-format json`

Expand Down
12 changes: 9 additions & 3 deletions apps/cli/src/legacy/commands/db/schema/declarative/generate/SIDE_EFFECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,9 +54,15 @@ pg-delta catalog (source) against the target database's catalog (target).

## Output

Text mode only (no machine envelope). Diagnostics + the final
`Declarative schema written to <dir>` go to stderr; the PostRun prints
`Finished supabase db schema declarative generate.` to stdout on success.
Diagnostics (target resolution, prompts, `Declarative schema written to <dir>`)
always go to stderr, in every `--output-format`. On success:

- `text` mode prints `Finished supabase db schema declarative generate.` to
stdout (matches Go's PostRun `fmt.Println`, `cmd/db_schema_declarative.go:116-118`).
- `json`/`stream-json` mode instead emits a structured success envelope
(`output.success("Finished supabase db schema declarative generate.")`) so
the machine stdout payload isn't corrupted by a bare human line
(`generate.command.ts:74-90`, CLI-1546 invariant).

## Notes

Expand Down
Loading
Loading