diff --git a/apps/cli/docs/go-cli-porting-status.md b/apps/cli/docs/go-cli-porting-status.md
index 49a7fe9c95..18a2fd46a5 100644
--- a/apps/cli/docs/go-cli-porting-status.md
+++ b/apps/cli/docs/go-cli-porting-status.md
@@ -155,12 +155,12 @@ The old Go `storage` family could target either the linked project or the local
 
 Current TS only exposes low-level Management API routes under [`api`](../src/next/commands/platform/api.command.ts). This tracker does not count those routes as parity for the old `storage` object-management CLI surface, especially because there is no TS equivalent for the old local Storage API workflow.
 
-| Old command  | TS status | New TS counterpart(s) | Notes                                                                                                                                                                                                      |
-| ------------ | --------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `storage cp` | `missing` | `missing`             | No TS object copy command in `next/`. Legacy shell proxy exposes `--recursive`, `--local`, `--linked`, `--cache-control`, `--content-type`, `--copy-metadata` matching the Go CLI flag surface.            |
-| `storage ls` | `missing` | `missing`             | No TS object listing command in `next/`. Legacy shell proxy exposes `--recursive`, `--local`, `--linked` matching the Go CLI flag surface.                                                                 |
-| `storage mv` | `missing` | `missing`             | No TS object move command in `next/`. Legacy shell proxy exposes `--recursive`, `--local`, `--linked` matching the Go CLI flag surface.                                                                    |
-| `storage rm` | `missing` | `missing`             | No TS object remove command in `next/`. Legacy shell proxy exposes `--recursive`, `--local`, `--linked` matching the Go CLI flag surface. Pass global `--yes` to skip the interactive confirmation prompt. |
+| Old command  | TS status | New TS counterpart(s) | Notes                                                                                                                                                                                                                                                                                                                               |
+| ------------ | --------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `storage cp` | `missing` | `missing`             | No TS object copy command in `next/`. Natively ported in the legacy shell ([`legacy/commands/storage/cp/`](../src/legacy/commands/storage/cp/cp.command.ts)) — `--recursive`, `--local`, `--linked`, `--cache-control`, `--content-type`, `--jobs` (Go has no `--copy-metadata`). Adds TS-only `--output-format json\|stream-json`. |
+| `storage ls` | `missing` | `missing`             | No TS object listing command in `next/`. Natively ported in the legacy shell ([`legacy/commands/storage/ls/`](../src/legacy/commands/storage/ls/ls.command.ts)) — `--recursive`, `--local`, `--linked`. Adds TS-only `--output-format json\|stream-json`.                                                                           |
+| `storage mv` | `missing` | `missing`             | No TS object move command in `next/`. Natively ported in the legacy shell ([`legacy/commands/storage/mv/`](../src/legacy/commands/storage/mv/mv.command.ts)) — `--recursive`, `--local`, `--linked`. Adds TS-only `--output-format json\|stream-json`.                                                                              |
+| `storage rm` | `missing` | `missing`             | No TS object remove command in `next/`. Natively ported in the legacy shell ([`legacy/commands/storage/rm/`](../src/legacy/commands/storage/rm/rm.command.ts)) — `--recursive`, `--local`, `--linked`; global `--yes`/`SUPABASE_YES` skips the confirmation. Adds TS-only `--output-format json\|stream-json`.                      |
 
 ## Management APIs
 
@@ -291,10 +291,10 @@ Legend:
 | `functions deploy`                     | `ported`      | [`../src/legacy/commands/functions/deploy/deploy.command.ts`](../src/legacy/commands/functions/deploy/deploy.command.ts)                                                                                                                                                   |
 | `functions new`                        | `wrapped`     | [`../src/legacy/commands/functions/new/new.command.ts`](../src/legacy/commands/functions/new/new.command.ts)                                                                                                                                                               |
 | `functions serve`                      | `ported`      | [`../src/legacy/commands/functions/serve/serve.command.ts`](../src/legacy/commands/functions/serve/serve.command.ts)                                                                                                                                                       |
-| `storage ls`                           | `wrapped`     | [`../src/legacy/commands/storage/ls/ls.command.ts`](../src/legacy/commands/storage/ls/ls.command.ts)                                                                                                                                                                       |
-| `storage cp`                           | `wrapped`     | [`../src/legacy/commands/storage/cp/cp.command.ts`](../src/legacy/commands/storage/cp/cp.command.ts)                                                                                                                                                                       |
-| `storage mv`                           | `wrapped`     | [`../src/legacy/commands/storage/mv/mv.command.ts`](../src/legacy/commands/storage/mv/mv.command.ts)                                                                                                                                                                       |
-| `storage rm`                           | `wrapped`     | [`../src/legacy/commands/storage/rm/rm.command.ts`](../src/legacy/commands/storage/rm/rm.command.ts)                                                                                                                                                                       |
+| `storage ls`                           | `ported`      | [`../src/legacy/commands/storage/ls/ls.command.ts`](../src/legacy/commands/storage/ls/ls.command.ts)                                                                                                                                                                       |
+| `storage cp`                           | `ported`      | [`../src/legacy/commands/storage/cp/cp.command.ts`](../src/legacy/commands/storage/cp/cp.command.ts)                                                                                                                                                                       |
+| `storage mv`                           | `ported`      | [`../src/legacy/commands/storage/mv/mv.command.ts`](../src/legacy/commands/storage/mv/mv.command.ts)                                                                                                                                                                       |
+| `storage rm`                           | `ported`      | [`../src/legacy/commands/storage/rm/rm.command.ts`](../src/legacy/commands/storage/rm/rm.command.ts)                                                                                                                                                                       |
 | `test db`                              | `ported`      | [`../src/legacy/commands/test/db/db.command.ts`](../src/legacy/commands/test/db/db.command.ts)                                                                                                                                                                             |
 | `test new`                             | `ported`      | [`../src/legacy/commands/test/new/new.command.ts`](../src/legacy/commands/test/new/new.command.ts)                                                                                                                                                                         |
 | `seed buckets`                         | `ported`      | [`../src/legacy/commands/seed/buckets/buckets.command.ts`](../src/legacy/commands/seed/buckets/buckets.command.ts)                                                                                                                                                         |
diff --git a/apps/cli/src/legacy/commands/seed/buckets/buckets.command.ts b/apps/cli/src/legacy/commands/seed/buckets/buckets.command.ts
index 8c23144d05..20c9b269fe 100644
--- a/apps/cli/src/legacy/commands/seed/buckets/buckets.command.ts
+++ b/apps/cli/src/legacy/commands/seed/buckets/buckets.command.ts
@@ -6,7 +6,7 @@ import { withJsonErrorHandling } from "../../../../shared/output/json-error-hand
 import { withLegacyCommandInstrumentation } from "../../../telemetry/legacy-command-instrumentation.ts";
 import { LegacySeedLinkedFlag, LegacySeedLocalFlag } from "../seed.flags.ts";
 import { legacyAssertSeedTargetsExclusive } from "./buckets.flags.ts";
-import { legacySeedRuntimeLayer } from "../seed.layers.ts";
+import { legacyStorageGatewayRuntimeLayer } from "../../../shared/legacy-storage-runtime.layer.ts";
 import { legacySeedBuckets } from "./buckets.handler.ts";
 
 // `--linked`/`--local` are scoped globals on the `seed` group (`seed.flags.ts`),
@@ -36,5 +36,5 @@ export const legacyBucketsCommand = Command.make("buckets").pipe(
       return yield* legacySeedBuckets(flags).pipe(withLegacyCommandInstrumentation({ flags }));
     }).pipe(withJsonErrorHandling),
   ),
-  Command.provide(legacySeedRuntimeLayer(["seed", "buckets"])),
+  Command.provide(legacyStorageGatewayRuntimeLayer(["seed", "buckets"])),
 );
diff --git a/apps/cli/src/legacy/commands/seed/buckets/buckets.errors.ts b/apps/cli/src/legacy/commands/seed/buckets/buckets.errors.ts
index b5b72fa75f..2f3e9efa6f 100644
--- a/apps/cli/src/legacy/commands/seed/buckets/buckets.errors.ts
+++ b/apps/cli/src/legacy/commands/seed/buckets/buckets.errors.ts
@@ -1,35 +1,20 @@
 import { Data } from "effect";
 
 /**
- * Domain errors for `supabase seed buckets`.
+ * Domain errors specific to `supabase seed buckets`.
  *
- * The Storage service-gateway calls fail with one of two shapes, mirroring Go's
- * `pkg/fetcher`:
- *   - transport failure (`failed to execute http request`) →
- *     `LegacySeedStorageNetworkError`
- *   - non-2xx response (`Error status <d>: <body>`, `pkg/fetcher/http.go:112`) →
- *     `LegacySeedStorageStatusError`
- *
- * `message` reproduces Go's verbatim error text so the vector graceful-skip
- * classifiers in `buckets.classify.ts` match on the same substrings Go inspects.
+ * The Storage gateway and credential-derivation errors are shared with
+ * `storage ls/cp/mv/rm` and live in `legacy/shared/legacy-storage-gateway.errors.ts`
+ * and `legacy/shared/legacy-storage-credentials.errors.ts`. This file keeps only
+ * the seed-specific errors.
  */
-export class LegacySeedStorageNetworkError extends Data.TaggedError(
-  "LegacySeedStorageNetworkError",
-)<{
-  readonly message: string;
-}> {}
-
-export class LegacySeedStorageStatusError extends Data.TaggedError("LegacySeedStorageStatusError")<{
-  readonly status: number;
-  readonly body: string;
-  readonly message: string;
-}> {}
 
 /**
- * Raised when `supabase/config.toml` cannot be parsed. Mirrors the `config push`
- * CLI-1489 tradeoff (`config/push/push.handler.ts:96-114`): `loadProjectConfig`
- * raises `ProjectConfigParseError` on `env(...)` refs over numeric/bool fields,
- * which Go resolves transparently.
+ * Raised when `supabase/config.toml` cannot be parsed, or a config-load-time
+ * validation Go runs before any Storage call fails (bucket name regex,
+ * `file_size_limit` numeral). Mirrors the `config push` CLI-1489 tradeoff:
+ * `loadProjectConfig` raises `ProjectConfigParseError` on `env(...)` refs over
+ * numeric/bool fields, which Go resolves transparently.
  */
 export class LegacySeedConfigLoadError extends Data.TaggedError("LegacySeedConfigLoadError")<{
   readonly message: string;
@@ -44,37 +29,3 @@ export class LegacySeedMutuallyExclusiveFlagsError extends Data.TaggedError(
 )<{
   readonly message: string;
 }> {}
-
-/**
- * Raised on `--linked` when the project's api-keys response yields no keys,
- * mirroring Go's `tenant.GetApiKeys` → `errMissingKey` ("Anon key not found.",
- * `apps/cli-go/internal/utils/tenant/client.go:16,80-82`), which aborts before
- * the remote Storage client is built. Message matches Go verbatim.
- */
-export class LegacySeedMissingApiKeyError extends Data.TaggedError("LegacySeedMissingApiKeyError")<{
-  readonly message: string;
-}> {}
-
-/**
- * Transport failure fetching the project's api-keys on `--linked`, mirroring Go's
- * `tenant.GetApiKeys` network path (`failed to get api keys: <cause>`).
- */
-export class LegacySeedApiKeysNetworkError extends Data.TaggedError(
-  "LegacySeedApiKeysNetworkError",
-)<{
-  readonly message: string;
-}> {}
-
-/**
- * `GET /v1/projects/{ref}/api-keys?reveal=true` returned a non-200 status on a
- * `--linked` run. Byte-matches Go's `tenant.GetApiKeys` → `ErrAuthToken`,
- * `"Authorization failed for the access token and project ref pair: " + body`
- * (`apps/cli-go/internal/utils/tenant/client.go:15,77-78`). This is the user-facing
- * error for an invalid access token / project-ref pair — distinct from the
- * `projects api-keys` helper's `unexpected get api keys status ...`.
- */
-export class LegacySeedAuthTokenError extends Data.TaggedError("LegacySeedAuthTokenError")<{
-  readonly status: number;
-  readonly body: string;
-  readonly message: string;
-}> {}
diff --git a/apps/cli/src/legacy/commands/seed/buckets/buckets.flags.ts b/apps/cli/src/legacy/commands/seed/buckets/buckets.flags.ts
index b9a7f587b8..3f4bb5fe46 100644
--- a/apps/cli/src/legacy/commands/seed/buckets/buckets.flags.ts
+++ b/apps/cli/src/legacy/commands/seed/buckets/buckets.flags.ts
@@ -1,67 +1,18 @@
 import { Effect } from "effect";
 
-import {
-  VALUE_CONSUMING_LONG_FLAGS,
-  VALUE_CONSUMING_SHORT_FLAGS,
-} from "../../../shared/legacy-db-target-flags.ts";
+import { legacyChangedLinkedLocalFlags } from "../../../shared/legacy-db-target-flags.ts";
 import { LegacySeedMutuallyExclusiveFlagsError } from "./buckets.errors.ts";
 
 /**
- * Detects which of `--local` / `--linked` were explicitly set on the command
- * line, reproducing cobra's `pflag.Changed` for `seed`'s
- * `MarkFlagsMutuallyExclusive("local", "linked")` (`apps/cli-go/cmd/seed.go:32`).
- *
- * Effect CLI's parsed flags carry no `Changed` bit, so we re-derive it from raw
- * argv. Value-consuming flags (`--workdir <path>`, `-o <fmt>`, …) skip their
- * value token to avoid false positives like `--workdir --linked`.
- *
- * Returned in cobra's alphabetically-sorted order `["linked", "local"]` so the
- * rendered conflict string matches Go exactly.
+ * Detects which of `--local` / `--linked` were explicitly set, reproducing
+ * cobra's `pflag.Changed` for `seed`'s `MarkFlagsMutuallyExclusive`
+ * (`apps/cli-go/cmd/seed.go:32`). Delegates to the shared linked/local scanner
+ * (also used by `storage`). The seed target is selected from this changed set
+ * (Go's `flag.Changed`, via `internal/utils/flags/db_url.go:46-63`), not the
+ * parsed flag value.
  */
 export function legacySeedChangedTargetFlags(args: ReadonlyArray<string>): ReadonlyArray<string> {
-  let linked = false;
-  let local = false;
-  let skipNext = false;
-
-  for (const token of args) {
-    if (skipNext) {
-      skipNext = false;
-      continue;
-    }
-    if (token === "--") break;
-
-    if (token.startsWith("--")) {
-      const eqIdx = token.indexOf("=");
-      const name = eqIdx === -1 ? token.slice(2) : token.slice(2, eqIdx);
-      const isBare = eqIdx === -1;
-      // Treat Effect CLI's boolean negation form (`--no-linked`/`--no-local`) as
-      // "changed" too — it sets the flag false but is unambiguously present on
-      // argv, the TS equivalent of cobra's `pflag.Changed` (and the seed target
-      // is selected from Changed, not the value, so `--no-linked` is still the
-      // linked path). Mirrors the sibling DB scanner (legacy-db-target-flags.ts).
-      if (name === "linked" || name === "no-linked") {
-        linked = true;
-        continue;
-      }
-      if (name === "local" || name === "no-local") {
-        local = true;
-        continue;
-      }
-      if (isBare && VALUE_CONSUMING_LONG_FLAGS.has(name)) skipNext = true;
-      continue;
-    }
-
-    if (token.startsWith("-") && token.length >= 2 && token.charAt(1) !== "-") {
-      if (token.length === 2 && VALUE_CONSUMING_SHORT_FLAGS.has(token.charAt(1))) {
-        skipNext = true;
-      }
-    }
-  }
-
-  const setFlags: Array<string> = [];
-  if (linked) setFlags.push("linked");
-  if (local) setFlags.push("local");
-  return setFlags;
+  return legacyChangedLinkedLocalFlags(args);
 }
 
 /**
diff --git a/apps/cli/src/legacy/commands/seed/buckets/buckets.gateway.unit.test.ts b/apps/cli/src/legacy/commands/seed/buckets/buckets.gateway.unit.test.ts
deleted file mode 100644
index da2b2972b5..0000000000
--- a/apps/cli/src/legacy/commands/seed/buckets/buckets.gateway.unit.test.ts
+++ /dev/null
@@ -1,40 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { legacyBucketBody } from "./buckets.gateway.ts";
-
-describe("legacyBucketBody", () => {
-  it("omits public when undefined (Go *bool nil / omitempty)", () => {
-    expect(legacyBucketBody({ public: undefined, fileSizeLimit: 0, allowedMimeTypes: [] })).toEqual(
-      {},
-    );
-  });
-
-  it("includes public when explicitly set (true or false)", () => {
-    expect(legacyBucketBody({ public: true, fileSizeLimit: 0, allowedMimeTypes: [] })).toEqual({
-      public: true,
-    });
-    expect(legacyBucketBody({ public: false, fileSizeLimit: 0, allowedMimeTypes: [] })).toEqual({
-      public: false,
-    });
-  });
-
-  it("omits file_size_limit when 0 and allowed_mime_types when empty", () => {
-    expect(
-      legacyBucketBody({ public: undefined, fileSizeLimit: 0, allowedMimeTypes: [] }),
-    ).not.toHaveProperty("file_size_limit");
-  });
-
-  it("includes file_size_limit and allowed_mime_types when present", () => {
-    expect(
-      legacyBucketBody({
-        public: false,
-        fileSizeLimit: 52_428_800,
-        allowedMimeTypes: ["image/png"],
-      }),
-    ).toEqual({
-      public: false,
-      file_size_limit: 52_428_800,
-      allowed_mime_types: ["image/png"],
-    });
-  });
-});
diff --git a/apps/cli/src/legacy/commands/seed/buckets/buckets.handler.ts b/apps/cli/src/legacy/commands/seed/buckets/buckets.handler.ts
index 9450ac1b56..7e91961b04 100644
--- a/apps/cli/src/legacy/commands/seed/buckets/buckets.handler.ts
+++ b/apps/cli/src/legacy/commands/seed/buckets/buckets.handler.ts
@@ -1,10 +1,8 @@
 import {
-  KONG_LOCAL_CA_CERT,
   loadProjectConfig,
   type LoadProjectConfigOptions,
   ProjectConfigSchema,
 } from "@supabase/config";
-import { defaultJwtSecret, generateJwt } from "@supabase/stack/effect";
 import { Effect, FileSystem, Option, Path, Schema } from "effect";
 import { FetchHttpClient } from "effect/unstable/http";
 import type { PlatformError } from "effect/PlatformError";
@@ -13,145 +11,41 @@ import { CliArgs } from "../../../../shared/cli/cli-args.service.ts";
 import { LegacyYesFlag } from "../../../../shared/legacy/global-flags.ts";
 import { LegacyCliConfig } from "../../../config/legacy-cli-config.service.ts";
 import { LegacyProjectRefResolver } from "../../../config/legacy-project-ref.service.ts";
-import { LegacyPlatformApiFactory } from "../../../auth/legacy-platform-api-factory.service.ts";
-import { legacyMapTenantApiKeysError } from "../../../shared/legacy-get-tenant-api-keys.ts";
-import { legacyExtractServiceKeys } from "../../../shared/legacy-tenant-keys.ts";
-import { LegacyLinkedProjectCache } from "../../../telemetry/legacy-linked-project-cache.service.ts";
-import { LegacyTelemetryState } from "../../../telemetry/legacy-telemetry-state.service.ts";
 import { legacySeedChangedTargetFlags } from "./buckets.flags.ts";
 import { legacyBold, legacyYellow } from "../../../shared/legacy-colors.ts";
-import { legacyGetHostname } from "../../../shared/legacy-hostname.ts";
-import { Output } from "../../../../shared/output/output.service.ts";
 import {
-  legacyIsLocalVectorBucketsUnavailable,
-  legacyIsVectorBucketsFeatureNotEnabled,
-} from "./buckets.classify.ts";
+  legacyResolveStorageCredentials,
+  legacyStorageGatewayFetch,
+} from "../../../shared/legacy-storage-credentials.ts";
+import {
+  legacyParseFileSizeLimit,
+  legacyResolveBucketProps,
+} from "../../../shared/legacy-storage-bucket-config.ts";
 import {
   type LegacyStorageGateway,
   type LegacyUpsertBucketProps,
   legacyMakeStorageGateway,
-} from "./buckets.gateway.ts";
+} from "../../../shared/legacy-storage-gateway.ts";
+import type { LegacyStorageGatewayError } from "../../../shared/legacy-storage-gateway.errors.ts";
+import { Output } from "../../../../shared/output/output.service.ts";
 import {
-  LegacySeedApiKeysNetworkError,
-  LegacySeedAuthTokenError,
-  LegacySeedConfigLoadError,
-  LegacySeedMissingApiKeyError,
-  LegacySeedStorageNetworkError,
-  LegacySeedStorageStatusError,
-} from "./buckets.errors.ts";
+  legacyIsLocalVectorBucketsUnavailable,
+  legacyIsVectorBucketsFeatureNotEnabled,
+} from "./buckets.classify.ts";
+import { LegacySeedConfigLoadError } from "./buckets.errors.ts";
+import { legacyBucketObjectKey } from "./buckets.upload.ts";
+import { legacyPromptYesNo } from "../../../shared/legacy-prompt-yes-no.ts";
 import {
-  legacyBucketObjectKey,
   legacyContentTypeForUpload,
-  legacyParseFileSizeLimit,
-} from "./buckets.upload.ts";
+  legacyReadSniffBytes,
+} from "../../../shared/legacy-storage-content-type.ts";
+import { LegacyLinkedProjectCache } from "../../../telemetry/legacy-linked-project-cache.service.ts";
+import { LegacyTelemetryState } from "../../../telemetry/legacy-telemetry-state.service.ts";
 import type { LegacyBucketsFlags } from "./buckets.command.ts";
 
 const CONFIG_PATH = "supabase/config.toml";
 const UPLOAD_CONCURRENCY = 5;
 
-/**
- * Builds a `typeof globalThis.fetch` that injects `tls.ca` into every request,
- * trusting the provided CA PEM for HTTPS connections to the local Kong gateway.
- *
- * Mirrors Go's `newLocalClient` (`apps/cli-go/internal/storage/client/api.go:30-37`),
- * which appends `utils.Config.Api.Tls.CertContent` to the TLS cert pool.
- *
- * Bun's fetch accepts `{ tls: { ca: string } }` in the same position as
- * `BunFetchRequestInit.tls`; the `ca` field is Bun-specific and is typed via
- * `BunFetchRequestInit` (a Bun global). No `as` cast is needed: the init object
- * is typed as `BunFetchRequestInit` which extends the standard `RequestInit`.
- */
-function legacyKongCaFetch(ca: string): typeof globalThis.fetch {
-  const fetchImpl = async (
-    input: string | URL | Request,
-    init?: RequestInit,
-  ): Promise<Response> => {
-    const caInit: BunFetchRequestInit = { ...init, tls: { ca } };
-    return globalThis.fetch(input, caInit);
-  };
-  // Attach `preconnect` so the override is structurally complete as
-  // `typeof globalThis.fetch` — mirrors the same pattern in legacy-http-dns.ts.
-  return Object.assign(fetchImpl, { preconnect: globalThis.fetch.preconnect });
-}
-
-/**
- * Validates and resolves the local Kong TLS configuration, mirroring Go's
- * `(*api).Validate` (`apps/cli-go/pkg/config/config.go:845-861`) which runs at
- * config-load before `NewStorageAPI`:
- *  1. `cert_path` set, `key_path` empty → error
- *  2. `cert_path` set, unreadable → error
- *  3. `key_path` set, `cert_path` empty → error
- *  4. `key_path` set, unreadable → error
- *  5. Both set and readable → returns the CA PEM (cert content)
- *  6. Neither set → returns the embedded `KONG_LOCAL_CA_CERT`
- *
- * The CLI only uses the CA cert for trusting the Kong gateway, but Go also reads
- * the key purely to validate the pairing, so we mirror that behaviour.
- *
- * // TODO: broader `@supabase/config` gap — `packages/config/src/api.ts` models
- * // `tls.cert_path` / `tls.key_path` but has no pairing or readability validation.
- * // Once @supabase/config adds `(*api).Validate`, this helper can be removed and
- * // the error mapping moved to the `ProjectConfigParseError` catch above.
- *
- * Only called when `projectRef === ""` (local) AND `config.api.enabled` AND
- * `config.api.tls.enabled` — Go gates both path resolution (`config.go:795`)
- * and validation (`config.go:841`) on `c.Api.Enabled`.
- */
-const validateLocalKongTls = Effect.fnUntraced(function* (
-  fs: FileSystem.FileSystem,
-  path: Path.Path,
-  workdir: string,
-  certPath: string | undefined,
-  keyPath: string | undefined,
-) {
-  const hasCert = certPath !== undefined && certPath.length > 0;
-  const hasKey = keyPath !== undefined && keyPath.length > 0;
-
-  if (hasCert && !hasKey) {
-    return yield* new LegacySeedConfigLoadError({
-      message: "Missing required field in config: api.tls.key_path",
-    });
-  }
-  if (hasKey && !hasCert) {
-    return yield* new LegacySeedConfigLoadError({
-      message: "Missing required field in config: api.tls.cert_path",
-    });
-  }
-
-  if (hasCert) {
-    // Go joins TLS paths unconditionally with the supabase dir — NO IsAbs guard
-    // (config.go:795-801 uses path.Join, which absorbs a leading "/" on the
-    // joined element), so `cert_path = "/tmp/kong.crt"` resolves under
-    // supabase/tmp/kong.crt. This differs from objects_path below, which Go
-    // guards with !filepath.IsAbs (config.go:753-761).
-    const absCert = path.join(workdir, "supabase", certPath);
-    const certContent = yield* fs.readFileString(absCert).pipe(
-      Effect.catchTag(
-        "PlatformError",
-        (cause) =>
-          new LegacySeedConfigLoadError({
-            message: `failed to read TLS cert: ${String(cause.cause ?? cause)}`,
-          }),
-      ),
-    );
-    // keyPath is non-empty here because hasKey === true (cert+key both present);
-    // joined unconditionally, same as cert_path above (config.go:795-801).
-    const absKey = path.join(workdir, "supabase", keyPath!);
-    yield* fs.readFileString(absKey).pipe(
-      Effect.catchTag(
-        "PlatformError",
-        (cause) =>
-          new LegacySeedConfigLoadError({
-            message: `failed to read TLS key: ${String(cause.cause ?? cause)}`,
-          }),
-      ),
-    );
-    return certContent;
-  }
-
-  return KONG_LOCAL_CA_CERT;
-});
-
 /**
  * Mirrors Go's `ValidateBucketName` regex (`apps/cli-go/pkg/config/config.go:1382`).
  * Used to validate `[storage.buckets]` names before any Storage API call, matching
@@ -175,8 +69,6 @@ const legacyValidateBucketName = Effect.fnUntraced(function* (name: string) {
   }
 });
 
-type StorageError = LegacySeedStorageNetworkError | LegacySeedStorageStatusError;
-
 interface CollectedFile {
   readonly absPath: string;
   readonly displayPath: string;
@@ -213,9 +105,8 @@ function emptySummary(): SeedSummary {
  * Embedded-default project config, decoded from an empty object — the same
  * `decodeUnknownSync(ProjectConfigSchema)({})` the loader uses internally
  * (`packages/config/src/io.ts:54-56`). Go's `seed buckets` never aborts on a
- * missing `config.toml`: it reads the package-global `utils.Config`, which is
- * initialized to embedded defaults (`internal/utils/config.go:100`), and
- * `config.Load` no-ops on a missing file (`mergeFileConfig` → nil). So "no
+ * missing `config.toml`: it reads the package-global `utils.Config`, initialized
+ * to embedded defaults, and `config.Load` no-ops on a missing file. So "no
  * config file" behaves like the embedded-default config.
  */
 const legacyDecodeDefaultProjectConfig = Schema.decodeUnknownSync(ProjectConfigSchema);
@@ -251,14 +142,9 @@ export const legacySeedBuckets = Effect.fn("legacy.seed.buckets")(function* (
   yield* Effect.gen(function* () {
     // 1. Resolve the project ref for --linked BEFORE loading config, so that
     // the matching `[remotes.<name>]` override (whose `project_id == ref`) is
-    // merged over the base config by `loadProjectConfig`. Mirrors Go's
-    // `Config.ProjectId = ProjectRef` → `config.Load` sequence
-    // (`apps/cli-go/pkg/config/config.go:505-518`).
-    // Go selects the target from `flag.Changed`, not the flag value
-    // (`internal/utils/flags/db_url.go:46-63`): `--linked` is the linked path
-    // whenever it's *set*, even `--linked=false`. Use the changed-flag set
-    // (the `--local`/`--linked` mutual-exclusivity is enforced before
-    // instrumentation in `buckets.command.ts`), not `flags.linked`'s value.
+    // merged over the base config by `loadProjectConfig`. Go selects the target
+    // from `flag.Changed`, not the flag value: `--linked` is the linked path
+    // whenever it's *set* (even `--linked=false`).
     const setFlags = legacySeedChangedTargetFlags(cliArgs.args);
     const projectRefResolver = yield* LegacyProjectRefResolver;
     const projectRef = setFlags.includes("linked")
@@ -280,20 +166,14 @@ export const legacySeedBuckets = Effect.fn("legacy.seed.buckets")(function* (
       ),
     );
     // A missing config file is NOT an early exit: Go uses embedded defaults and
-    // still gates the no-op on `len(projectRef) == 0` (`internal/seed/buckets/
-    // buckets.go:16-20`). So local + no-config falls into the no-op short-circuit
-    // below (emitting the empty summary in json/stream-json); `--linked` +
-    // no-config falls through to the remote path so auth/project/API failures
-    // surface, exactly as the Go command does.
+    // still gates the no-op on `len(projectRef) == 0`. So local + no-config falls
+    // into the no-op short-circuit; `--linked` + no-config falls through to the
+    // remote path so auth/project/API failures surface.
     const config = loaded === null ? legacyDecodeDefaultProjectConfig({}) : loaded.config;
     const document = loaded === null ? undefined : loaded.document;
 
-    // Go prints this from inside config load (`config.go:513`,
-    // `fmt.Fprintln(os.Stderr, "Loading config override:", idToName[projectId])`),
-    // unconditionally and before any command output, whenever a `[remotes.*]`
-    // block's project_id matched the linked ref. `appliedRemote` is the bare name,
-    // bracketed here to match Go's `idToName` value (`config.go:511`). Same emit as
-    // `config push` (push.handler.ts). stderr in all output modes (diagnostic-only).
+    // Go prints this from inside config load (`config.go:513`) whenever a
+    // `[remotes.*]` block matched the linked ref. stderr in all output modes.
     if (loaded !== null && loaded.appliedRemote !== undefined) {
       yield* output.raw(`Loading config override: [remotes.${loaded.appliedRemote}]\n`, "stderr");
     }
@@ -313,8 +193,7 @@ export const legacySeedBuckets = Effect.fn("legacy.seed.buckets")(function* (
       yield* legacyValidateBucketName(name);
     }
 
-    // 3b. Storage-level file_size_limit, parsed unconditionally (Go unmarshals
-    // `storage.FileSizeLimit` at config.Load regardless of buckets).
+    // 3b. Storage-level file_size_limit, parsed unconditionally.
     const storageFileSizeLimitBytes = yield* parseFileSizeLimitOrFail(
       config.storage.file_size_limit,
     );
@@ -330,8 +209,6 @@ export const legacySeedBuckets = Effect.fn("legacy.seed.buckets")(function* (
 
     // 3d. Short-circuit: nothing to seed (ref present → never short-circuits).
     if (projectRef === "" && bucketNames.length === 0 && !hasVectorBuckets) {
-      // Go emits nothing in text mode; in the additive json/stream-json modes a
-      // scripted caller still expects a result object, so emit an empty summary.
       if (output.format !== "text") {
         yield* output.success("", { ...emptySummary() });
       }
@@ -339,88 +216,16 @@ export const legacySeedBuckets = Effect.fn("legacy.seed.buckets")(function* (
     }
 
     // 4. Build the Storage service-gateway client (local or remote).
-    let baseUrl: string;
-    let apiKey: string;
-
-    if (projectRef === "") {
-      baseUrl = resolveLocalBaseUrl(config);
-      apiKey = yield* resolveLocalServiceRoleKey(config.auth);
-    } else {
-      baseUrl = `https://${projectRef}.${cliConfig.projectHost}`;
-      const envKey = process.env["SUPABASE_AUTH_SERVICE_ROLE_KEY"];
-      if (envKey !== undefined && envKey.length > 0) {
-        apiKey = envKey;
-      } else {
-        // Go builds the remote Storage client via `tenant.GetApiKeys`
-        // (`internal/storage/client/api.go:22`), which maps a non-200 to
-        // `Authorization failed for the access token and project ref pair: <body>`
-        // (`internal/utils/tenant/client.go:15,77-78`) — NOT the `projects api-keys`
-        // helper's `unexpected get api keys status ...`. Resolve the client lazily
-        // so the local path never triggers Management API auth.
-        const api = yield* (yield* LegacyPlatformApiFactory).make;
-        const keys = legacyExtractServiceKeys(
-          yield* api.v1.getProjectApiKeys({ ref: projectRef, reveal: true }).pipe(
-            Effect.catch(
-              legacyMapTenantApiKeysError({
-                networkError: LegacySeedApiKeysNetworkError,
-                statusError: LegacySeedAuthTokenError,
-              }),
-            ),
-          ),
-        );
-        // Go's tenant.GetApiKeys fails with errMissingKey ("Anon key not found.")
-        // when the api-keys response yields nothing, before building the remote
-        // Storage client (`internal/utils/tenant/client.go:24-26,80-82`).
-        if (keys.anon === "" && keys.serviceRole === "") {
-          return yield* new LegacySeedMissingApiKeyError({ message: "Anon key not found." });
-        }
-        apiKey = keys.serviceRole;
-      }
-    }
+    const credentials = yield* legacyResolveStorageCredentials({ projectRef, config });
 
-    // Kong CA trust for the LOCAL path. Go's `newLocalClient` installs
-    // `status.NewKongClient` unconditionally (`internal/storage/client/api.go:30-37`)
-    // — its embedded CA only matters for https — and `(*api).Validate` resolves
-    // `cert_path`/`key_path` (`config.go:795`) and validates the cert/key pairing
-    // (`config.go:841-861`) only when `api.enabled && api.tls.enabled` (both
-    // blocks are gated on `c.Api.Enabled`). So: validate (and resolve a cert_path
-    // CA) only when the api is enabled AND tls is enabled; inject the CA whenever
-    // the resolved local URL is https — Go derives the scheme from `api.tls.enabled`
-    // alone (`config.go:639-642`, NOT gated on `api.enabled`), so an `enabled=false`
-    // + `tls.enabled=true` config still yields an https URL and the embedded CA —
-    // and never for the remote `--linked` host.
-    let localKongCa: string | undefined;
-    if (projectRef === "") {
-      const validatedCa =
-        config.api.enabled && config.api.tls.enabled
-          ? yield* validateLocalKongTls(
-              fs,
-              path,
-              cliConfig.workdir,
-              config.api.tls.cert_path,
-              config.api.tls.key_path,
-            )
-          : undefined;
-      if (baseUrl.startsWith("https:")) {
-        localKongCa = validatedCa ?? KONG_LOCAL_CA_CERT;
-      }
-    }
-
-    // All gateway operations run with an explicit non-DoH fetch. Storage calls
-    // never use DoH in Go: `newLocalClient` uses `status.NewKongClient` and
-    // `newRemoteClient` uses `http.DefaultClient` — `withFallbackDNS` is installed
-    // only in `utils.GetSupabase` (Management API, `internal/utils/api.go:125-127`).
-    // `legacyHttpClientLayer` bakes the DoH wrapper into the shared client, so we
-    // override `FetchHttpClient.Fetch` at this scope UNCONDITIONALLY: a CA-trusting
-    // fetch for local + https, plain `globalThis.fetch` otherwise. (`Fetch` is read
-    // per request from the fiber context, so the scope override applies to every
-    // gateway call.) The api-keys lookup above runs through the platform API factory
-    // BEFORE this scope, so it still honors `--dns-resolver https`, matching Go's
-    // `tenant.GetApiKeys` → `GetSupabase`.
+    // All gateway operations run with an explicit non-DoH fetch (CA-trusting for
+    // local + https, plain `globalThis.fetch` otherwise). The api-keys lookup
+    // inside `legacyResolveStorageCredentials` runs BEFORE this scope, so it
+    // still honors `--dns-resolver https`, matching Go's `tenant.GetApiKeys`.
     const gatewayOps = Effect.gen(function* () {
       const gateway = yield* legacyMakeStorageGateway({
-        baseUrl,
-        apiKey,
+        baseUrl: credentials.baseUrl,
+        apiKey: credentials.apiKey,
         userAgent: cliConfig.userAgent,
       });
 
@@ -458,19 +263,15 @@ export const legacySeedBuckets = Effect.fn("legacy.seed.buckets")(function* (
       }
     });
 
-    // Non-DoH fetch for every gateway call: CA-trusting for local + https, plain
-    // `globalThis.fetch` otherwise. Never the DoH-wrapped shared client.
     yield* gatewayOps.pipe(
       Effect.provideService(
         FetchHttpClient.Fetch,
-        localKongCa !== undefined ? legacyKongCaFetch(localKongCa) : globalThis.fetch,
+        legacyStorageGatewayFetch(credentials.localKongCa),
       ),
     );
   }).pipe(
     // Go's root `Execute` caches the linked project + fires org/project group
     // identify whenever `flags.ProjectRef` is set — only on the --linked path.
-    // `suspend` defers reading `linkedRef` until the finalizer runs (after the
-    // ref has been resolved inside the gen).
     Effect.ensuring(
       Effect.suspend(() => (linkedRef === "" ? Effect.void : linkedProjectCache.cache(linkedRef))),
     ),
@@ -478,82 +279,6 @@ export const legacySeedBuckets = Effect.fn("legacy.seed.buckets")(function* (
   );
 });
 
-/**
- * Local API URL, mirroring Go's `config.go:634-644` + `misc.go:298`: an explicit
- * `api.external_url` wins, otherwise `<scheme>://<host>:<port>` where the scheme
- * follows `api.tls.enabled`, the host is resolved by `legacyGetHostname` (Go's
- * `utils.GetHostname`: `SUPABASE_SERVICES_HOSTNAME` → TCP Docker daemon host →
- * `127.0.0.1`), and the port is `api.port`.
- */
-function resolveLocalBaseUrl(config: {
-  readonly api: {
-    readonly external_url?: string;
-    readonly port: number;
-    readonly tls: { readonly enabled: boolean };
-  };
-}): string {
-  if (config.api.external_url !== undefined && config.api.external_url.length > 0) {
-    return config.api.external_url;
-  }
-  const host = legacyGetHostname();
-  const scheme = config.api.tls.enabled ? "https" : "http";
-  // Go builds the host:port with net.JoinHostPort (config.go:636-638), which
-  // brackets an IPv6 host (e.g. `::1` → `[::1]:54321`); a bare `::1:54321` is an
-  // invalid URL. legacyGetHostname returns the unbracketed host, so bracket here.
-  const hostPort = host.includes(":")
-    ? `[${host}]:${config.api.port}`
-    : `${host}:${config.api.port}`;
-  return `${scheme}://${hostPort}`;
-}
-
-/**
- * Resolve the service-role key used against the local Storage gateway, mirroring
- * Go's `(*auth).generateAPIKeys` (`apps/cli-go/pkg/config/apikeys.go:43-63`),
- * which `config.Load` always runs before `NewStorageAPI`. Applies env-var
- * precedence matching Go's Viper `AutomaticEnv`+`SUPABASE_` prefix
- * (`apps/cli-go/pkg/config/config.go:492-497`):
- *  - jwt secret: `SUPABASE_AUTH_JWT_SECRET` env (if set & non-empty) →
- *    `auth.jwt_secret` (if non-empty) → `defaultJwtSecret`;
- *  - a resolved secret shorter than 16 chars is rejected;
- *  - service-role key: `SUPABASE_AUTH_SERVICE_ROLE_KEY` env (if set & non-empty) →
- *    `auth.service_role_key` (if non-empty) → sign from resolved secret.
- *
- * `@supabase/config` has no `generateAPIKeys` equivalent (the keys are
- * `optionalKey` with no default), so this fill-in is the caller's job. Empty
- * checks use length, not nullishness, so an explicit `service_role_key = ""` is
- * regenerated like Go (`??` would have sent the empty string). An unresolved
- * `env(...)` literal is passed through verbatim, exactly as Go does
- * (`pkg/config/decode_hooks.go:15-26` leaves it, and a non-empty literal is not
- * regenerated by `generateAPIKeys`).
- */
-const resolveLocalServiceRoleKey = Effect.fnUntraced(function* (auth: {
-  readonly jwt_secret?: string;
-  readonly service_role_key?: string;
-}) {
-  // Apply env-var precedence for jwt_secret (Go Viper AutomaticEnv).
-  const envSecret = process.env["SUPABASE_AUTH_JWT_SECRET"];
-  const configuredSecret =
-    envSecret !== undefined && envSecret.length > 0 ? envSecret : auth.jwt_secret;
-
-  let jwtSecret: string;
-  if (configuredSecret === undefined || configuredSecret.length === 0) {
-    jwtSecret = defaultJwtSecret;
-  } else if (configuredSecret.length < 16) {
-    return yield* new LegacySeedConfigLoadError({
-      message: "Invalid config for auth.jwt_secret. Must be at least 16 characters",
-    });
-  } else {
-    jwtSecret = configuredSecret;
-  }
-
-  // Apply env-var precedence for service_role_key (Go Viper AutomaticEnv).
-  const envKey = process.env["SUPABASE_AUTH_SERVICE_ROLE_KEY"];
-  const configuredKey = envKey !== undefined && envKey.length > 0 ? envKey : auth.service_role_key;
-  return configuredKey !== undefined && configuredKey.length > 0
-    ? configuredKey
-    : generateJwt(jwtSecret, "service_role");
-});
-
 type BucketsConfig = Readonly<
   Record<
     string,
@@ -566,56 +291,6 @@ type BucketsConfig = Readonly<
   >
 >;
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-/**
- * Whether the bucket's TOML entry explicitly declares a `public` key. Go reads
- * `public` into a `*bool`, so an absent key serialises as omitted (not `false`).
- * The decoded `@supabase/config` value defaults to `false` and loses this, so we
- * recover presence from the raw (post-`env()`) document.
- */
-function bucketHasPublicKey(document: Record<string, unknown> | undefined, name: string): boolean {
-  return bucketHasKey(document, name, "public");
-}
-
-/**
- * Whether the bucket's TOML entry explicitly declares `file_size_limit`. Absent
- * decodes to the bucket schema default (`50MiB`), losing the "omitted" signal Go
- * relies on to inherit the storage-level limit, so recover presence from the raw
- * (post-`env()`) document — same approach as `bucketHasPublicKey`.
- */
-function bucketHasFileSizeLimit(
-  document: Record<string, unknown> | undefined,
-  name: string,
-): boolean {
-  return bucketHasKey(document, name, "file_size_limit");
-}
-
-function bucketHasKey(
-  document: Record<string, unknown> | undefined,
-  name: string,
-  key: string,
-): boolean {
-  if (document === undefined) return false;
-  const storage = document["storage"];
-  if (!isRecord(storage)) return false;
-  const buckets = storage["buckets"];
-  if (!isRecord(buckets)) return false;
-  const bucket = buckets[name];
-  return isRecord(bucket) && key in bucket;
-}
-
-/**
- * Resolve a bucket's create/update props, mirroring Go's `config.resolve()`
- * (`apps/cli-go/pkg/config/config.go:753-756`) + the `sizeInBytes` decode that
- * happens at config-load **before** `NewStorageAPI`:
- *  - an omitted or zero `file_size_limit` inherits the storage-level limit;
- *  - the size is parsed up front, so an invalid value fails (mapped to a
- *    config-load error) before any Storage list/create/update side effect — Go
- *    rejects the same config during `LoadConfig`.
- */
 // Parse a `file_size_limit` string to bytes, mapping a parse failure to a
 // config-load error (Go rejects an invalid `sizeInBytes` during `config.Load`,
 // before NewStorageAPI).
@@ -628,50 +303,19 @@ const parseFileSizeLimitOrFail = (value: string) =>
       }),
   });
 
-const computeBucketProps = Effect.fnUntraced(function* (
+const computeBucketProps = (
   document: Record<string, unknown> | undefined,
   name: string,
   bucket: BucketsConfig[string],
   storageFileSizeLimitBytes: number,
-) {
-  // Go's resolve() inherits the (already-parsed) storage-level limit when the
-  // bucket omits its own / sets 0 (`config.go:753-756`).
-  const bucketBytes = bucketHasFileSizeLimit(document, name)
-    ? yield* parseFileSizeLimitOrFail(bucket.file_size_limit)
-    : 0;
-  const fileSizeLimit = bucketBytes === 0 ? storageFileSizeLimitBytes : bucketBytes;
-
-  return {
-    public: bucketHasPublicKey(document, name) ? bucket.public : undefined,
-    fileSizeLimit,
-    allowedMimeTypes: bucket.allowed_mime_types,
-  } satisfies LegacyUpsertBucketProps;
-});
-
-/**
- * Confirm-or-default prompt mirroring Go's `console.PromptYesNo`
- * (`internal/utils/console.go`): `--yes`/`SUPABASE_YES` echoes `<label> [Y/n] y`
- * and returns true even on a TTY; a real TTY in text mode otherwise prompts;
- * everything else (non-interactive, json/stream-json) uses the default silently.
- */
-const promptYesNo = Effect.fnUntraced(function* (
-  output: typeof Output.Service,
-  yes: boolean,
-  label: string,
-  defaultValue: boolean,
-) {
-  if (yes) {
-    const choices = defaultValue ? "Y/n" : "y/N";
-    yield* output.raw(`${label} [${choices}] y\n`, "stderr");
-    return true;
-  }
-  if (output.format !== "text") {
-    return defaultValue;
-  }
-  return yield* output
-    .promptConfirm(label, { defaultValue })
-    .pipe(Effect.catchTag("NonInteractiveError", () => Effect.succeed(defaultValue)));
-});
+) =>
+  Effect.try({
+    try: () => legacyResolveBucketProps({ document, name, bucket, storageFileSizeLimitBytes }),
+    catch: (cause) =>
+      new LegacySeedConfigLoadError({
+        message: cause instanceof Error ? cause.message : String(cause),
+      }),
+  });
 
 // Port of `pkg/storage/batch.go:UpsertBuckets`. `propsByName` is precomputed and
 // size-validated before this runs (Go parses sizes at config-load, before any
@@ -689,7 +333,7 @@ const upsertBuckets = Effect.fnUntraced(function* (
   for (const [name, props] of propsByName) {
     const bucketId = byName.get(name);
     if (bucketId !== undefined) {
-      const overwrite = yield* promptYesNo(
+      const overwrite = yield* legacyPromptYesNo(
         output,
         yes,
         `Bucket ${legacyBold(bucketId)} already exists. Do you want to overwrite its properties?`,
@@ -734,7 +378,7 @@ const upsertVectorBuckets = Effect.fnUntraced(function* (
   }
 
   for (const name of toDelete) {
-    const prune = yield* promptYesNo(
+    const prune = yield* legacyPromptYesNo(
       output,
       yes,
       `Bucket ${legacyBold(name)} not found in ${legacyBold(CONFIG_PATH)}. Do you want to prune it?`,
@@ -773,7 +417,7 @@ const upsertAnalyticsBuckets = Effect.fnUntraced(function* (
   }
 
   for (const name of toDelete) {
-    const prune = yield* promptYesNo(
+    const prune = yield* legacyPromptYesNo(
       output,
       yes,
       `Bucket ${legacyBold(name)} not found in ${legacyBold(CONFIG_PATH)}. Do you want to prune it?`,
@@ -795,7 +439,7 @@ const upsertAnalyticsBuckets = Effect.fnUntraced(function* (
  */
 const handleVectorError = Effect.fnUntraced(function* (
   output: typeof Output.Service,
-  error: StorageError,
+  error: LegacyStorageGatewayError,
   summary: SeedSummary,
 ) {
   if (legacyIsVectorBucketsFeatureNotEnabled(error.message)) {
@@ -817,34 +461,6 @@ const handleVectorError = Effect.fnUntraced(function* (
   return yield* Effect.fail(error);
 });
 
-// Content-type sniff window: Go reads the first 512 bytes (io.LimitReader,
-// `pkg/storage/objects.go:78-79`).
-const LEGACY_SNIFF_LEN = 512;
-
-/**
- * Read ONLY the first ≤512 bytes of a file for content-type sniffing, mirroring
- * Go's `io.LimitReader(f, 512)` (`pkg/storage/objects.go:78-79`) — the file is
- * NOT fully buffered (a large object would otherwise stall/OOM before the upload
- * request starts). Opens a handle, reads one sniff window, and closes it via
- * `Effect.scoped`. Returns an empty buffer on EOF (empty file → Go sniffs "" →
- * text/plain) or any read error — an unreadable file then fails at the streaming
- * upload open below, so the sniff result is moot in that case.
- */
-const legacyReadSniffBytes = Effect.fnUntraced(function* (
-  fs: FileSystem.FileSystem,
-  absPath: string,
-) {
-  return yield* Effect.scoped(
-    Effect.gen(function* () {
-      const handle = yield* fs.open(absPath, { flag: "r" });
-      return yield* handle.readAlloc(LEGACY_SNIFF_LEN);
-    }),
-  ).pipe(
-    Effect.map(Option.getOrElse(() => new Uint8Array(0))),
-    Effect.catch(() => Effect.succeed(new Uint8Array(0))),
-  );
-});
-
 // Port of `pkg/storage/batch.go:UpsertObjects` (+ object walk in objects.go).
 const uploadObjects = Effect.fnUntraced(function* (
   fs: FileSystem.FileSystem,
@@ -860,12 +476,10 @@ const uploadObjects = Effect.fnUntraced(function* (
     if (objectsPath.length === 0) {
       continue;
     }
-    // Go resolves a relative bucket objects_path against SupabaseDirPath (the
-    // `supabase/` dir) at config-resolve time (`pkg/config/config.go:757-759`);
-    // absolute paths are left untouched. `@supabase/config` doesn't reproduce
-    // this and `workdir` is the project root, so apply the `supabase/` prefix
-    // here. `displayRoot` (workdir-relative) drives the `Uploading:` stderr and
-    // the destination key so both stay byte-identical to Go.
+    // Go resolves a relative bucket objects_path against SupabaseDirPath at
+    // config-resolve time (`pkg/config/config.go:757-759`); absolute paths are
+    // left untouched. `displayRoot` (workdir-relative) drives the `Uploading:`
+    // stderr and the destination key so both stay byte-identical to Go.
     const displayRoot = path.isAbsolute(objectsPath)
       ? objectsPath
       : path.join("supabase", objectsPath);
@@ -881,18 +495,15 @@ const uploadObjects = Effect.fnUntraced(function* (
           yield* output.raw(`Uploading: ${file.displayPath} => ${dstPath}\n`, "stderr");
           // Content-type is byte-driven: Go sniffs the first 512 bytes with
           // http.DetectContentType, refining only a generic text/plain by
-          // extension (`pkg/storage/objects.go:77-108`). Read the sniff window
-          // here (an unreadable file → empty sniff; the streaming open below then
-          // surfaces the real error), then stream the full file into the body.
+          // extension (`pkg/storage/objects.go:77-108`).
           const sniff = yield* legacyReadSniffBytes(fs, file.absPath);
-          // Stream the file into the request body — Go opens the file and streams
-          // the io.Reader (`pkg/storage/objects.go:94-127`) rather than buffering
-          // each object fully into memory.
-          yield* gateway.uploadObject(
-            dstPath,
-            file.absPath,
-            legacyContentTypeForUpload(sniff, file.absPath),
-          );
+          // Go's seed upload always sets Cache-Control max-age=3600 and x-upsert
+          // (Overwrite) true (`pkg/storage/batch.go`).
+          yield* gateway.uploadObject(dstPath, file.absPath, {
+            contentType: legacyContentTypeForUpload(sniff, file.absPath),
+            cacheControl: "max-age=3600",
+            overwrite: true,
+          });
           summary.objects_uploaded.push(dstPath);
         }),
       { concurrency: UPLOAD_CONCURRENCY },
@@ -906,15 +517,11 @@ const uploadObjects = Effect.fnUntraced(function* (
  *
  * Parity details:
  *  - The **root** is resolved with a following stat (Go's `fs.Stat`), so a
- *    symlinked `objects_path` is followed; a missing/dangling root fails the
- *    command, as Go's WalkDir does.
- *  - **Nested** entries use no-follow detection (Go reads `DirEntry` from
- *    `ReadDir`): real directories are descended; symlinks are NOT descended —
- *    Go's `isUploadableEntry` OPENS the symlink target (`fsys.Open`, requiring
- *    read access) then stats the handle, uploading only a regular file and
- *    skipping dangling symlinks / symlinks-to-directories / unreadable targets
- *    with `Skipping non-regular file:` (no crash). Stat alone would queue an
- *    unreadable target and abort later at upload, so the symlink branch opens.
+ *    symlinked `objects_path` is followed; a missing/dangling root fails.
+ *  - **Nested** entries use no-follow detection: real directories are descended;
+ *    symlinks are NOT descended — Go's `isUploadableEntry` OPENS the symlink
+ *    target then stats the handle, uploading only a regular file and skipping
+ *    dangling symlinks / symlinks-to-directories / unreadable targets.
  */
 const collectFiles = (
   fs: FileSystem.FileSystem,
@@ -955,14 +562,9 @@ const collectDir = (
         Effect.catch(() => Effect.succeed(false)),
       );
       if (isSymlink) {
-        // Go `isUploadableEntry` (batch.go:73-84) OPENS the target (fsys.Open,
-        // requiring read access) then stats the handle; it uploads only a regular
-        // file and skips on either an open OR a stat error. `stat` alone follows
-        // the link but needs no read permission on the target, so a symlink to an
-        // unreadable-but-existing regular file would stat as "File", get queued,
-        // then abort the whole run when `uploadObject` opens it to stream. Mirror
-        // Go: open + stat, closing the handle (Go's `defer f.Close()`) via
-        // `Effect.scoped`. Any open/stat failure falls through to the skip path.
+        // Go `isUploadableEntry` (batch.go:73-84) OPENS the target then stats the
+        // handle; it uploads only a regular file. `stat` alone would queue an
+        // unreadable target and abort later at upload, so mirror Go: open + stat.
         const targetType = yield* Effect.scoped(
           Effect.gen(function* () {
             const handle = yield* fs.open(absChild, { flag: "r" });
diff --git a/apps/cli/src/legacy/commands/seed/buckets/buckets.integration.test.ts b/apps/cli/src/legacy/commands/seed/buckets/buckets.integration.test.ts
index 5aae1d1b0c..674cf9f82e 100644
--- a/apps/cli/src/legacy/commands/seed/buckets/buckets.integration.test.ts
+++ b/apps/cli/src/legacy/commands/seed/buckets/buckets.integration.test.ts
@@ -1485,7 +1485,7 @@ describe("legacy seed buckets", () => {
       );
       expect(Exit.isFailure(exit)).toBe(true);
       const json = JSON.stringify(exit);
-      expect(json).toContain("LegacySeedAuthTokenError");
+      expect(json).toContain("LegacyStorageAuthTokenError");
       expect(json).toContain("Authorization failed for the access token and project ref pair");
       expect(json).not.toContain("unexpected get api keys status");
       // Fails before any remote Storage call.
diff --git a/apps/cli/src/legacy/commands/seed/buckets/buckets.upload.ts b/apps/cli/src/legacy/commands/seed/buckets/buckets.upload.ts
index 51bb58a58f..6fb1a31929 100644
--- a/apps/cli/src/legacy/commands/seed/buckets/buckets.upload.ts
+++ b/apps/cli/src/legacy/commands/seed/buckets/buckets.upload.ts
@@ -1,13 +1,11 @@
 import * as nodePath from "node:path";
 
-import { legacyDetectContentType } from "../../../shared/legacy-detect-content-type.ts";
-import { ramInBytes } from "../../../shared/legacy-size-units.ts";
-
 /**
- * Pure path/encoding helpers for object upload, ported from
- * `apps/cli-go/pkg/storage/{objects,batch}.go`. Kept free of Effect / services
- * so the Go-parity rules (destination-key mapping, size parsing, content-type
- * fallback) stay unit-testable.
+ * Pure path helper for `seed buckets` object upload, ported from Go's
+ * `UpsertObjects` (`apps/cli-go/pkg/storage/batch.go`). Content-type resolution
+ * and the sniff read live in `legacy/shared/legacy-storage-content-type.ts`
+ * (shared with `storage cp`); size parsing in
+ * `legacy/shared/legacy-storage-bucket-config.ts`.
  */
 
 /**
@@ -33,114 +31,3 @@ export function legacyBucketObjectKey(
   const relPosix = relPath.split(nodePath.sep).join(nodePath.posix.sep);
   return nodePath.posix.join(bucketName, relPosix);
 }
-
-/**
- * Parse a `[storage.buckets.*].file_size_limit` config string (e.g. `"50MiB"`)
- * to the int64 byte count Go sends in the create/update bucket body
- * (`int64(bucket.FileSizeLimit)`, `batch.go:38/49`). `@supabase/config` keeps
- * the field as the raw human-readable string, so the conversion Go performs at
- * config-load time happens here instead. Throws on an unparseable value, which
- * the handler maps to a config-load error.
- */
-export function legacyParseFileSizeLimit(sizeStr: string): number {
-  return ramInBytes(sizeStr);
-}
-
-/**
- * Content-type for an uploaded object, mirroring Go's `UploadObject`
- * (`apps/cli-go/pkg/storage/objects.go:77-108`): run `http.DetectContentType`
- * on the first 512 bytes (the **bytes** decide), and only when that returns a
- * generic `text/plain` refine it via `mime.TypeByExtension` on the file
- * extension. So a PNG/PDF named `.txt` is stored as `image/png`/`application/pdf`
- * (bytes win), while a plain-text file is refined to e.g. `application/json` by
- * its extension.
- *
- * `sniff` is the first ≤512 bytes of the file (Go's `io.LimitReader(f, 512)`).
- *
- * The extension table is Go's built-in `mime` table (`mime/type.go`
- * `builtinTypesLower`). NOTE: Go's `mime.TypeByExtension` additionally augments
- * this from the OS MIME database (`/etc/mime.types`, the Windows registry, …),
- * which is host-dependent and not reproduced here — the deterministic built-in
- * table is the faithful baseline and covers the standard extensions; the
- * byte-sniff step above (the dominant, non-text path) is reproduced exactly.
- */
-export function legacyContentTypeForUpload(sniff: Uint8Array, filePath: string): string {
-  const detected = legacyDetectContentType(sniff);
-  if (detected.includes("text/plain")) {
-    const ext = nodePath.extname(filePath).toLowerCase();
-    const refined = MIME_BY_EXTENSION[ext];
-    if (refined !== undefined && refined !== "") return refined;
-  }
-  return detected;
-}
-
-// Go's built-in `mime` extension table (`mime/type.go` `builtinTypesLower`),
-// used only to refine a generic `text/plain` sniff result. Keys are lowercase;
-// `legacyContentTypeForUpload` lowercases the extension before lookup, matching
-// `mime.TypeByExtension`'s case-insensitive fallback.
-const MIME_BY_EXTENSION: Readonly<Record<string, string>> = {
-  ".ai": "application/postscript",
-  ".apk": "application/vnd.android.package-archive",
-  ".apng": "image/apng",
-  ".avif": "image/avif",
-  ".bin": "application/octet-stream",
-  ".bmp": "image/bmp",
-  ".com": "application/octet-stream",
-  ".css": "text/css; charset=utf-8",
-  ".csv": "text/csv; charset=utf-8",
-  ".doc": "application/msword",
-  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-  ".ehtml": "text/html; charset=utf-8",
-  ".eml": "message/rfc822",
-  ".eps": "application/postscript",
-  ".exe": "application/octet-stream",
-  ".flac": "audio/flac",
-  ".gif": "image/gif",
-  ".gz": "application/gzip",
-  ".htm": "text/html; charset=utf-8",
-  ".html": "text/html; charset=utf-8",
-  ".ico": "image/vnd.microsoft.icon",
-  ".ics": "text/calendar; charset=utf-8",
-  ".jfif": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".jpg": "image/jpeg",
-  ".js": "text/javascript; charset=utf-8",
-  ".json": "application/json",
-  ".m4a": "audio/mp4",
-  ".mjs": "text/javascript; charset=utf-8",
-  ".mp3": "audio/mpeg",
-  ".mp4": "video/mp4",
-  ".oga": "audio/ogg",
-  ".ogg": "audio/ogg",
-  ".ogv": "video/ogg",
-  ".opus": "audio/ogg",
-  ".pdf": "application/pdf",
-  ".pjp": "image/jpeg",
-  ".pjpeg": "image/jpeg",
-  ".png": "image/png",
-  ".ppt": "application/vnd.ms-powerpoint",
-  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
-  ".ps": "application/postscript",
-  ".rdf": "application/rdf+xml",
-  ".rtf": "application/rtf",
-  ".shtml": "text/html; charset=utf-8",
-  ".svg": "image/svg+xml",
-  ".text": "text/plain; charset=utf-8",
-  ".tif": "image/tiff",
-  ".tiff": "image/tiff",
-  ".txt": "text/plain; charset=utf-8",
-  ".vtt": "text/vtt; charset=utf-8",
-  ".wasm": "application/wasm",
-  ".wav": "audio/wav",
-  ".webm": "audio/webm",
-  ".webp": "image/webp",
-  ".xbl": "text/xml; charset=utf-8",
-  ".xbm": "image/x-xbitmap",
-  ".xht": "application/xhtml+xml",
-  ".xhtml": "application/xhtml+xml",
-  ".xls": "application/vnd.ms-excel",
-  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-  ".xml": "text/xml; charset=utf-8",
-  ".xsl": "text/xml; charset=utf-8",
-  ".zip": "application/zip",
-};
diff --git a/apps/cli/src/legacy/commands/seed/buckets/buckets.upload.unit.test.ts b/apps/cli/src/legacy/commands/seed/buckets/buckets.upload.unit.test.ts
index 63098e7efa..1b3e60842e 100644
--- a/apps/cli/src/legacy/commands/seed/buckets/buckets.upload.unit.test.ts
+++ b/apps/cli/src/legacy/commands/seed/buckets/buckets.upload.unit.test.ts
@@ -1,17 +1,6 @@
 import { describe, expect, it } from "@effect/vitest";
 
-import {
-  legacyBucketObjectKey,
-  legacyContentTypeForUpload,
-  legacyParseFileSizeLimit,
-} from "./buckets.upload.ts";
-
-/** Latin-1 byte view of a string fixture. */
-function bytes(s: string): Uint8Array {
-  const out = new Uint8Array(s.length);
-  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i) & 0xff;
-  return out;
-}
+import { legacyBucketObjectKey } from "./buckets.upload.ts";
 
 describe("legacyBucketObjectKey", () => {
   it("maps a single-file objects_path to <bucket>/<basename>", () => {
@@ -34,87 +23,3 @@ describe("legacyBucketObjectKey", () => {
     expect(legacyBucketObjectKey("docs", "./assets", "assets/a.txt")).toBe("docs/a.txt");
   });
 });
-
-describe("legacyParseFileSizeLimit", () => {
-  it("parses a human-readable size to bytes", () => {
-    expect(legacyParseFileSizeLimit("50MiB")).toBe(50 * 1024 * 1024);
-  });
-
-  it("returns 0 for a zero limit", () => {
-    expect(legacyParseFileSizeLimit("0")).toBe(0);
-  });
-
-  it("throws on an unparseable value", () => {
-    expect(() => legacyParseFileSizeLimit("not-a-size")).toThrow();
-  });
-
-  it("accepts Go-valid numeral forms (strconv.ParseFloat parity)", () => {
-    // docker/go-units RAMInBytes hands the numeric part to strconv.ParseFloat,
-    // which accepts a leading/trailing dot, exponent, sign, and underscores
-    // between digits (Go 1.13+ literal rule).
-    expect(legacyParseFileSizeLimit(".5MiB")).toBe(Math.trunc(0.5 * 1024 * 1024));
-    expect(legacyParseFileSizeLimit("1.MiB")).toBe(1024 * 1024);
-    expect(legacyParseFileSizeLimit("1e6")).toBe(1_000_000);
-    expect(legacyParseFileSizeLimit("1_000MiB")).toBe(1000 * 1024 * 1024);
-    expect(legacyParseFileSizeLimit("1_0MiB")).toBe(10 * 1024 * 1024);
-  });
-
-  it("rejects badly-placed underscores (Go literal rule)", () => {
-    // Underscores only between digits — no leading/trailing/doubled.
-    expect(() => legacyParseFileSizeLimit("_1000MiB")).toThrow("invalid size");
-    expect(() => legacyParseFileSizeLimit("1__0MiB")).toThrow("invalid size");
-  });
-
-  it("rejects malformed numerals that JS parseFloat would truncate", () => {
-    // strconv.ParseFloat rejects the whole string; JS parseFloat parses a prefix.
-    expect(() => legacyParseFileSizeLimit("1.2.3MiB")).toThrow("invalid size");
-    expect(() => legacyParseFileSizeLimit("1 2MiB")).toThrow("invalid size");
-    expect(() => legacyParseFileSizeLimit("-5MiB")).toThrow("invalid size");
-  });
-
-  it("rejects an overflowing numeral (Go ParseFloat range error)", () => {
-    // 1e309 parses to Infinity in JS; Go's strconv.ParseFloat returns a range error.
-    expect(() => legacyParseFileSizeLimit("1e309")).toThrow("invalid size");
-  });
-});
-
-describe("legacyContentTypeForUpload", () => {
-  // Go: http.DetectContentType (bytes win) then refine only generic text/plain
-  // by extension via mime.TypeByExtension (objects.go:77-108).
-  it("lets the sniffed bytes win over the extension (PNG named .txt)", () => {
-    const png = bytes("\x89PNG\x0D\x0A\x1A\x0A\x00\x00");
-    expect(legacyContentTypeForUpload(png, "/x/a.txt")).toBe("image/png");
-  });
-
-  it("refines a generic text/plain sniff via the file extension", () => {
-    const text = bytes('{"a":1}'); // sniffs as text/plain
-    expect(legacyContentTypeForUpload(text, "/x/a.json")).toBe("application/json");
-    expect(legacyContentTypeForUpload(text, "/x/a.css")).toBe("text/css; charset=utf-8");
-  });
-
-  it("is case-insensitive on the extension for the text refinement", () => {
-    expect(legacyContentTypeForUpload(bytes("plain text"), "/x/A.JSON")).toBe("application/json");
-  });
-
-  it("keeps text/plain when a text file has no/unknown extension", () => {
-    // mime.TypeByExtension returns "" → Go keeps the sniffed text/plain.
-    expect(legacyContentTypeForUpload(bytes("plain text"), "/x/a.unknownext")).toBe(
-      "text/plain; charset=utf-8",
-    );
-    expect(legacyContentTypeForUpload(bytes("plain text"), "/x/noext")).toBe(
-      "text/plain; charset=utf-8",
-    );
-  });
-
-  it("does not refine a non-text sniff result by extension", () => {
-    // An SVG body sniffs as text/xml (not text/plain), so the .svg extension
-    // refinement is NOT applied — matches Go (refine gate is text/plain only).
-    const svg = bytes('<?xml version="1.0"?><svg></svg>');
-    expect(legacyContentTypeForUpload(svg, "/x/a.svg")).toBe("text/xml; charset=utf-8");
-  });
-
-  it("falls back to application/octet-stream for unrecognized binary content", () => {
-    const blob = bytes("\x00\x01\x02\x03\x04\x05garbage");
-    expect(legacyContentTypeForUpload(blob, "/x/a.bin")).toBe("application/octet-stream");
-  });
-});
diff --git a/apps/cli/src/legacy/commands/seed/seed.layers.ts b/apps/cli/src/legacy/commands/seed/seed.layers.ts
deleted file mode 100644
index 9095f30121..0000000000
--- a/apps/cli/src/legacy/commands/seed/seed.layers.ts
+++ /dev/null
@@ -1,83 +0,0 @@
-import { Layer } from "effect";
-import * as HttpClient from "effect/unstable/http/HttpClient";
-
-import { legacyCredentialsLayer } from "../../auth/legacy-credentials.layer.ts";
-import { legacyPlatformApiFactoryLayer } from "../../auth/legacy-platform-api-factory.layer.ts";
-import { LegacyPlatformApiFactory } from "../../auth/legacy-platform-api-factory.service.ts";
-import { legacyCliConfigLayer } from "../../config/legacy-cli-config.layer.ts";
-import { LegacyCliConfig } from "../../config/legacy-cli-config.service.ts";
-import { legacyProjectRefLayer } from "../../config/legacy-project-ref.layer.ts";
-import { LegacyProjectRefResolver } from "../../config/legacy-project-ref.service.ts";
-import { legacyDebugLoggerLayer } from "../../shared/legacy-debug-logger.layer.ts";
-import {
-  LegacyIdentityStitch,
-  legacyIdentityStitchLayer,
-} from "../../shared/legacy-identity-stitch.ts";
-import { legacyHttpClientLayer } from "../../auth/legacy-http-debug.layer.ts";
-import { legacyLinkedProjectCacheLayer } from "../../telemetry/legacy-linked-project-cache.layer.ts";
-import { LegacyLinkedProjectCache } from "../../telemetry/legacy-linked-project-cache.service.ts";
-import { legacyTelemetryStateLayer } from "../../telemetry/legacy-telemetry-state.layer.ts";
-import { LegacyTelemetryState } from "../../telemetry/legacy-telemetry-state.service.ts";
-import { commandRuntimeLayer } from "../../../shared/runtime/command-runtime.layer.ts";
-import { CommandRuntime } from "../../../shared/runtime/command-runtime.service.ts";
-
-/**
- * `seed buckets` uses the Storage gateway directly, so the Management API client
- * must be lazy: the LOCAL path (no `--linked`) never touches the Management API and
- * must not require a login. `legacyPlatformApiFactoryLayer` defers token resolution
- * to the first `factory.make` call, which only fires on the `--linked` branch.
- *
- * `HttpClient` is exposed at the top level (unlike `legacyGenTypesRuntimeLayer`)
- * because `buckets.handler.ts` uses the Storage gateway, which requires an `HttpClient`
- * service directly rather than going through the typed Management API client.
- */
-export function legacySeedRuntimeLayer(subcommand: ReadonlyArray<string>) {
-  const cliConfig = legacyCliConfigLayer.pipe(Layer.provide(legacyDebugLoggerLayer));
-  const httpClient = legacyHttpClientLayer.pipe(Layer.provide(legacyDebugLoggerLayer));
-  const credentials = legacyCredentialsLayer.pipe(
-    Layer.provide(cliConfig),
-    Layer.provide(legacyDebugLoggerLayer),
-  );
-  // Lazy factory: build does NOT resolve a token. Token resolution is deferred
-  // until `factory.make` is first called — i.e. when the `--linked` branch of
-  // `legacyGetProjectApiKeys` actually executes. The LOCAL path (no `--linked`)
-  // completes without touching the Management API. Mirrors
-  // `legacyGenTypesRuntimeLayer` and `legacyLinkedDbResolverRuntimeLayer`.
-  const platformApiFactory = legacyPlatformApiFactoryLayer.pipe(
-    Layer.provide(credentials),
-    Layer.provide(cliConfig),
-    Layer.provide(legacyDebugLoggerLayer),
-    Layer.provide(legacyIdentityStitchLayer),
-  );
-
-  const built = Layer.mergeAll(
-    cliConfig,
-    platformApiFactory,
-    httpClient,
-    legacyProjectRefLayer.pipe(Layer.provide(platformApiFactory), Layer.provide(cliConfig)),
-    legacyLinkedProjectCacheLayer.pipe(
-      Layer.provide(credentials),
-      Layer.provide(cliConfig),
-      Layer.provide(httpClient),
-      Layer.provide(legacyIdentityStitchLayer),
-    ),
-    legacyTelemetryStateLayer,
-    legacyIdentityStitchLayer,
-    commandRuntimeLayer([...subcommand]),
-  );
-
-  const _serviceCoverageCheck: Layer.Layer<LegacySeedServices, unknown, unknown> = built;
-  void _serviceCoverageCheck;
-
-  return built;
-}
-
-type LegacySeedServices =
-  | LegacyPlatformApiFactory
-  | LegacyCliConfig
-  | LegacyProjectRefResolver
-  | LegacyLinkedProjectCache
-  | LegacyTelemetryState
-  | LegacyIdentityStitch
-  | CommandRuntime
-  | HttpClient.HttpClient;
diff --git a/apps/cli/src/legacy/commands/storage/cp/SIDE_EFFECTS.md b/apps/cli/src/legacy/commands/storage/cp/SIDE_EFFECTS.md
index 5865755099..ab14d7165f 100644
--- a/apps/cli/src/legacy/commands/storage/cp/SIDE_EFFECTS.md
+++ b/apps/cli/src/legacy/commands/storage/cp/SIDE_EFFECTS.md
@@ -1,63 +1,87 @@
 # `supabase storage cp <src> <dst>`
 
+Native TypeScript port of `apps/cli-go/internal/storage/cp`. Copies objects between
+local paths and the Storage service. The scheme of `src`/`dst` selects the operation:
+`ss://`→local download, local→`ss://` upload, both `ss://` → error, both local → unsupported.
+
 ## Files Read
 
-| Path                       | Format     | When                                                       |
-| -------------------------- | ---------- | ---------------------------------------------------------- |
-| `~/.supabase/access-token` | plain text | when `SUPABASE_ACCESS_TOKEN` unset and keyring unavailable |
-| `<src>`                    | binary     | when src is a local file path                              |
+| Path                                     | Format     | When                                                               |
+| ---------------------------------------- | ---------- | ------------------------------------------------------------------ |
+| `<workdir>/supabase/config.toml`         | TOML       | always (local creds; `[storage.buckets.*]` for bucket auto-create) |
+| `~/.supabase/access-token`               | plain text | linked path, when `SUPABASE_ACCESS_TOKEN` unset                    |
+| `~/.supabase/<hash>/linked-project.json` | JSON       | linked path, to resolve the project ref                            |
+| local Kong TLS cert/key                  | PEM        | local + `api.enabled` + `api.tls.enabled`                          |
+| upload source files                      | bytes      | upload: sniff (≤512 bytes) + streamed body                         |
 
 ## Files Written
 
-| Path    | Format | When                                |
-| ------- | ------ | ----------------------------------- |
-| `<dst>` | binary | when dst is a local filesystem path |
+| Path                                     | Format | When                                                   |
+| ---------------------------------------- | ------ | ------------------------------------------------------ |
+| download destination files               | bytes  | download (single: O_EXCL `wx`; recursive: O_TRUNC `w`) |
+| download destination parent dirs         | dir    | recursive download (`mkdir -p`)                        |
+| `~/.supabase/<hash>/linked-project.json` | JSON   | post-run, linked path                                  |
+| `~/.supabase/telemetry.json`             | JSON   | post-run (always)                                      |
 
 ## API Routes
 
-| Method | Path                                 | Auth         | Request body  | Response (used fields) |
-| ------ | ------------------------------------ | ------------ | ------------- | ---------------------- |
-| `POST` | `/storage/v1/object/{bucket}/{path}` | Bearer token | file contents | `{Key}`                |
-| `GET`  | `/storage/v1/object/{bucket}/{path}` | Bearer token | none          | file contents          |
+Auth: `apikey` always; `Authorization: Bearer <key>` unless the key is `sb_`-prefixed.
+
+| Method | Path                                      | Request body / headers                                                        | Response         |
+| ------ | ----------------------------------------- | ----------------------------------------------------------------------------- | ---------------- |
+| `GET`  | `/storage/v1/object/{path}`               | — (download)                                                                  | binary stream    |
+| `POST` | `/storage/v1/object/{path}`               | file stream; `Content-Type`, `Cache-Control`, `x-upsert` (recursive only)     | —                |
+| `POST` | `/storage/v1/object/list/{bucket}`        | `{prefix, search?, limit:100, offset?}` (recursive walk + dst detection)      | `[{name, id?}]`  |
+| `GET`  | `/storage/v1/bucket`                      | — (recursive walk to bucket root)                                             | `[{name, id}]`   |
+| `POST` | `/storage/v1/bucket`                      | `{name, public?, file_size_limit?, allowed_mime_types?}` (auto-create on 404) | `{name}`         |
+| `GET`  | `/v1/projects/{ref}/api-keys?reveal=true` | — (linked, Management API)                                                    | service-role key |
 
 ## Environment Variables
 
-| Variable                | Purpose                                              | Required?                                               |
-| ----------------------- | ---------------------------------------------------- | ------------------------------------------------------- |
-| `SUPABASE_ACCESS_TOKEN` | auth token (bypasses credential file/keyring lookup) | no (falls back to keyring → `~/.supabase/access-token`) |
-| `SUPABASE_API_URL`      | override Management API base URL                     | no (defaults to `https://api.supabase.com`)             |
+`SUPABASE_AUTH_SERVICE_ROLE_KEY`, `SUPABASE_AUTH_JWT_SECRET`, `SUPABASE_ACCESS_TOKEN`,
+`SUPABASE_PROJECT_ID`, `SUPABASE_SERVICES_HOSTNAME` — same roles as `storage ls`.
 
 ## Exit Codes
 
-| Code | Condition                             |
-| ---- | ------------------------------------- |
-| `0`  | success                               |
-| `1`  | API error (non-2xx response)          |
-| `1`  | authentication error (no token found) |
-| `1`  | source file not found                 |
-| `1`  | network / connection failure          |
+| Code | Condition                                                                                                                                                                               |
+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `0`  | success                                                                                                                                                                                 |
+| `1`  | invalid/parse url, unsupported operation (local→local), copy-between-buckets, object-not-found (recursive download), file create/read failure, API non-2xx, network, auth, config parse |
 
 ## Output
 
 ### `--output-format text` (Go CLI compatible)
 
-Prints progress and success message after object is copied.
+- Recursive download prints `Downloading: <remote> => <local>` per object (stderr).
+- Recursive upload prints `Uploading: <local> => <remote>` per file (stderr).
+- Single copies are silent (Go's `api.{Download,Upload}Object`).
+- Empty recursive download → `Object not found: <remote>`.
 
 ### `--output-format json`
 
-Not applicable (proxied to Go binary).
+```json
+{ "uploaded": [{ "from": "…", "to": "…" }], "downloaded": [{ "from": "…", "to": "…" }] }
+```
 
 ### `--output-format stream-json`
 
-Not applicable (proxied to Go binary).
+```ndjson
+{"type":"result","data":{"uploaded":[…],"downloaded":[…]}}
+```
+
+## Telemetry Events Fired
+
+| Event                  | When                                       | Notable properties                                                                            |
+| ---------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| `cli_command_executed` | post-run, success or failure (via wrapper) | `flags` (recursive/cache-control/content-type/jobs/linked/local; non-boolean values redacted) |
 
 ## Notes
 
-- Copies objects between local filesystem and Supabase Storage (or between Storage paths).
-- `--recursive` / `-r` copies directories recursively.
-- `--cache-control` sets custom Cache-Control header (default: `max-age=3600`).
-- `--content-type` sets custom Content-Type header (default: auto-detected).
-- `--jobs` / `-j` sets maximum number of parallel upload jobs.
-- `--linked` (default) connects to linked project Storage API.
-- `--local` connects to local database Storage API.
-- Phase 0 proxy: all invocations are forwarded to the bundled Go binary.
+- Single upload does NOT send `x-upsert`; recursive upload sets it (Go's `Overwrite`).
+- `--content-type` overrides the sniffed type; an explicit value is still refined when
+  it is a generic `text/plain` (Go's `ParseFileOptions` → `UploadObject`).
+- `--cache-control` defaults to `max-age=3600`; an empty value resets to that default.
+- `--jobs`/`-j` bounds upload/download concurrency (default 1).
+- DQ-1: Go help shows `--content-type` DefValue `auto-detect`; the runtime default is
+  `""` (empty ⇒ auto-detect). Effect renders the real `""` (cosmetic help diff only).
+- Relative local paths resolve against the original cwd (Go's `utils.CurrentDirAbs`).
diff --git a/apps/cli/src/legacy/commands/storage/cp/cp.command.ts b/apps/cli/src/legacy/commands/storage/cp/cp.command.ts
index a25822e711..55f2b0422d 100644
--- a/apps/cli/src/legacy/commands/storage/cp/cp.command.ts
+++ b/apps/cli/src/legacy/commands/storage/cp/cp.command.ts
@@ -1,7 +1,21 @@
+import { Effect } from "effect";
 import { Argument, Command, Flag } from "effect/unstable/cli";
 import type * as CliCommand from "effect/unstable/cli/Command";
+
+import { CliArgs } from "../../../../shared/cli/cli-args.service.ts";
+import { withJsonErrorHandling } from "../../../../shared/output/json-error-handling.ts";
+import { withLegacyCommandInstrumentation } from "../../../telemetry/legacy-command-instrumentation.ts";
+import { legacyStorageGatewayRuntimeLayer } from "../../../shared/legacy-storage-runtime.layer.ts";
+import {
+  LegacyStorageLinkedFlagDef,
+  LegacyStorageLocalFlagDef,
+  legacyAssertStorageTargetsExclusive,
+} from "../storage.flags.ts";
 import { legacyStorageCp } from "./cp.handler.ts";
 
+// `--linked`/`--local` are scoped globals on the `storage` group. Note the Go
+// help shows `--content-type` DefValue `auto-detect`, but the runtime default is
+// `""` (empty ⇒ auto-detect); Effect renders the real default (DQ-1, cosmetic).
 const config = {
   src: Argument.string("src").pipe(Argument.withDescription("Source path to copy from.")),
   dst: Argument.string("dst").pipe(Argument.withDescription("Destination path to copy to.")),
@@ -22,12 +36,8 @@ const config = {
     Flag.withDescription("Maximum number of parallel jobs."),
     Flag.optional,
   ),
-  local: Flag.boolean("local").pipe(
-    Flag.withDescription("Connects to Storage API of the local database."),
-  ),
-  linked: Flag.boolean("linked").pipe(
-    Flag.withDescription("Connects to Storage API of the linked project."),
-  ),
+  linked: LegacyStorageLinkedFlagDef,
+  local: LegacyStorageLocalFlagDef,
 } as const;
 
 export type LegacyStorageCpFlags = CliCommand.Command.Config.Infer<typeof config>;
@@ -49,5 +59,22 @@ export const legacyStorageCpCommand = Command.make("cp", config).pipe(
       description: "Download a directory from storage",
     },
   ]),
-  Command.withHandler((flags) => legacyStorageCp(flags)),
+  Command.withHandler((flags) =>
+    Effect.gen(function* () {
+      const cliArgs = yield* CliArgs;
+      yield* legacyAssertStorageTargetsExclusive(cliArgs.args);
+      const telemetryFlags = {
+        recursive: flags.recursive,
+        cacheControl: flags.cacheControl,
+        contentType: flags.contentType,
+        jobs: flags.jobs,
+        linked: flags.linked,
+        local: flags.local,
+      };
+      return yield* legacyStorageCp(flags).pipe(
+        withLegacyCommandInstrumentation({ flags: telemetryFlags }),
+      );
+    }).pipe(withJsonErrorHandling),
+  ),
+  Command.provide(legacyStorageGatewayRuntimeLayer(["storage", "cp"])),
 );
diff --git a/apps/cli/src/legacy/commands/storage/cp/cp.handler.ts b/apps/cli/src/legacy/commands/storage/cp/cp.handler.ts
index d7af5c5f2c..ed28c40fae 100644
--- a/apps/cli/src/legacy/commands/storage/cp/cp.handler.ts
+++ b/apps/cli/src/legacy/commands/storage/cp/cp.handler.ts
@@ -1,18 +1,476 @@
-import { Effect, Option } from "effect";
-import { LegacyGoProxy } from "../../../../shared/legacy/go-proxy.service.ts";
+import * as nodePath from "node:path";
+
+import type { ProjectConfig } from "@supabase/config";
+import { Effect, FileSystem, Option, Path, Stream } from "effect";
+import type { PlatformError } from "effect/PlatformError";
+
+import { LegacyCliConfig } from "../../../config/legacy-cli-config.service.ts";
+import { LegacyProjectRefResolver } from "../../../config/legacy-project-ref.service.ts";
+import { LegacyLinkedProjectCache } from "../../../telemetry/legacy-linked-project-cache.service.ts";
+import { LegacyTelemetryState } from "../../../telemetry/legacy-telemetry-state.service.ts";
+import { Output } from "../../../../shared/output/output.service.ts";
+import { RuntimeInfo } from "../../../../shared/runtime/runtime-info.service.ts";
+import {
+  legacyContentTypeForUpload,
+  legacyReadSniffBytes,
+  legacyRefineUploadContentType,
+} from "../../../shared/legacy-storage-content-type.ts";
+import {
+  legacyParseFileSizeLimit,
+  legacyResolveBucketProps,
+} from "../../../shared/legacy-storage-bucket-config.ts";
+import type { LegacyStorageGateway } from "../../../shared/legacy-storage-gateway.ts";
+import {
+  type LegacyStorageGatewayError,
+  LegacyStorageGatewayStatusError,
+} from "../../../shared/legacy-storage-gateway.errors.ts";
+import {
+  LegacyGoUrlParseError,
+  LEGACY_STORAGE_SCHEME,
+  legacyGoUrlParse,
+  legacySplitBucketPrefix,
+} from "../../../shared/legacy-storage-url.ts";
+import { legacyConnectStorageGateway, legacyLoadStorageConfig } from "../storage.frame.ts";
+import { LegacyStorageConfigError } from "../../../shared/legacy-storage-credentials.errors.ts";
+import {
+  LegacyStorageCopyBetweenBucketsError,
+  LegacyStorageFileError,
+  LegacyStorageObjectNotFoundError,
+  LegacyStorageUnsupportedOperationError,
+  LegacyStorageUrlParseError,
+} from "../storage.errors.ts";
+import { legacyIterateStoragePaths, legacyIterateStoragePathsAll } from "../storage.iterate.ts";
+import { legacyResolveUploadDstPath } from "./cp.upload.ts";
 import type { LegacyStorageCpFlags } from "./cp.command.ts";
 
+interface CpSummary {
+  readonly uploaded: Array<{ from: string; to: string }>;
+  readonly downloaded: Array<{ from: string; to: string }>;
+}
+
+/**
+ * `supabase storage cp <src> <dst>` — copy objects between local paths and the
+ * Storage service. Port of `apps/cli-go/internal/storage/cp/cp.go`. The scheme of
+ * `src`/`dst` selects the operation: `ss://`→local download, local→`ss://`
+ * upload, both `ss://` → error, both local → unsupported.
+ */
 export const legacyStorageCp = Effect.fn("legacy.storage.cp")(function* (
   flags: LegacyStorageCpFlags,
 ) {
-  const proxy = yield* LegacyGoProxy;
-  const args: string[] = ["storage", "cp"];
-  if (flags.recursive) args.push("--recursive");
-  if (flags.local) args.push("--local");
-  if (flags.linked) args.push("--linked");
-  if (Option.isSome(flags.cacheControl)) args.push("--cache-control", flags.cacheControl.value);
-  if (Option.isSome(flags.contentType)) args.push("--content-type", flags.contentType.value);
-  if (Option.isSome(flags.jobs)) args.push("--jobs", String(flags.jobs.value));
-  args.push(flags.src, flags.dst);
-  yield* proxy.exec(args);
+  const output = yield* Output;
+  const cliConfig = yield* LegacyCliConfig;
+  const telemetryState = yield* LegacyTelemetryState;
+  const linkedProjectCache = yield* LegacyLinkedProjectCache;
+  const resolver = yield* LegacyProjectRefResolver;
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const runtimeInfo = yield* RuntimeInfo;
+
+  const jobsFlag = Option.getOrElse(flags.jobs, () => 1);
+  const jobs = jobsFlag < 1 ? 1 : jobsFlag;
+  const contentTypeFlag = Option.getOrElse(flags.contentType, () => "");
+  const cacheControlRaw = Option.getOrElse(flags.cacheControl, () => "max-age=3600");
+  // Go's ParseFileOptions resets an empty Cache-Control to the storage-js default.
+  const cacheControl = cacheControlRaw.length === 0 ? "max-age=3600" : cacheControlRaw;
+
+  let linkedRef = "";
+
+  yield* Effect.gen(function* () {
+    const projectRef = flags.local ? "" : yield* resolver.loadProjectRef(Option.none());
+    linkedRef = projectRef;
+    const loaded = yield* legacyLoadStorageConfig(cliConfig.workdir, projectRef);
+    if (loaded.appliedRemote !== undefined) {
+      yield* output.raw(`Loading config override: [remotes.${loaded.appliedRemote}]\n`, "stderr");
+    }
+
+    // Parse both URLs with Go's lenient url.Parse (NOT ParseStorageURL), BEFORE
+    // building the client — an invalid url fails without an api-keys lookup.
+    const srcUrl = yield* parseCpUrl(flags.src, "src");
+    const dstUrl = yield* parseCpUrl(flags.dst, "dst");
+    const srcIsStorage = srcUrl.scheme === LEGACY_STORAGE_SCHEME;
+    const dstIsStorage = dstUrl.scheme === LEGACY_STORAGE_SCHEME;
+
+    const summary: CpSummary = { uploaded: [], downloaded: [] };
+
+    yield* legacyConnectStorageGateway(
+      { projectRef, config: loaded.config, userAgent: cliConfig.userAgent },
+      (gateway) =>
+        Effect.gen(function* () {
+          if (srcIsStorage && dstUrl.scheme === "") {
+            const localPath = absLocal(path, runtimeInfo.cwd, flags.dst);
+            if (flags.recursive) {
+              yield* downloadAll(gateway, output, fs, path, srcUrl.path, localPath, jobs, summary);
+            } else {
+              yield* downloadSingle(gateway, fs, srcUrl.path, localPath, summary);
+            }
+          } else if (srcUrl.scheme === "" && dstIsStorage) {
+            const localPath = absLocal(path, runtimeInfo.cwd, flags.src);
+            const uploadCtx = {
+              gateway,
+              output,
+              fs,
+              path,
+              contentTypeFlag,
+              cacheControl,
+              config: loaded.config,
+              document: loaded.document,
+              summary,
+            };
+            if (flags.recursive) {
+              yield* uploadAll(uploadCtx, dstUrl.path, localPath, jobs);
+            } else {
+              yield* uploadSingle(uploadCtx, dstUrl.path, localPath);
+            }
+          } else if (srcIsStorage && dstIsStorage) {
+            return yield* new LegacyStorageCopyBetweenBucketsError();
+          } else {
+            return yield* new LegacyStorageUnsupportedOperationError();
+          }
+
+          if (output.format !== "text") {
+            yield* output.success("", {
+              uploaded: summary.uploaded,
+              downloaded: summary.downloaded,
+            });
+          }
+        }),
+    );
+  }).pipe(
+    Effect.ensuring(
+      Effect.suspend(() => (linkedRef === "" ? Effect.void : linkedProjectCache.cache(linkedRef))),
+    ),
+    Effect.ensuring(telemetryState.flush),
+  );
 });
+
+const parseCpUrl = (raw: string, which: "src" | "dst") =>
+  Effect.try({
+    try: () => legacyGoUrlParse(raw),
+    catch: (cause) =>
+      new LegacyStorageUrlParseError({
+        message: `failed to parse ${which} url: ${
+          cause instanceof LegacyGoUrlParseError ? cause.message : String(cause)
+        }`,
+      }),
+  });
+
+/** Resolve a local path against the original cwd (Go's `utils.CurrentDirAbs`). */
+function absLocal(path: Path.Path, cwd: string, p: string): string {
+  return path.isAbsolute(p) ? p : path.join(cwd, p);
+}
+
+/** Write a stream chunk fully to the open file handle. */
+const writeChunk = (handle: FileSystem.File, chunk: Uint8Array) => handle.writeAll(chunk);
+
+// ---------------------------------------------------------------------------
+// Download (remote → local)
+// ---------------------------------------------------------------------------
+
+/** Go `api.DownloadObject` (`objects.go:135-142`): O_EXCL create, then stream. */
+const downloadSingle = (
+  gateway: LegacyStorageGateway,
+  fs: FileSystem.FileSystem,
+  remotePath: string,
+  localPath: string,
+  summary: CpSummary,
+) =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const handle = yield* fs.open(localPath, { flag: "wx" }).pipe(
+        Effect.mapError(
+          (cause) =>
+            new LegacyStorageFileError({
+              message: `failed to create file: ${String(cause.cause ?? cause)}`,
+            }),
+        ),
+      );
+      yield* gateway
+        .downloadObject(remotePath)
+        .pipe(Stream.runForEach((c) => writeChunk(handle, c)));
+      summary.downloaded.push({ from: remotePath, to: localPath });
+    }),
+  );
+
+/** Go `DownloadStorageObjectAll` (`cp.go:63-97`): BFS, O_TRUNC, mkdir parents. */
+const downloadAll = (
+  gateway: LegacyStorageGateway,
+  output: typeof Output.Service,
+  fs: FileSystem.FileSystem,
+  path: Path.Path,
+  remotePath: string,
+  localPath0: string,
+  jobs: number,
+  summary: CpSummary,
+) =>
+  Effect.gen(function* () {
+    // If the destination is an existing directory, nest under base(remotePath).
+    const isDir = yield* fs.stat(localPath0).pipe(
+      Effect.map((i) => i.type === "Directory"),
+      Effect.orElseSucceed(() => false),
+    );
+    const localPath = isDir
+      ? path.join(localPath0, nodePath.posix.basename(remotePath))
+      : localPath0;
+
+    const tasks: Array<{ objectPath: string; dstPath: string; isDir: boolean }> = [];
+    // Capture the iteration error as a value so the `count === 0` check can run
+    // first — Go's `count == 0 → "Object not found"` precedes the errors.Join,
+    // masking an iteration error when nothing was walked (`cp.go:93-95`).
+    const iterError = yield* legacyIterateStoragePathsAll(
+      gateway,
+      output,
+      remotePath,
+      (objectPath) =>
+        Effect.gen(function* () {
+          const relPath = objectPath.startsWith(remotePath)
+            ? objectPath.slice(remotePath.length)
+            : objectPath;
+          const dstPath = path.join(localPath, relPath);
+          yield* output.raw(`Downloading: ${objectPath} => ${dstPath}\n`, "stderr");
+          tasks.push({ objectPath, dstPath, isDir: objectPath.endsWith("/") });
+        }),
+    ).pipe(
+      Effect.as<LegacyStorageGatewayError | undefined>(undefined),
+      Effect.catch((error) => Effect.succeed(error)),
+    );
+
+    if (tasks.length === 0) {
+      return yield* new LegacyStorageObjectNotFoundError(remotePath);
+    }
+    if (iterError !== undefined) {
+      return yield* Effect.fail(iterError);
+    }
+
+    yield* Effect.forEach(
+      tasks,
+      (task) =>
+        task.isDir
+          ? makeDirIfNotExist(fs, task.dstPath)
+          : Effect.gen(function* () {
+              yield* makeDirIfNotExist(fs, path.dirname(task.dstPath));
+              yield* Effect.scoped(
+                Effect.gen(function* () {
+                  const handle = yield* fs.open(task.dstPath, { flag: "w" }).pipe(
+                    Effect.mapError(
+                      (cause) =>
+                        new LegacyStorageFileError({
+                          message: `failed to create file: ${String(cause.cause ?? cause)}`,
+                        }),
+                    ),
+                  );
+                  yield* gateway
+                    .downloadObject(task.objectPath)
+                    .pipe(Stream.runForEach((c) => writeChunk(handle, c)));
+                }),
+              );
+              summary.downloaded.push({ from: task.objectPath, to: task.dstPath });
+            }),
+      { concurrency: jobs },
+    );
+  });
+
+const makeDirIfNotExist = (fs: FileSystem.FileSystem, dir: string) =>
+  fs.makeDirectory(dir, { recursive: true }).pipe(
+    Effect.mapError(
+      (cause) =>
+        new LegacyStorageFileError({
+          message: `failed to mkdir: ${String(cause.cause ?? cause)}`,
+        }),
+    ),
+  );
+
+// ---------------------------------------------------------------------------
+// Upload (local → remote)
+// ---------------------------------------------------------------------------
+
+interface UploadCtx {
+  readonly gateway: LegacyStorageGateway;
+  readonly output: typeof Output.Service;
+  readonly fs: FileSystem.FileSystem;
+  readonly path: Path.Path;
+  readonly contentTypeFlag: string;
+  readonly cacheControl: string;
+  readonly config: ProjectConfig;
+  readonly document: Record<string, unknown> | undefined;
+  readonly summary: CpSummary;
+}
+
+const resolveContentType = (ctx: UploadCtx, filePath: string) =>
+  Effect.gen(function* () {
+    if (ctx.contentTypeFlag.length > 0) {
+      return legacyRefineUploadContentType(ctx.contentTypeFlag, filePath);
+    }
+    const sniff = yield* legacyReadSniffBytes(ctx.fs, filePath);
+    return legacyContentTypeForUpload(sniff, filePath);
+  });
+
+/** Go `api.UploadObject` single (`cp.go:55`): no x-upsert, no "Uploading:" line. */
+const uploadSingle = (ctx: UploadCtx, remoteDstPath: string, localPath: string) =>
+  Effect.gen(function* () {
+    const contentType = yield* resolveContentType(ctx, localPath);
+    yield* ctx.gateway.uploadObject(remoteDstPath, localPath, {
+      contentType,
+      cacheControl: ctx.cacheControl,
+      overwrite: false,
+    });
+    ctx.summary.uploaded.push({ from: localPath, to: remoteDstPath });
+  });
+
+/** Go `UploadStorageObjectAll` (`cp.go:99-172`): walk + dst-key + auto-create. */
+const uploadAll = (ctx: UploadCtx, remotePath: string, localPath: string, jobs: number) =>
+  Effect.gen(function* () {
+    const noSlash = remotePath.endsWith("/") ? remotePath.slice(0, -1) : remotePath;
+
+    // Detect whether base(noSlash) already exists remotely as a file or dir.
+    let dirExists = false;
+    let fileExists = false;
+    if (noSlash.length > 0) {
+      const base = nodePath.posix.basename(noSlash);
+      yield* legacyIterateStoragePaths(ctx.gateway, ctx.output, noSlash, (objectName) =>
+        Effect.sync(() => {
+          if (objectName === base) fileExists = true;
+          if (objectName === `${base}/`) dirExists = true;
+        }),
+      );
+    }
+
+    const baseName = ctx.path.basename(localPath);
+    const files = yield* collectUploadFiles(ctx.fs, ctx.path, localPath);
+
+    const tasks: Array<{ filePath: string; dstPath: string }> = [];
+    for (const file of files) {
+      const dstPath = legacyResolveUploadDstPath({
+        remotePath,
+        relPath: file.relPath,
+        fileName: ctx.path.basename(file.filePath),
+        baseName,
+        noSlash,
+        dirExists,
+        fileExists,
+      });
+      yield* ctx.output.raw(`Uploading: ${file.filePath} => ${dstPath}\n`, "stderr");
+      tasks.push({ filePath: file.filePath, dstPath });
+    }
+
+    yield* Effect.forEach(
+      tasks,
+      (task) => uploadOneWithAutoCreate(ctx, task.dstPath, task.filePath),
+      {
+        concurrency: jobs,
+      },
+    );
+  });
+
+/** One recursive upload (overwrite), retrying after bucket auto-create on 404. */
+const uploadOneWithAutoCreate = (ctx: UploadCtx, dstPath: string, filePath: string) =>
+  Effect.gen(function* () {
+    const contentType = yield* resolveContentType(ctx, filePath);
+    const upload = ctx.gateway.uploadObject(dstPath, filePath, {
+      contentType,
+      cacheControl: ctx.cacheControl,
+      overwrite: true,
+    });
+    yield* upload.pipe(
+      Effect.catch((error) =>
+        error instanceof LegacyStorageGatewayStatusError &&
+        error.body.includes('"error":"Bucket not found"')
+          ? autoCreateAndRetry(ctx, dstPath, upload, error)
+          : Effect.fail(error),
+      ),
+    );
+    ctx.summary.uploaded.push({ from: filePath, to: dstPath });
+  });
+
+const autoCreateAndRetry = (
+  ctx: UploadCtx,
+  dstPath: string,
+  retry: Effect.Effect<void, LegacyStorageGatewayError>,
+  original: LegacyStorageGatewayStatusError,
+) =>
+  Effect.gen(function* () {
+    const [bucket, prefix] = legacySplitBucketPrefix(dstPath);
+    // Go only auto-creates when a prefix follows the bucket (`cp.go:154`).
+    if (prefix.length === 0) {
+      return yield* Effect.fail(original);
+    }
+    const props = yield* bucketAutoCreateProps(ctx, bucket);
+    yield* ctx.gateway.createBucket(bucket, props);
+    yield* retry;
+  });
+
+/** Props for an auto-created bucket: from `[storage.buckets.<name>]` if present. */
+const bucketAutoCreateProps = (ctx: UploadCtx, bucket: string) =>
+  Effect.gen(function* () {
+    const bucketConfig = ctx.config.storage.buckets?.[bucket];
+    if (bucketConfig === undefined) {
+      return { public: undefined, fileSizeLimit: 0, allowedMimeTypes: [] };
+    }
+    return yield* Effect.try({
+      try: () =>
+        legacyResolveBucketProps({
+          document: ctx.document,
+          name: bucket,
+          bucket: bucketConfig,
+          storageFileSizeLimitBytes: legacyParseFileSizeLimit(ctx.config.storage.file_size_limit),
+        }),
+      catch: (cause) =>
+        new LegacyStorageConfigError({
+          message: cause instanceof Error ? cause.message : String(cause),
+        }),
+    });
+  });
+
+interface UploadFile {
+  readonly filePath: string;
+  readonly relPath: string;
+}
+
+/**
+ * Lexically-ordered regular files under `root`, mirroring `afero.Walk` +
+ * `info.Mode().IsRegular()` (`cp.go:124-130`): directories are descended,
+ * symlinks and other non-regular files are skipped. A single-file root yields one
+ * entry with `relPath === "."` (Go's `filepath.Rel(localPath, localPath)`).
+ */
+const collectUploadFiles = (
+  fs: FileSystem.FileSystem,
+  path: Path.Path,
+  root: string,
+): Effect.Effect<ReadonlyArray<UploadFile>, PlatformError> =>
+  Effect.gen(function* () {
+    const info = yield* fs.stat(root);
+    if (info.type === "File") {
+      return [{ filePath: root, relPath: "." }];
+    }
+    if (info.type === "Directory") {
+      const out: Array<UploadFile> = [];
+      yield* walkUploadDir(fs, path, root, root, out);
+      return out;
+    }
+    return [];
+  });
+
+const walkUploadDir = (
+  fs: FileSystem.FileSystem,
+  path: Path.Path,
+  root: string,
+  dir: string,
+  out: Array<UploadFile>,
+): Effect.Effect<void, PlatformError> =>
+  Effect.gen(function* () {
+    const names = [...(yield* fs.readDirectory(dir))].sort();
+    for (const name of names) {
+      const abs = path.join(dir, name);
+      // afero.Walk uses Lstat (no-follow); a symlink is not regular → skipped.
+      const isSymlink = yield* fs.readLink(abs).pipe(
+        Effect.as(true),
+        Effect.catch(() => Effect.succeed(false)),
+      );
+      if (isSymlink) continue;
+      const info = yield* fs.stat(abs);
+      if (info.type === "Directory") {
+        yield* walkUploadDir(fs, path, root, abs, out);
+      } else if (info.type === "File") {
+        out.push({ filePath: abs, relPath: path.relative(root, abs) });
+      }
+    }
+  });
diff --git a/apps/cli/src/legacy/commands/storage/cp/cp.integration.test.ts b/apps/cli/src/legacy/commands/storage/cp/cp.integration.test.ts
new file mode 100644
index 0000000000..1037474da4
--- /dev/null
+++ b/apps/cli/src/legacy/commands/storage/cp/cp.integration.test.ts
@@ -0,0 +1,393 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, Exit, Option } from "effect";
+
+import { setupLegacyStorage } from "../../../../../tests/helpers/legacy-storage.ts";
+import { useLegacyTempWorkdir } from "../../../../../tests/helpers/legacy-mocks.ts";
+import { legacyStorageCp } from "./cp.handler.ts";
+import type { LegacyStorageCpFlags } from "./cp.command.ts";
+
+const BUCKET = "/storage/v1/bucket";
+const OBJECT = (p: string) => `/storage/v1/object/${p}`;
+const LIST = (bucket: string) => `/storage/v1/object/list/${bucket}`;
+
+function cpFlags(opts: {
+  src: string;
+  dst: string;
+  recursive?: boolean;
+  cacheControl?: string;
+  contentType?: string;
+  jobs?: number;
+  local?: boolean;
+}): LegacyStorageCpFlags {
+  return {
+    src: opts.src,
+    dst: opts.dst,
+    recursive: opts.recursive ?? false,
+    cacheControl: opts.cacheControl === undefined ? Option.none() : Option.some(opts.cacheControl),
+    contentType: opts.contentType === undefined ? Option.none() : Option.some(opts.contentType),
+    jobs: opts.jobs === undefined ? Option.none() : Option.some(opts.jobs),
+    linked: true,
+    local: opts.local ?? true,
+  };
+}
+
+function prefixOf(body: unknown): string {
+  return typeof body === "object" &&
+    body !== null &&
+    typeof (body as { prefix?: unknown }).prefix === "string"
+    ? (body as { prefix: string }).prefix
+    : "";
+}
+
+describe("legacy storage cp", () => {
+  const tmp = useLegacyTempWorkdir("supabase-storage-cp-");
+
+  it.live("uploads a single local file without x-upsert (sniffed content-type)", () => {
+    writeFileSync(join(tmp.current, "readme.md"), "hello world");
+    const { layer, requests } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      routes: [{ method: "POST", match: OBJECT("private/readme.md"), body: {} }],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageCp(
+        cpFlags({ src: join(tmp.current, "readme.md"), dst: "ss:///private/readme.md" }),
+      ).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      const upload = requests.find((r) => r.url.includes(OBJECT("private/readme.md")));
+      expect(upload?.method).toBe("POST");
+      // Single upload does NOT set x-upsert (Go's Overwrite stays false).
+      expect(upload?.headers["x-upsert"]).toBeUndefined();
+      expect(upload?.headers["cache-control"]).toBe("max-age=3600");
+      expect(upload?.headers["content-type"]).toContain("text/plain");
+    });
+  });
+
+  it.live("honors --content-type and --cache-control on upload", () => {
+    writeFileSync(join(tmp.current, "data.bin"), "hello");
+    const { layer, requests } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      routes: [{ method: "POST", match: OBJECT("private/data.bin"), body: {} }],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageCp(
+        cpFlags({
+          src: join(tmp.current, "data.bin"),
+          dst: "ss:///private/data.bin",
+          contentType: "application/custom",
+          cacheControl: "max-age=60",
+        }),
+      ).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      const upload = requests.find((r) => r.url.includes(OBJECT("private/data.bin")));
+      expect(upload?.headers["content-type"]).toBe("application/custom");
+      expect(upload?.headers["cache-control"]).toBe("max-age=60");
+    });
+  });
+
+  it.live("recursively uploads a directory, auto-creating a missing bucket", () => {
+    mkdirSync(join(tmp.current, "upload"), { recursive: true });
+    writeFileSync(join(tmp.current, "upload", "readme.md"), "hello");
+    const { layer, requests } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      routes: [
+        // first upload → bucket missing
+        {
+          method: "POST",
+          match: OBJECT("upload/readme.md"),
+          status: 400,
+          body: { error: "Bucket not found" },
+        },
+        // create the bucket
+        { method: "POST", match: "/storage/v1/bucket", body: { name: "upload" } },
+        // retry upload
+        { method: "POST", match: OBJECT("upload/readme.md"), body: {} },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageCp(
+        cpFlags({ src: join(tmp.current, "upload"), dst: "ss://", recursive: true }),
+      ).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      // Recursive uploads set x-upsert; bucket auto-created then upload retried.
+      const uploads = requests.filter((r) => r.url.includes(OBJECT("upload/readme.md")));
+      expect(uploads).toHaveLength(2);
+      expect(uploads[1]?.headers["x-upsert"]).toBe("true");
+      expect(
+        requests.some((r) => r.method === "POST" && r.url.endsWith("/storage/v1/bucket")),
+      ).toBe(true);
+    });
+  });
+
+  it.live("downloads a single object to a new local file (O_EXCL)", () => {
+    const dst = join(tmp.current, "out.md");
+    const { layer } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      routes: [{ method: "GET", match: OBJECT("private/readme.md"), rawBody: "downloaded-bytes" }],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageCp(cpFlags({ src: "ss:///private/readme.md", dst })).pipe(
+        Effect.provide(layer),
+        Effect.exit,
+      );
+      expect(Exit.isSuccess(exit)).toBe(true);
+      expect(readFileSync(dst, "utf8")).toBe("downloaded-bytes");
+    });
+  });
+
+  it.live("fails to overwrite an existing file on single download (O_EXCL)", () => {
+    const dst = join(tmp.current, "exists.md");
+    writeFileSync(dst, "original");
+    const { layer } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      routes: [{ method: "GET", match: OBJECT("private/readme.md"), rawBody: "new" }],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageCp(cpFlags({ src: "ss:///private/readme.md", dst })).pipe(
+        Effect.provide(layer),
+        Effect.exit,
+      );
+      expect(Exit.isFailure(exit)).toBe(true);
+      expect(JSON.stringify(exit)).toContain("failed to create file");
+      // The existing file is untouched.
+      expect(readFileSync(dst, "utf8")).toBe("original");
+    });
+  });
+
+  it.live("recursively downloads nested objects, creating parent dirs", () => {
+    const dst = join(tmp.current, "dl");
+    const { layer } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      routes: [
+        {
+          method: "POST",
+          match: LIST("private"),
+          when: (b) => prefixOf(b) === "",
+          body: [
+            { name: "folder", id: null },
+            { name: "a.txt", id: "ai" },
+          ],
+        },
+        {
+          method: "POST",
+          match: LIST("private"),
+          when: (b) => prefixOf(b) === "folder/",
+          body: [{ name: "b.txt", id: "bi" }],
+        },
+        { method: "GET", match: OBJECT("private/a.txt"), rawBody: "a-content" },
+        { method: "GET", match: OBJECT("private/folder/b.txt"), rawBody: "b-content" },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageCp(
+        cpFlags({ src: "ss:///private/", dst, recursive: true }),
+      ).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      expect(readFileSync(join(dst, "a.txt"), "utf8")).toBe("a-content");
+      expect(readFileSync(join(dst, "folder", "b.txt"), "utf8")).toBe("b-content");
+    });
+  });
+
+  it.live("recursively downloads into an existing directory (nests under the remote base)", () => {
+    const dst = join(tmp.current, "existing");
+    mkdirSync(dst, { recursive: true });
+    const { layer } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      routes: [
+        { method: "POST", match: LIST("private"), body: [{ name: "a.txt", id: "ai" }] },
+        { method: "GET", match: OBJECT("private/a.txt"), rawBody: "a" },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageCp(
+        cpFlags({ src: "ss:///private/", dst, recursive: true }),
+      ).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      // Existing dir → nest under base("/private/") = "private".
+      expect(readFileSync(join(dst, "private", "a.txt"), "utf8")).toBe("a");
+    });
+  });
+
+  it.live("creates a directory for an empty bucket on recursive download", () => {
+    const dst = join(tmp.current, "dl-empty");
+    const { layer } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      routes: [
+        { method: "GET", match: BUCKET, body: [{ name: "empty", id: "empty" }] },
+        { method: "POST", match: LIST("empty"), body: [] },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageCp(cpFlags({ src: "ss:///", dst, recursive: true })).pipe(
+        Effect.provide(layer),
+        Effect.exit,
+      );
+      expect(Exit.isSuccess(exit)).toBe(true);
+      // Empty bucket reported as "empty/" → mkdir under the destination.
+      expect(existsSync(join(dst, "empty"))).toBe(true);
+    });
+  });
+
+  it.live("recursively uploads a nested subdirectory", () => {
+    mkdirSync(join(tmp.current, "tree", "sub"), { recursive: true });
+    writeFileSync(join(tmp.current, "tree", "top.txt"), "t");
+    writeFileSync(join(tmp.current, "tree", "sub", "nested.txt"), "n");
+    const { layer, requests } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      routes: [
+        { method: "POST", match: LIST("private"), body: [{ name: "dir", id: null }] },
+        { method: "POST", match: OBJECT("private/dir/tree/top.txt"), body: {} },
+        { method: "POST", match: OBJECT("private/dir/tree/sub/nested.txt"), body: {} },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageCp(
+        cpFlags({ src: join(tmp.current, "tree"), dst: "ss:///private/dir/", recursive: true }),
+      ).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      expect(requests.some((r) => r.url.includes(OBJECT("private/dir/tree/sub/nested.txt")))).toBe(
+        true,
+      );
+    });
+  });
+
+  it.live("auto-creates a bucket using its config from supabase/config.toml", () => {
+    mkdirSync(join(tmp.current, "media"), { recursive: true });
+    writeFileSync(join(tmp.current, "media", "a.png"), "x");
+    const { layer, requests } = setupLegacyStorage(tmp.current, {
+      toml: "[storage.buckets.media]\npublic = true\n",
+      local: true,
+      routes: [
+        {
+          method: "POST",
+          match: OBJECT("media/a.png"),
+          status: 400,
+          body: { error: "Bucket not found" },
+        },
+        { method: "POST", match: "/storage/v1/bucket", body: { name: "media" } },
+        { method: "POST", match: OBJECT("media/a.png"), body: {} },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageCp(
+        cpFlags({ src: join(tmp.current, "media"), dst: "ss://", recursive: true }),
+      ).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      const create = requests.find(
+        (r) => r.method === "POST" && r.url.endsWith("/storage/v1/bucket"),
+      );
+      // The bucket is created with its configured `public` property.
+      const createBody = create?.body as { public?: boolean } | undefined;
+      expect(createBody?.public).toBe(true);
+    });
+  });
+
+  it.live("fails with Object not found when a recursive download is empty", () => {
+    const { layer } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      routes: [{ method: "POST", match: LIST("private"), body: [] }],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageCp(
+        cpFlags({ src: "ss:///private/empty/", dst: join(tmp.current, "dl"), recursive: true }),
+      ).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isFailure(exit)).toBe(true);
+      expect(JSON.stringify(exit)).toContain("Object not found: /private/empty/");
+    });
+  });
+
+  it.live("rejects copying between buckets", () => {
+    const { layer } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageCp(cpFlags({ src: "ss:///a/x", dst: "ss:///b/y" })).pipe(
+        Effect.provide(layer),
+        Effect.exit,
+      );
+      expect(Exit.isFailure(exit)).toBe(true);
+      expect(JSON.stringify(exit)).toContain("Copying between buckets is not supported");
+    });
+  });
+
+  it.live("rejects a local-to-local copy with a cp -r suggestion", () => {
+    const { layer } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageCp(cpFlags({ src: "./a", dst: "./b" })).pipe(
+        Effect.provide(layer),
+        Effect.exit,
+      );
+      expect(Exit.isFailure(exit)).toBe(true);
+      const json = JSON.stringify(exit);
+      expect(json).toContain("Unsupported operation");
+      expect(json).toContain("to copy between local directories");
+    });
+  });
+
+  it.live("fails on an invalid src url without any network call", () => {
+    const { layer, requests } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageCp(cpFlags({ src: ":", dst: "." })).pipe(
+        Effect.provide(layer),
+        Effect.exit,
+      );
+      expect(Exit.isFailure(exit)).toBe(true);
+      const json = JSON.stringify(exit);
+      expect(json).toContain("failed to parse src url");
+      expect(json).toContain("missing protocol scheme");
+      expect(requests).toHaveLength(0);
+    });
+  });
+
+  it.live("fails when the recursive upload source is missing", () => {
+    const { layer } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageCp(
+        cpFlags({ src: join(tmp.current, "missing"), dst: "ss:///private", recursive: true }),
+      ).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isFailure(exit)).toBe(true);
+    });
+  });
+
+  it.live("emits an { uploaded, downloaded } result in json mode", () => {
+    writeFileSync(join(tmp.current, "readme.md"), "hello");
+    const { layer, out } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      format: "json",
+      routes: [{ method: "POST", match: OBJECT("private/readme.md"), body: {} }],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageCp(
+        cpFlags({ src: join(tmp.current, "readme.md"), dst: "ss:///private/readme.md" }),
+      ).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      const success = out.messages.find((m) => m.type === "success");
+      const uploaded = success?.data?.["uploaded"] as Array<{ to: string }>;
+      expect(uploaded?.[0]?.to).toBe("/private/readme.md");
+      expect(existsSync(join(tmp.current, "readme.md"))).toBe(true);
+    });
+  });
+});
diff --git a/apps/cli/src/legacy/commands/storage/cp/cp.upload.ts b/apps/cli/src/legacy/commands/storage/cp/cp.upload.ts
new file mode 100644
index 0000000000..10fc6fae89
--- /dev/null
+++ b/apps/cli/src/legacy/commands/storage/cp/cp.upload.ts
@@ -0,0 +1,53 @@
+import * as nodePath from "node:path";
+
+import { legacySplitBucketPrefix, legacyStorageIsDir } from "../../../shared/legacy-storage-url.ts";
+
+/**
+ * Pure destination-key resolution for `storage cp` recursive uploads, ported from
+ * Go's `UploadStorageObjectAll` walk callback (`internal/storage/cp/cp.go:124-148`).
+ * Kept free of Effect/services so the Go-parity branch matrix stays unit-testable.
+ */
+
+export interface LegacyUploadDstPathInput {
+  /** The destination object path (`dstParsed.Path`, e.g. `/private/dir/`). */
+  readonly remotePath: string;
+  /** `filepath.Rel(localPath, filePath)` — `"."` when `localPath` is the file itself. */
+  readonly relPath: string;
+  /** Base name of the current file (`info.Name()`), used in the single-file branch. */
+  readonly fileName: string;
+  /** Base name of the walk root (`filepath.Base(localPath)`). */
+  readonly baseName: string;
+  /** `strings.TrimSuffix(remotePath, "/")`. */
+  readonly noSlash: string;
+  /** Whether `base(noSlash)` exists as a directory at the destination. */
+  readonly dirExists: boolean;
+  /** Whether `base(noSlash)` exists as a file at the destination. */
+  readonly fileExists: boolean;
+}
+
+/**
+ * Resolve the remote destination key for one walked file (`cp.go:135-148`):
+ *  - single file (`relPath === "."`): append the file name only when the
+ *    destination prefix is itself a directory, or the destination dir exists and
+ *    no same-named file does;
+ *  - otherwise: nest under `baseName` when the destination dir exists (or the
+ *    destination is a bare bucket), then append the relative path.
+ *
+ * Remote keys are joined with POSIX semantics (Go uses `path.Join`); the relative
+ * segment's OS separators are normalised to `/`.
+ */
+export function legacyResolveUploadDstPath(input: LegacyUploadDstPathInput): string {
+  let dstPath = input.remotePath;
+  if (input.relPath === ".") {
+    const [, prefix] = legacySplitBucketPrefix(dstPath);
+    if (legacyStorageIsDir(prefix) || (input.dirExists && !input.fileExists)) {
+      dstPath = nodePath.posix.join(dstPath, input.fileName);
+    }
+    return dstPath;
+  }
+  if (input.baseName !== "." && (input.dirExists || input.noSlash.length === 0)) {
+    dstPath = nodePath.posix.join(dstPath, input.baseName);
+  }
+  const relPosix = input.relPath.split(nodePath.sep).join(nodePath.posix.sep);
+  return nodePath.posix.join(dstPath, relPosix);
+}
diff --git a/apps/cli/src/legacy/commands/storage/cp/cp.upload.unit.test.ts b/apps/cli/src/legacy/commands/storage/cp/cp.upload.unit.test.ts
new file mode 100644
index 0000000000..558b989b72
--- /dev/null
+++ b/apps/cli/src/legacy/commands/storage/cp/cp.upload.unit.test.ts
@@ -0,0 +1,110 @@
+import { describe, expect, it } from "vitest";
+
+import { legacyResolveUploadDstPath } from "./cp.upload.ts";
+
+// Oracle: apps/cli-go/internal/storage/cp/cp.go:135-148 + cp_test.go TestUploadAll.
+describe("legacyResolveUploadDstPath", () => {
+  describe("single file (relPath === '.')", () => {
+    it("appends the file name when the dst prefix is a bucket root", () => {
+      // remote "private" → prefix "" is a directory → keep the file name.
+      expect(
+        legacyResolveUploadDstPath({
+          remotePath: "private",
+          relPath: ".",
+          fileName: "readme.md",
+          baseName: "readme.md",
+          noSlash: "private",
+          dirExists: true,
+          fileExists: false,
+        }),
+      ).toBe("private/readme.md");
+    });
+
+    it("keeps the destination key when it targets an existing object", () => {
+      // remote "private/file" → prefix "file" is not a dir, and the object exists.
+      expect(
+        legacyResolveUploadDstPath({
+          remotePath: "private/file",
+          relPath: ".",
+          fileName: "readme.md",
+          baseName: "readme.md",
+          noSlash: "private/file",
+          dirExists: false,
+          fileExists: true,
+        }),
+      ).toBe("private/file");
+    });
+
+    it("appends the file name when the dst dir exists and no same-named file does", () => {
+      expect(
+        legacyResolveUploadDstPath({
+          remotePath: "private/docs",
+          relPath: ".",
+          fileName: "readme.md",
+          baseName: "readme.md",
+          noSlash: "private/docs",
+          dirExists: true,
+          fileExists: false,
+        }),
+      ).toBe("private/docs/readme.md");
+    });
+  });
+
+  describe("directory walk", () => {
+    it("nests under baseName for a new bucket (noSlash empty)", () => {
+      expect(
+        legacyResolveUploadDstPath({
+          remotePath: "",
+          relPath: "readme.md",
+          fileName: "readme.md",
+          baseName: "tmp",
+          noSlash: "",
+          dirExists: false,
+          fileExists: false,
+        }),
+      ).toBe("tmp/readme.md");
+    });
+
+    it("nests under baseName when the destination dir exists", () => {
+      expect(
+        legacyResolveUploadDstPath({
+          remotePath: "/private/dir/",
+          relPath: "readme.md",
+          fileName: "readme.md",
+          baseName: "tmp",
+          noSlash: "/private/dir",
+          dirExists: true,
+          fileExists: false,
+        }),
+      ).toBe("/private/dir/tmp/readme.md");
+    });
+
+    it("preserves a nested relative path under baseName", () => {
+      expect(
+        legacyResolveUploadDstPath({
+          remotePath: "/private/dir/",
+          relPath: "docs/api.md",
+          fileName: "api.md",
+          baseName: "tmp",
+          noSlash: "/private/dir",
+          dirExists: true,
+          fileExists: false,
+        }),
+      ).toBe("/private/dir/tmp/docs/api.md");
+    });
+
+    it("does not nest under baseName when it is '.' (cwd source)", () => {
+      expect(
+        legacyResolveUploadDstPath({
+          remotePath: "/private",
+          relPath: "readme.md",
+          fileName: "readme.md",
+          baseName: ".",
+          noSlash: "/private",
+          dirExists: true,
+          fileExists: false,
+        }),
+      ).toBe("/private/readme.md");
+    });
+  });
+});
diff --git a/apps/cli/src/legacy/commands/storage/ls/SIDE_EFFECTS.md b/apps/cli/src/legacy/commands/storage/ls/SIDE_EFFECTS.md
index 13ae89b088..12a90b25ef 100644
--- a/apps/cli/src/legacy/commands/storage/ls/SIDE_EFFECTS.md
+++ b/apps/cli/src/legacy/commands/storage/ls/SIDE_EFFECTS.md
@@ -1,57 +1,86 @@
 # `supabase storage ls [path]`
 
+Native TypeScript port of `apps/cli-go/internal/storage/ls`. Lists objects/buckets
+by path prefix against the Storage gateway (local stack or linked project).
+
 ## Files Read
 
-| Path                       | Format     | When                                                       |
-| -------------------------- | ---------- | ---------------------------------------------------------- |
-| `~/.supabase/access-token` | plain text | when `SUPABASE_ACCESS_TOKEN` unset and keyring unavailable |
+| Path                                     | Format     | When                                                          |
+| ---------------------------------------- | ---------- | ------------------------------------------------------------- |
+| `<workdir>/supabase/config.toml`         | TOML       | always (local creds/baseUrl; `[remotes.*]` merge when linked) |
+| `~/.supabase/access-token`               | plain text | linked path, when `SUPABASE_ACCESS_TOKEN` unset               |
+| `~/.supabase/<hash>/linked-project.json` | JSON       | linked path, to resolve the project ref                       |
+| local Kong TLS cert/key                  | PEM        | local + `api.enabled` + `api.tls.enabled`                     |
 
 ## Files Written
 
-| Path | Format | When |
-| ---- | ------ | ---- |
-| —    | —      | —    |
+| Path                                     | Format | When                              |
+| ---------------------------------------- | ------ | --------------------------------- |
+| `~/.supabase/<hash>/linked-project.json` | JSON   | post-run, linked path (ref cache) |
+| `~/.supabase/telemetry.json`             | JSON   | post-run (always)                 |
 
 ## API Routes
 
-| Method | Path                               | Auth         | Request body | Response (used fields) |
-| ------ | ---------------------------------- | ------------ | ------------ | ---------------------- |
-| `POST` | `/storage/v1/object/list/{bucket}` | Bearer token | path filter  | `[{name, id, ...}]`    |
+Auth: `apikey` header always; `Authorization: Bearer <key>` unless the key is `sb_`-prefixed.
+
+| Method | Path                                      | Request body                            | Response (used)                 |
+| ------ | ----------------------------------------- | --------------------------------------- | ------------------------------- |
+| `POST` | `/storage/v1/object/list/{bucket}`        | `{prefix, search?, limit:100, offset?}` | `[{name, id?}]` (id null ⇒ dir) |
+| `GET`  | `/storage/v1/bucket`                      | —                                       | `[{name, id}]`                  |
+| `GET`  | `/v1/projects/{ref}/api-keys?reveal=true` | — (linked, Management API)              | api-key list → service-role key |
 
 ## Environment Variables
 
-| Variable                | Purpose                                              | Required?                                               |
-| ----------------------- | ---------------------------------------------------- | ------------------------------------------------------- |
-| `SUPABASE_ACCESS_TOKEN` | auth token (bypasses credential file/keyring lookup) | no (falls back to keyring → `~/.supabase/access-token`) |
-| `SUPABASE_API_URL`      | override Management API base URL                     | no (defaults to `https://api.supabase.com`)             |
+| Variable                         | Purpose                                              | Required?                          |
+| -------------------------------- | ---------------------------------------------------- | ---------------------------------- |
+| `SUPABASE_AUTH_SERVICE_ROLE_KEY` | linked: bypass tenant key fetch; local: explicit key | no                                 |
+| `SUPABASE_AUTH_JWT_SECRET`       | local: derive service-role key                       | no (→ `auth.jwt_secret` → default) |
+| `SUPABASE_ACCESS_TOKEN`          | linked: Management API auth                          | no (→ `~/.supabase/access-token`)  |
+| `SUPABASE_PROJECT_ID`            | linked: project-ref resolution                       | no                                 |
+| `SUPABASE_SERVICES_HOSTNAME`     | local baseUrl host                                   | no (→ Docker host → `127.0.0.1`)   |
 
 ## Exit Codes
 
-| Code | Condition                             |
-| ---- | ------------------------------------- |
-| `0`  | success                               |
-| `1`  | API error (non-2xx response)          |
-| `1`  | authentication error (no token found) |
-| `1`  | invalid path                          |
+| Code | Condition                                                                   |
+| ---- | --------------------------------------------------------------------------- |
+| `0`  | success                                                                     |
+| `1`  | invalid URL / url-parse error / API non-2xx / network / auth / config parse |
 
 ## Output
 
 ### `--output-format text` (Go CLI compatible)
 
-Prints a list of object names under the given path prefix.
+One entry per line to **stdout** (`fmt.Println`); directory entries get a trailing `/`.
+Pagination prints `Loading page: <N>` to **stderr**.
 
 ### `--output-format json`
 
-Not applicable (proxied to Go binary).
+```json
+{ "paths": ["bucket/", "bucket/folder/file.png"] }
+```
 
 ### `--output-format stream-json`
 
-Not applicable (proxied to Go binary).
+```ndjson
+{"type":"result","data":{"paths":["bucket/","bucket/folder/file.png"]}}
+```
+
+## Telemetry Events Fired
+
+| Event                  | When                                       | Notable properties               |
+| ---------------------- | ------------------------------------------ | -------------------------------- |
+| `cli_command_executed` | post-run, success or failure (via wrapper) | `flags` (recursive/linked/local) |
+
+No custom storage telemetry events (verified against `internal/storage/ls`).
 
 ## Notes
 
-- Default path is `ss:///` (all buckets root).
-- `--recursive` / `-r` lists objects recursively.
-- `--linked` (default) connects to linked project Storage API.
-- `--local` connects to local database Storage API.
-- Phase 0 proxy: all invocations are forwarded to the bundled Go binary.
+- Default path is `ss:///` (all buckets root) → remotePath `/`; recursive file paths
+  then carry a leading slash, while an empty bucket is reported bare as `<bucket>/`.
+- `--recursive`/`-r` walks the tree (BFS).
+- `--local` / `--linked` are mutually exclusive; `--local` routes to the local stack,
+  otherwise the linked project is used. They are declared **per-leaf** (not as
+  `storage`-group scoped globals) because Effect CLI requires global-flag names to be
+  unique tree-wide and `seed` already owns `linked`/`local`; the only behavioural cost
+  vs Go's persistent flags is that they must follow the subcommand token
+  (`storage ls --local`, not `storage --local ls`) — the same shape the `db` family uses.
diff --git a/apps/cli/src/legacy/commands/storage/ls/ls.command.ts b/apps/cli/src/legacy/commands/storage/ls/ls.command.ts
index ca6ea11197..e0ff127311 100644
--- a/apps/cli/src/legacy/commands/storage/ls/ls.command.ts
+++ b/apps/cli/src/legacy/commands/storage/ls/ls.command.ts
@@ -1,5 +1,16 @@
+import { Effect } from "effect";
 import { Argument, Command, Flag } from "effect/unstable/cli";
 import type * as CliCommand from "effect/unstable/cli/Command";
+
+import { CliArgs } from "../../../../shared/cli/cli-args.service.ts";
+import { withJsonErrorHandling } from "../../../../shared/output/json-error-handling.ts";
+import { withLegacyCommandInstrumentation } from "../../../telemetry/legacy-command-instrumentation.ts";
+import { legacyStorageGatewayRuntimeLayer } from "../../../shared/legacy-storage-runtime.layer.ts";
+import {
+  LegacyStorageLinkedFlagDef,
+  LegacyStorageLocalFlagDef,
+  legacyAssertStorageTargetsExclusive,
+} from "../storage.flags.ts";
 import { legacyStorageLs } from "./ls.handler.ts";
 
 const config = {
@@ -11,12 +22,8 @@ const config = {
     Flag.withAlias("r"),
     Flag.withDescription("Recursively list a directory."),
   ),
-  local: Flag.boolean("local").pipe(
-    Flag.withDescription("Connects to Storage API of the local database."),
-  ),
-  linked: Flag.boolean("linked").pipe(
-    Flag.withDescription("Connects to Storage API of the linked project."),
-  ),
+  linked: LegacyStorageLinkedFlagDef,
+  local: LegacyStorageLocalFlagDef,
 } as const;
 
 export type LegacyStorageLsFlags = CliCommand.Command.Config.Infer<typeof config>;
@@ -30,5 +37,22 @@ export const legacyStorageLsCommand = Command.make("ls", config).pipe(
       description: "List objects at a storage path",
     },
   ]),
-  Command.withHandler((flags) => legacyStorageLs(flags)),
+  Command.withHandler((flags) =>
+    Effect.gen(function* () {
+      // Enforce --linked/--local mutual exclusivity BEFORE instrumentation, so a
+      // flag-validation rejection doesn't emit `cli_command_executed` (Go rejects
+      // it at cobra flag validation, before RunE/PostRun).
+      const cliArgs = yield* CliArgs;
+      yield* legacyAssertStorageTargetsExclusive(cliArgs.args);
+      const telemetryFlags = {
+        recursive: flags.recursive,
+        linked: flags.linked,
+        local: flags.local,
+      };
+      return yield* legacyStorageLs(flags).pipe(
+        withLegacyCommandInstrumentation({ flags: telemetryFlags }),
+      );
+    }).pipe(withJsonErrorHandling),
+  ),
+  Command.provide(legacyStorageGatewayRuntimeLayer(["storage", "ls"])),
 );
diff --git a/apps/cli/src/legacy/commands/storage/ls/ls.handler.ts b/apps/cli/src/legacy/commands/storage/ls/ls.handler.ts
index bb169205e4..4152f6bee9 100644
--- a/apps/cli/src/legacy/commands/storage/ls/ls.handler.ts
+++ b/apps/cli/src/legacy/commands/storage/ls/ls.handler.ts
@@ -1,15 +1,80 @@
 import { Effect, Option } from "effect";
-import { LegacyGoProxy } from "../../../../shared/legacy/go-proxy.service.ts";
+
+import { LegacyCliConfig } from "../../../config/legacy-cli-config.service.ts";
+import { LegacyProjectRefResolver } from "../../../config/legacy-project-ref.service.ts";
+import { LegacyLinkedProjectCache } from "../../../telemetry/legacy-linked-project-cache.service.ts";
+import { LegacyTelemetryState } from "../../../telemetry/legacy-telemetry-state.service.ts";
+import { Output } from "../../../../shared/output/output.service.ts";
+import { legacyIterateStoragePaths, legacyIterateStoragePathsAll } from "../storage.iterate.ts";
+import {
+  legacyConnectStorageGateway,
+  legacyLoadStorageConfig,
+  legacyParseStorageUrlEffect,
+} from "../storage.frame.ts";
 import type { LegacyStorageLsFlags } from "./ls.command.ts";
 
+/**
+ * `supabase storage ls [path]` — list objects by path prefix.
+ *
+ * Port of `apps/cli-go/internal/storage/ls/ls.go`. The default path is `ss:///`
+ * (all buckets); `--recursive` walks the tree with BFS. Text mode prints one
+ * entry per line to **stdout** (Go `fmt.Println`); json/stream-json emit a single
+ * `{ paths }` result.
+ */
 export const legacyStorageLs = Effect.fn("legacy.storage.ls")(function* (
   flags: LegacyStorageLsFlags,
 ) {
-  const proxy = yield* LegacyGoProxy;
-  const args: string[] = ["storage", "ls"];
-  if (flags.recursive) args.push("--recursive");
-  if (flags.local) args.push("--local");
-  if (flags.linked) args.push("--linked");
-  if (Option.isSome(flags.path)) args.push(flags.path.value);
-  yield* proxy.exec(args);
+  const output = yield* Output;
+  const cliConfig = yield* LegacyCliConfig;
+  const telemetryState = yield* LegacyTelemetryState;
+  const linkedProjectCache = yield* LegacyLinkedProjectCache;
+  const resolver = yield* LegacyProjectRefResolver;
+
+  let linkedRef = "";
+
+  yield* Effect.gen(function* () {
+    // Routing reads the `--local` value (Go `storage.go:21-32`): local clears the
+    // ref, otherwise the linked path resolves it. No network — safe before the
+    // url parse below.
+    const projectRef = flags.local ? "" : yield* resolver.loadProjectRef(Option.none());
+    linkedRef = projectRef;
+
+    // Config is always loaded (Go's `utils.Config`); a `[remotes.*]` match prints
+    // the override line.
+    const loaded = yield* legacyLoadStorageConfig(cliConfig.workdir, projectRef);
+    if (loaded.appliedRemote !== undefined) {
+      yield* output.raw(`Loading config override: [remotes.${loaded.appliedRemote}]\n`, "stderr");
+    }
+
+    // Parse the URL BEFORE building the client (Go `ls.go:17`), so an invalid URL
+    // fails without an api-keys lookup or any Storage call.
+    const remotePath = yield* legacyParseStorageUrlEffect(
+      Option.getOrElse(flags.path, () => "ss:///"),
+    );
+
+    const paths: Array<string> = [];
+    const callback = (objectPath: string) =>
+      output.format === "text"
+        ? output.raw(`${objectPath}\n`, "stdout")
+        : Effect.sync(() => {
+            paths.push(objectPath);
+          });
+
+    yield* legacyConnectStorageGateway(
+      { projectRef, config: loaded.config, userAgent: cliConfig.userAgent },
+      (gateway) =>
+        flags.recursive
+          ? legacyIterateStoragePathsAll(gateway, output, remotePath, callback)
+          : legacyIterateStoragePaths(gateway, output, remotePath, callback),
+    );
+
+    if (output.format !== "text") {
+      yield* output.success("", { paths });
+    }
+  }).pipe(
+    Effect.ensuring(
+      Effect.suspend(() => (linkedRef === "" ? Effect.void : linkedProjectCache.cache(linkedRef))),
+    ),
+    Effect.ensuring(telemetryState.flush),
+  );
 });
diff --git a/apps/cli/src/legacy/commands/storage/ls/ls.integration.test.ts b/apps/cli/src/legacy/commands/storage/ls/ls.integration.test.ts
new file mode 100644
index 0000000000..b27d5ac756
--- /dev/null
+++ b/apps/cli/src/legacy/commands/storage/ls/ls.integration.test.ts
@@ -0,0 +1,273 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, Exit, Option } from "effect";
+
+import { LEGACY_VALID_REF } from "../../../../../tests/helpers/legacy-mocks.ts";
+import { setupLegacyStorage } from "../../../../../tests/helpers/legacy-storage.ts";
+import { useLegacyTempWorkdir } from "../../../../../tests/helpers/legacy-mocks.ts";
+import { legacyStorageLs } from "./ls.handler.ts";
+import type { LegacyStorageLsFlags } from "./ls.command.ts";
+
+const BUCKET = "/storage/v1/bucket";
+const LIST = (bucket: string) => `/storage/v1/object/list/${bucket}`;
+
+function lsFlags(
+  opts: { path?: string; recursive?: boolean; local?: boolean } = {},
+): LegacyStorageLsFlags {
+  // `local` drives routing (default true here — most tests use the local stack).
+  return {
+    path: opts.path === undefined ? Option.none() : Option.some(opts.path),
+    recursive: opts.recursive ?? false,
+    linked: true,
+    local: opts.local ?? true,
+  };
+}
+
+describe("legacy storage ls", () => {
+  const tmp = useLegacyTempWorkdir("supabase-storage-ls-");
+
+  it.live("lists buckets at the root, filtered by the bucket prefix", () => {
+    const { layer, out } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      routes: [
+        {
+          method: "GET",
+          match: BUCKET,
+          body: [
+            { name: "test", id: "test" },
+            { name: "private", id: "private" },
+          ],
+        },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageLs(lsFlags({ path: "ss:///te" })).pipe(
+        Effect.provide(layer),
+        Effect.exit,
+      );
+      expect(Exit.isSuccess(exit)).toBe(true);
+      // Only the prefix-matching bucket is printed, with a trailing slash.
+      expect(out.stdoutText).toBe("test/\n");
+    });
+  });
+
+  it.live("lists objects under a prefix, dirs get a trailing slash", () => {
+    const { layer, out } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      routes: [
+        {
+          method: "POST",
+          match: LIST("bucket"),
+          body: [
+            { name: "folder", id: null },
+            { name: "abstract.pdf", id: "9b7f9f48" },
+          ],
+        },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageLs(lsFlags({ path: "ss:///bucket/" })).pipe(
+        Effect.provide(layer),
+        Effect.exit,
+      );
+      expect(Exit.isSuccess(exit)).toBe(true);
+      expect(out.stdoutText).toBe("folder/\nabstract.pdf\n");
+    });
+  });
+
+  it.live("paginates past PAGE_LIMIT and reports Loading page on stderr", () => {
+    const page0 = Array.from({ length: 100 }, (_, i) => ({ name: `f${i}`, id: `${i}` }));
+    const { layer, out, requests } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      routes: [
+        { method: "POST", match: LIST("bucket"), when: (b) => !hasOffset(b), body: page0 },
+        { method: "POST", match: LIST("bucket"), when: (b) => hasOffset(b), body: [] },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageLs(lsFlags({ path: "ss:///bucket/dir/" })).pipe(
+        Effect.provide(layer),
+        Effect.exit,
+      );
+      expect(Exit.isSuccess(exit)).toBe(true);
+      expect(out.stderrText).toContain("Loading page: 1");
+      expect(out.stdoutText.split("\n").filter(Boolean)).toHaveLength(100);
+      // Two list calls: page 0 (offset omitted) then page 1 (offset 100).
+      const lists = requests.filter((r) => r.url.includes(LIST("bucket")));
+      expect(lists).toHaveLength(2);
+      const secondBody = lists[1]?.body as { offset?: number } | undefined;
+      expect(secondBody?.offset).toBe(100);
+    });
+  });
+
+  it.live("recursively walks nested dirs and reports an empty bucket", () => {
+    const { layer, out } = setupLegacyStorage(tmp.current, {
+      local: true,
+      toml: 'project_id = "test"\n',
+      routes: [
+        // root → buckets
+        {
+          method: "GET",
+          match: BUCKET,
+          body: [
+            { name: "test", id: "test" },
+            { name: "private", id: "private" },
+          ],
+        },
+        // empty bucket "test"
+        { method: "POST", match: LIST("test"), body: [] },
+        // "private" → a folder
+        {
+          method: "POST",
+          match: LIST("private"),
+          when: (b) => prefixOf(b) === "",
+          body: [{ name: "folder", id: null }],
+        },
+        // "private/folder/" → a file
+        {
+          method: "POST",
+          match: LIST("private"),
+          when: (b) => prefixOf(b) === "folder/",
+          body: [{ name: "abstract.pdf", id: "id" }],
+        },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageLs(lsFlags({ recursive: true })).pipe(
+        Effect.provide(layer),
+        Effect.exit,
+      );
+      expect(Exit.isSuccess(exit)).toBe(true);
+      const lines = out.stdoutText.split("\n").filter(Boolean);
+      // Default path is `ss:///` → remotePath `/`, so basePath is `/` and file
+      // paths get a leading slash; an empty bucket is reported bare as `<bucket>/`.
+      expect(lines).toContain("test/");
+      expect(lines).toContain("/private/folder/abstract.pdf");
+    });
+  });
+
+  it.live("fails on an invalid url without any network call", () => {
+    const { layer, requests } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageLs(lsFlags({ path: "ss://bucket" })).pipe(
+        Effect.provide(layer),
+        Effect.exit,
+      );
+      expect(Exit.isFailure(exit)).toBe(true);
+      expect(JSON.stringify(exit)).toContain("URL must match pattern ss:///bucket/[prefix]");
+      expect(requests).toHaveLength(0);
+    });
+  });
+
+  it.live("surfaces a url-parse error (missing protocol scheme)", () => {
+    const { layer } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageLs(lsFlags({ path: ":" })).pipe(
+        Effect.provide(layer),
+        Effect.exit,
+      );
+      expect(Exit.isFailure(exit)).toBe(true);
+      const json = JSON.stringify(exit);
+      expect(json).toContain("failed to parse storage url");
+      expect(json).toContain("missing protocol scheme");
+    });
+  });
+
+  it.live("propagates a 503 from the bucket service", () => {
+    const { layer } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      routes: [{ method: "GET", match: BUCKET, status: 503, body: { message: "unavailable" } }],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageLs(lsFlags()).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isFailure(exit)).toBe(true);
+      expect(JSON.stringify(exit)).toContain("Error status 503");
+    });
+  });
+
+  it.live("targets the linked project's Storage host and flushes telemetry", () => {
+    const { layer, requests, telemetry, linkedCache } = setupLegacyStorage(tmp.current, {
+      // No `--local`, so the linked path resolves the ref + service-role key.
+      routes: [
+        {
+          method: "GET",
+          match: BUCKET,
+          body: [{ name: "remote", id: "remote" }],
+        },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageLs(lsFlags({ local: false })).pipe(
+        Effect.provide(layer),
+        Effect.exit,
+      );
+      expect(Exit.isSuccess(exit)).toBe(true);
+      expect(
+        requests.some((r) => r.url.startsWith(`https://${LEGACY_VALID_REF}.supabase.co`)),
+      ).toBe(true);
+      expect(telemetry.flushed).toBe(true);
+      expect(linkedCache.cached).toBe(true);
+      expect(linkedCache.cachedRef).toBe(LEGACY_VALID_REF);
+    });
+  });
+
+  it.live("emits a { paths } result in json mode", () => {
+    const { layer, out } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      format: "json",
+      routes: [{ method: "GET", match: BUCKET, body: [{ name: "test", id: "test" }] }],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageLs(lsFlags()).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      // No streamed stdout lines in json mode; a single result carries the paths.
+      expect(out.stdoutText).toBe("");
+      const success = out.messages.find((m) => m.type === "success");
+      expect(success?.data?.["paths"]).toEqual(["test/"]);
+    });
+  });
+
+  it.live("paginates without the Loading page line in json mode", () => {
+    const page0 = Array.from({ length: 100 }, (_, i) => ({ name: `f${i}`, id: `${i}` }));
+    const { layer, out } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      format: "stream-json",
+      routes: [
+        { method: "POST", match: LIST("bucket"), when: (b) => !hasOffset(b), body: page0 },
+        { method: "POST", match: LIST("bucket"), when: (b) => hasOffset(b), body: [] },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageLs(lsFlags({ path: "ss:///bucket/dir/" })).pipe(
+        Effect.provide(layer),
+        Effect.exit,
+      );
+      expect(Exit.isSuccess(exit)).toBe(true);
+      // json/stream-json suppress the pagination notice.
+      expect(out.stderrText).not.toContain("Loading page");
+    });
+  });
+});
+
+function hasOffset(body: unknown): boolean {
+  return typeof body === "object" && body !== null && "offset" in body;
+}
+
+function prefixOf(body: unknown): string {
+  return typeof body === "object" &&
+    body !== null &&
+    typeof (body as { prefix?: unknown }).prefix === "string"
+    ? (body as { prefix: string }).prefix
+    : "";
+}
diff --git a/apps/cli/src/legacy/commands/storage/mv/SIDE_EFFECTS.md b/apps/cli/src/legacy/commands/storage/mv/SIDE_EFFECTS.md
index 1187b8e36a..8dc5ec88ab 100644
--- a/apps/cli/src/legacy/commands/storage/mv/SIDE_EFFECTS.md
+++ b/apps/cli/src/legacy/commands/storage/mv/SIDE_EFFECTS.md
@@ -1,58 +1,77 @@
 # `supabase storage mv <src> <dst>`
 
+Native TypeScript port of `apps/cli-go/internal/storage/mv`. Moves objects within a
+bucket. Both paths must be `ss://` and resolve to the same bucket. A direct move that
+returns `not_found` falls back to a recursive per-object move when `--recursive` is set.
+
 ## Files Read
 
-| Path                       | Format     | When                                                       |
-| -------------------------- | ---------- | ---------------------------------------------------------- |
-| `~/.supabase/access-token` | plain text | when `SUPABASE_ACCESS_TOKEN` unset and keyring unavailable |
+| Path                                     | Format     | When                                                  |
+| ---------------------------------------- | ---------- | ----------------------------------------------------- |
+| `<workdir>/supabase/config.toml`         | TOML       | always (local creds; `[remotes.*]` merge when linked) |
+| `~/.supabase/access-token`               | plain text | linked path, when `SUPABASE_ACCESS_TOKEN` unset       |
+| `~/.supabase/<hash>/linked-project.json` | JSON       | linked path, to resolve the project ref               |
+| local Kong TLS cert/key                  | PEM        | local + `api.enabled` + `api.tls.enabled`             |
 
 ## Files Written
 
-| Path | Format | When |
-| ---- | ------ | ---- |
-| —    | —      | —    |
+| Path                                     | Format | When                  |
+| ---------------------------------------- | ------ | --------------------- |
+| `~/.supabase/<hash>/linked-project.json` | JSON   | post-run, linked path |
+| `~/.supabase/telemetry.json`             | JSON   | post-run (always)     |
 
 ## API Routes
 
-| Method | Path                      | Auth         | Request body                            | Response (used fields) |
-| ------ | ------------------------- | ------------ | --------------------------------------- | ---------------------- |
-| `POST` | `/storage/v1/object/move` | Bearer token | `{bucketId, sourceKey, destinationKey}` | none                   |
+Auth: `apikey` always; `Authorization: Bearer <key>` unless the key is `sb_`-prefixed.
+
+| Method | Path                                      | Request body                                                 | Response         |
+| ------ | ----------------------------------------- | ------------------------------------------------------------ | ---------------- |
+| `POST` | `/storage/v1/object/move`                 | `{bucketId, sourceKey, destinationKey}`                      | `{message}`      |
+| `POST` | `/storage/v1/object/list/{bucket}`        | `{prefix, search?, limit:100, offset?}` (recursive fallback) | `[{name, id?}]`  |
+| `GET`  | `/v1/projects/{ref}/api-keys?reveal=true` | — (linked, Management API)                                   | service-role key |
 
 ## Environment Variables
 
-| Variable                | Purpose                                              | Required?                                               |
-| ----------------------- | ---------------------------------------------------- | ------------------------------------------------------- |
-| `SUPABASE_ACCESS_TOKEN` | auth token (bypasses credential file/keyring lookup) | no (falls back to keyring → `~/.supabase/access-token`) |
-| `SUPABASE_API_URL`      | override Management API base URL                     | no (defaults to `https://api.supabase.com`)             |
+`SUPABASE_AUTH_SERVICE_ROLE_KEY`, `SUPABASE_AUTH_JWT_SECRET`, `SUPABASE_ACCESS_TOKEN`,
+`SUPABASE_PROJECT_ID`, `SUPABASE_SERVICES_HOSTNAME` — same roles as `storage ls`.
 
 ## Exit Codes
 
-| Code | Condition                             |
-| ---- | ------------------------------------- |
-| `0`  | success                               |
-| `1`  | API error (non-2xx response)          |
-| `1`  | authentication error (no token found) |
-| `1`  | source object not found               |
-| `1`  | network / connection failure          |
+| Code | Condition                                                                                                                                            |
+| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `0`  | success                                                                                                                                              |
+| `1`  | invalid/parse url, missing object path (both roots), cross-bucket move, object-not-found (recursive empty), API non-2xx, network, auth, config parse |
 
 ## Output
 
 ### `--output-format text` (Go CLI compatible)
 
-Prints a success message after objects are moved.
+- `Moving object: <src> => <dst>` (stderr) for the top-level move and each recursive move.
+- The move response `message` is printed (stderr) on a successful single move.
 
 ### `--output-format json`
 
-Not applicable (proxied to Go binary).
+```json
+{ "message": "Successfully moved" }
+```
+
+(Recursive fallback emits `{ "message": "", "moved": <count> }`.)
 
 ### `--output-format stream-json`
 
-Not applicable (proxied to Go binary).
+```ndjson
+{"type":"result","data":{"message":"Successfully moved"}}
+```
+
+## Telemetry Events Fired
+
+| Event                  | When                                       | Notable properties               |
+| ---------------------- | ------------------------------------------ | -------------------------------- |
+| `cli_command_executed` | post-run, success or failure (via wrapper) | `flags` (recursive/linked/local) |
 
 ## Notes
 
-- Moves objects within Supabase Storage (both src and dst must use `ss:///` scheme).
-- `--recursive` / `-r` moves directories recursively.
-- `--linked` (default) connects to linked project Storage API.
-- `--local` connects to local database Storage API.
-- Phase 0 proxy: all invocations are forwarded to the bundled Go binary.
+- Both `src` and `dst` must be `ss://` URLs (Go uses `ParseStorageURL`, not the lenient
+  `url.Parse` that `cp` uses).
+- The cross-bucket and missing-path checks run before any network call.
+- `--recursive`/`-r` only takes effect when the direct move returns `"error":"not_found"`.
diff --git a/apps/cli/src/legacy/commands/storage/mv/mv.command.ts b/apps/cli/src/legacy/commands/storage/mv/mv.command.ts
index 733c749983..28ea3b98d8 100644
--- a/apps/cli/src/legacy/commands/storage/mv/mv.command.ts
+++ b/apps/cli/src/legacy/commands/storage/mv/mv.command.ts
@@ -1,5 +1,16 @@
+import { Effect } from "effect";
 import { Argument, Command, Flag } from "effect/unstable/cli";
 import type * as CliCommand from "effect/unstable/cli/Command";
+
+import { CliArgs } from "../../../../shared/cli/cli-args.service.ts";
+import { withJsonErrorHandling } from "../../../../shared/output/json-error-handling.ts";
+import { withLegacyCommandInstrumentation } from "../../../telemetry/legacy-command-instrumentation.ts";
+import { legacyStorageGatewayRuntimeLayer } from "../../../shared/legacy-storage-runtime.layer.ts";
+import {
+  LegacyStorageLinkedFlagDef,
+  LegacyStorageLocalFlagDef,
+  legacyAssertStorageTargetsExclusive,
+} from "../storage.flags.ts";
 import { legacyStorageMv } from "./mv.handler.ts";
 
 const config = {
@@ -9,12 +20,8 @@ const config = {
     Flag.withAlias("r"),
     Flag.withDescription("Recursively move a directory."),
   ),
-  local: Flag.boolean("local").pipe(
-    Flag.withDescription("Connects to Storage API of the local database."),
-  ),
-  linked: Flag.boolean("linked").pipe(
-    Flag.withDescription("Connects to Storage API of the linked project."),
-  ),
+  linked: LegacyStorageLinkedFlagDef,
+  local: LegacyStorageLocalFlagDef,
 } as const;
 
 export type LegacyStorageMvFlags = CliCommand.Command.Config.Infer<typeof config>;
@@ -28,5 +35,19 @@ export const legacyStorageMvCommand = Command.make("mv", config).pipe(
       description: "Recursively move a directory within storage",
     },
   ]),
-  Command.withHandler((flags) => legacyStorageMv(flags)),
+  Command.withHandler((flags) =>
+    Effect.gen(function* () {
+      const cliArgs = yield* CliArgs;
+      yield* legacyAssertStorageTargetsExclusive(cliArgs.args);
+      const telemetryFlags = {
+        recursive: flags.recursive,
+        linked: flags.linked,
+        local: flags.local,
+      };
+      return yield* legacyStorageMv(flags).pipe(
+        withLegacyCommandInstrumentation({ flags: telemetryFlags }),
+      );
+    }).pipe(withJsonErrorHandling),
+  ),
+  Command.provide(legacyStorageGatewayRuntimeLayer(["storage", "mv"])),
 );
diff --git a/apps/cli/src/legacy/commands/storage/mv/mv.handler.ts b/apps/cli/src/legacy/commands/storage/mv/mv.handler.ts
index def88c3454..dfa6a64c07 100644
--- a/apps/cli/src/legacy/commands/storage/mv/mv.handler.ts
+++ b/apps/cli/src/legacy/commands/storage/mv/mv.handler.ts
@@ -1,15 +1,146 @@
-import { Effect } from "effect";
-import { LegacyGoProxy } from "../../../../shared/legacy/go-proxy.service.ts";
+import * as nodePath from "node:path";
+
+import { Effect, Option } from "effect";
+
+import { LegacyCliConfig } from "../../../config/legacy-cli-config.service.ts";
+import { LegacyProjectRefResolver } from "../../../config/legacy-project-ref.service.ts";
+import { LegacyLinkedProjectCache } from "../../../telemetry/legacy-linked-project-cache.service.ts";
+import { LegacyTelemetryState } from "../../../telemetry/legacy-telemetry-state.service.ts";
+import { Output } from "../../../../shared/output/output.service.ts";
+import type { LegacyStorageGateway } from "../../../shared/legacy-storage-gateway.ts";
+import { LegacyStorageGatewayStatusError } from "../../../shared/legacy-storage-gateway.errors.ts";
+import { legacySplitBucketPrefix } from "../../../shared/legacy-storage-url.ts";
+import {
+  legacyConnectStorageGateway,
+  legacyLoadStorageConfig,
+  legacyParseStorageUrlEffect,
+} from "../storage.frame.ts";
+import {
+  LegacyStorageMissingPathError,
+  LegacyStorageObjectNotFoundError,
+  LegacyStorageUnsupportedMoveError,
+} from "../storage.errors.ts";
+import { legacyListStoragePaths } from "../storage.iterate.ts";
 import type { LegacyStorageMvFlags } from "./mv.command.ts";
 
+/**
+ * `supabase storage mv <src> <dst>` — move objects within a bucket. Port of
+ * `apps/cli-go/internal/storage/mv/mv.go`. Both paths must be `ss://` and in the
+ * same bucket. A direct move that returns `not_found` falls back to a recursive
+ * per-object move when `--recursive` is set.
+ */
 export const legacyStorageMv = Effect.fn("legacy.storage.mv")(function* (
   flags: LegacyStorageMvFlags,
 ) {
-  const proxy = yield* LegacyGoProxy;
-  const args: string[] = ["storage", "mv"];
-  if (flags.recursive) args.push("--recursive");
-  if (flags.local) args.push("--local");
-  if (flags.linked) args.push("--linked");
-  args.push(flags.src, flags.dst);
-  yield* proxy.exec(args);
+  const output = yield* Output;
+  const cliConfig = yield* LegacyCliConfig;
+  const telemetryState = yield* LegacyTelemetryState;
+  const linkedProjectCache = yield* LegacyLinkedProjectCache;
+  const resolver = yield* LegacyProjectRefResolver;
+
+  let linkedRef = "";
+
+  yield* Effect.gen(function* () {
+    const projectRef = flags.local ? "" : yield* resolver.loadProjectRef(Option.none());
+    linkedRef = projectRef;
+    const loaded = yield* legacyLoadStorageConfig(cliConfig.workdir, projectRef);
+    if (loaded.appliedRemote !== undefined) {
+      yield* output.raw(`Loading config override: [remotes.${loaded.appliedRemote}]\n`, "stderr");
+    }
+
+    // Parse + validate BEFORE building the client (Go `mv.go:24-39`): both must be
+    // ss://, at least one prefix non-empty, and the same bucket.
+    const srcParsed = yield* legacyParseStorageUrlEffect(flags.src);
+    const dstParsed = yield* legacyParseStorageUrlEffect(flags.dst);
+    const [srcBucket, srcPrefix] = legacySplitBucketPrefix(srcParsed);
+    const [dstBucket, dstPrefix] = legacySplitBucketPrefix(dstParsed);
+    if (srcPrefix.length === 0 && dstPrefix.length === 0) {
+      return yield* new LegacyStorageMissingPathError();
+    }
+    if (srcBucket !== dstBucket) {
+      return yield* new LegacyStorageUnsupportedMoveError();
+    }
+
+    yield* legacyConnectStorageGateway(
+      { projectRef, config: loaded.config, userAgent: cliConfig.userAgent },
+      (gateway) =>
+        Effect.gen(function* () {
+          yield* output.raw(`Moving object: ${srcParsed} => ${dstParsed}\n`, "stderr");
+          const result = yield* gateway.moveObject(srcBucket, srcPrefix, dstPrefix).pipe(
+            Effect.map((message) => ({ moved: true, message })),
+            Effect.catch((error) =>
+              error instanceof LegacyStorageGatewayStatusError &&
+              error.body.includes('"error":"not_found"') &&
+              flags.recursive
+                ? Effect.succeed({ moved: false, message: "" })
+                : Effect.fail(error),
+            ),
+          );
+
+          if (result.moved) {
+            // Go prints the move response message on success.
+            yield* output.raw(`${result.message}\n`, "stderr");
+            if (output.format !== "text") {
+              yield* output.success("", { message: result.message });
+            }
+            return;
+          }
+
+          // Recursive fallback on `not_found`.
+          const moved = yield* moveStorageObjectAll(gateway, output, `${srcParsed}/`, dstParsed);
+          if (output.format !== "text") {
+            yield* output.success("", { message: "", moved });
+          }
+        }),
+    );
+  }).pipe(
+    Effect.ensuring(
+      Effect.suspend(() => (linkedRef === "" ? Effect.void : linkedProjectCache.cache(linkedRef))),
+    ),
+    Effect.ensuring(telemetryState.flush),
+  );
 });
+
+/**
+ * Go `MoveStorageObjectAll` (`mv.go:55-88`): BFS over the source tree (LIFO),
+ * moving each object with its `srcPrefix`→`dstPrefix` rewrite. `srcPath` is
+ * terminated by `/`. Fails with `Object not found: <srcPath>` when nothing moved.
+ */
+const moveStorageObjectAll = (
+  gateway: LegacyStorageGateway,
+  output: typeof Output.Service,
+  srcPath: string,
+  dstPath: string,
+) =>
+  Effect.gen(function* () {
+    const [, dstPrefix] = legacySplitBucketPrefix(dstPath);
+    let count = 0;
+    const queue: Array<string> = [srcPath];
+    while (queue.length > 0) {
+      const dirPath = queue.pop();
+      if (dirPath === undefined) break;
+      const paths = yield* legacyListStoragePaths(gateway, output, dirPath);
+      for (const objectName of paths) {
+        const objectPath = dirPath + objectName;
+        if (objectName.endsWith("/")) {
+          queue.push(objectPath);
+          continue;
+        }
+        count++;
+        const relPath = objectPath.startsWith(srcPath)
+          ? objectPath.slice(srcPath.length)
+          : objectPath;
+        const [srcBucket, srcPrefix] = legacySplitBucketPrefix(objectPath);
+        const absPath = nodePath.posix.join(dstPrefix, relPath);
+        yield* output.raw(
+          `Moving object: ${objectPath} => ${nodePath.posix.join(dstPath, relPath)}\n`,
+          "stderr",
+        );
+        yield* gateway.moveObject(srcBucket, srcPrefix, absPath);
+      }
+    }
+    if (count === 0) {
+      return yield* new LegacyStorageObjectNotFoundError(srcPath);
+    }
+    return count;
+  });
diff --git a/apps/cli/src/legacy/commands/storage/mv/mv.integration.test.ts b/apps/cli/src/legacy/commands/storage/mv/mv.integration.test.ts
new file mode 100644
index 0000000000..5e1bbb77b7
--- /dev/null
+++ b/apps/cli/src/legacy/commands/storage/mv/mv.integration.test.ts
@@ -0,0 +1,238 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, Exit } from "effect";
+
+import { setupLegacyStorage } from "../../../../../tests/helpers/legacy-storage.ts";
+import { useLegacyTempWorkdir } from "../../../../../tests/helpers/legacy-mocks.ts";
+import { legacyStorageMv } from "./mv.handler.ts";
+import type { LegacyStorageMvFlags } from "./mv.command.ts";
+
+const MOVE = "/storage/v1/object/move";
+const LIST = (bucket: string) => `/storage/v1/object/list/${bucket}`;
+
+function mvFlags(opts: {
+  src: string;
+  dst: string;
+  recursive?: boolean;
+  local?: boolean;
+}): LegacyStorageMvFlags {
+  return {
+    src: opts.src,
+    dst: opts.dst,
+    recursive: opts.recursive ?? false,
+    linked: true,
+    local: opts.local ?? true,
+  };
+}
+
+describe("legacy storage mv", () => {
+  const tmp = useLegacyTempWorkdir("supabase-storage-mv-");
+
+  it.live("moves a single object and prints the response message", () => {
+    const { layer, out, requests } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      routes: [{ method: "POST", match: MOVE, body: { message: "Successfully moved" } }],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageMv(
+        mvFlags({ src: "ss:///private/readme.md", dst: "ss:///private/docs/file" }),
+      ).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      expect(out.stderrText).toContain("Moving object: /private/readme.md => /private/docs/file");
+      expect(out.stderrText).toContain("Successfully moved");
+      const move = requests.find((r) => r.url.includes(MOVE));
+      expect(move?.body).toEqual({
+        bucketId: "private",
+        sourceKey: "readme.md",
+        destinationKey: "docs/file",
+      });
+    });
+  });
+
+  it.live("fails with missing path when both sides are bucket roots", () => {
+    const { layer, requests } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageMv(mvFlags({ src: "ss:///", dst: "ss:///" })).pipe(
+        Effect.provide(layer),
+        Effect.exit,
+      );
+      expect(Exit.isFailure(exit)).toBe(true);
+      expect(JSON.stringify(exit)).toContain("You must specify an object path");
+      expect(requests).toHaveLength(0);
+    });
+  });
+
+  it.live("rejects moving between buckets", () => {
+    const { layer, requests } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageMv(
+        mvFlags({ src: "ss:///bucket/docs", dst: "ss:///private" }),
+      ).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isFailure(exit)).toBe(true);
+      expect(JSON.stringify(exit)).toContain("Moving between buckets is unsupported");
+      expect(requests).toHaveLength(0);
+    });
+  });
+
+  it.live("falls back to a recursive move when the direct move is not_found", () => {
+    const { layer, requests } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      routes: [
+        // direct move of the directory → not_found
+        {
+          method: "POST",
+          match: MOVE,
+          when: (b) => (b as { destinationKey?: string }).destinationKey === "docs",
+          status: 404,
+          body: { error: "not_found" },
+        },
+        // list the source dir → one object
+        { method: "POST", match: LIST("private"), body: [{ name: "abstract.pdf", id: "id" }] },
+        // per-object move
+        {
+          method: "POST",
+          match: MOVE,
+          when: (b) => (b as { sourceKey?: string }).sourceKey === "abstract.pdf",
+          body: { message: "ok" },
+        },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageMv(
+        mvFlags({ src: "ss:///private", dst: "ss:///private/docs", recursive: true }),
+      ).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      const perObject = requests.find(
+        (r) =>
+          r.url.includes(MOVE) && (r.body as { sourceKey?: string }).sourceKey === "abstract.pdf",
+      );
+      expect(perObject?.body).toEqual({
+        bucketId: "private",
+        sourceKey: "abstract.pdf",
+        destinationKey: "docs/abstract.pdf",
+      });
+    });
+  });
+
+  it.live("recursively moves a nested directory tree", () => {
+    const { layer, requests } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      routes: [
+        {
+          method: "POST",
+          match: MOVE,
+          when: (b) => (b as { sourceKey?: string }).sourceKey === "",
+          status: 404,
+          body: { error: "not_found" },
+        },
+        // top level: a subdir + a file
+        {
+          method: "POST",
+          match: LIST("private"),
+          when: (b) => (b as { prefix?: string }).prefix === "",
+          body: [
+            { name: "sub", id: null },
+            { name: "a.txt", id: "ai" },
+          ],
+        },
+        {
+          method: "POST",
+          match: MOVE,
+          when: (b) => (b as { sourceKey?: string }).sourceKey === "a.txt",
+          body: { message: "ok" },
+        },
+        // descend into sub/
+        {
+          method: "POST",
+          match: LIST("private"),
+          when: (b) => (b as { prefix?: string }).prefix === "sub/",
+          body: [{ name: "b.txt", id: "bi" }],
+        },
+        {
+          method: "POST",
+          match: MOVE,
+          when: (b) => (b as { sourceKey?: string }).sourceKey === "sub/b.txt",
+          body: { message: "ok" },
+        },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageMv(
+        mvFlags({ src: "ss:///private", dst: "ss:///private/docs", recursive: true }),
+      ).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      // Nested file moved with the sub/ prefix rewritten under docs/.
+      const nested = requests.find(
+        (r) => r.url.includes(MOVE) && (r.body as { sourceKey?: string }).sourceKey === "sub/b.txt",
+      );
+      expect(nested?.body).toEqual({
+        bucketId: "private",
+        sourceKey: "sub/b.txt",
+        destinationKey: "docs/sub/b.txt",
+      });
+    });
+  });
+
+  it.live("propagates a not_found error when not recursive", () => {
+    const { layer } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      routes: [{ method: "POST", match: MOVE, status: 404, body: { error: "not_found" } }],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageMv(
+        mvFlags({ src: "ss:///private/a", dst: "ss:///private/b" }),
+      ).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isFailure(exit)).toBe(true);
+      expect(JSON.stringify(exit)).toContain("not_found");
+    });
+  });
+
+  it.live("fails with Object not found when the recursive move is empty", () => {
+    const { layer } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      routes: [
+        {
+          method: "POST",
+          match: MOVE,
+          status: 404,
+          body: { error: "not_found" },
+        },
+        { method: "POST", match: LIST("private"), body: [] },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageMv(
+        mvFlags({ src: "ss:///private/dir", dst: "ss:///private/other", recursive: true }),
+      ).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isFailure(exit)).toBe(true);
+      expect(JSON.stringify(exit)).toContain("Object not found: /private/dir/");
+    });
+  });
+
+  it.live("emits a { message } result in json mode", () => {
+    const { layer, out } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      format: "json",
+      routes: [{ method: "POST", match: MOVE, body: { message: "Successfully moved" } }],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageMv(
+        mvFlags({ src: "ss:///private/a", dst: "ss:///private/b" }),
+      ).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      const success = out.messages.find((m) => m.type === "success");
+      expect(success?.data?.["message"]).toBe("Successfully moved");
+    });
+  });
+});
diff --git a/apps/cli/src/legacy/commands/storage/rm/SIDE_EFFECTS.md b/apps/cli/src/legacy/commands/storage/rm/SIDE_EFFECTS.md
index 66ceb44709..bc95d0f7b9 100644
--- a/apps/cli/src/legacy/commands/storage/rm/SIDE_EFFECTS.md
+++ b/apps/cli/src/legacy/commands/storage/rm/SIDE_EFFECTS.md
@@ -1,57 +1,83 @@
 # `supabase storage rm <file> ...`
 
+Native TypeScript port of `apps/cli-go/internal/storage/rm`. Removes objects by path.
+Paths are grouped by bucket; each bucket is confirmed, its explicit prefixes are deleted
+(chunked at 1000), and any prefix that resolved to a directory is removed recursively
+when `-r` is set. With no paths and `-r`, every bucket is cleared and deleted.
+
 ## Files Read
 
-| Path                       | Format     | When                                                       |
-| -------------------------- | ---------- | ---------------------------------------------------------- |
-| `~/.supabase/access-token` | plain text | when `SUPABASE_ACCESS_TOKEN` unset and keyring unavailable |
+| Path                                     | Format     | When                                                  |
+| ---------------------------------------- | ---------- | ----------------------------------------------------- |
+| `<workdir>/supabase/config.toml`         | TOML       | always (local creds; `[remotes.*]` merge when linked) |
+| `~/.supabase/access-token`               | plain text | linked path, when `SUPABASE_ACCESS_TOKEN` unset       |
+| `~/.supabase/<hash>/linked-project.json` | JSON       | linked path, to resolve the project ref               |
+| local Kong TLS cert/key                  | PEM        | local + `api.enabled` + `api.tls.enabled`             |
 
 ## Files Written
 
-| Path | Format | When |
-| ---- | ------ | ---- |
-| —    | —      | —    |
+| Path                                     | Format | When                  |
+| ---------------------------------------- | ------ | --------------------- |
+| `~/.supabase/<hash>/linked-project.json` | JSON   | post-run, linked path |
+| `~/.supabase/telemetry.json`             | JSON   | post-run (always)     |
 
 ## API Routes
 
-| Method   | Path                          | Auth         | Request body        | Response (used fields) |
-| -------- | ----------------------------- | ------------ | ------------------- | ---------------------- |
-| `DELETE` | `/storage/v1/object/{bucket}` | Bearer token | `{prefixes: [...]}` | none                   |
+Auth: `apikey` always; `Authorization: Bearer <key>` unless the key is `sb_`-prefixed.
+
+| Method   | Path                                      | Request body                                             | Response         |
+| -------- | ----------------------------------------- | -------------------------------------------------------- | ---------------- |
+| `DELETE` | `/storage/v1/object/{bucket}`             | `{prefixes}` (chunked by 1000)                           | `[{name, ...}]`  |
+| `DELETE` | `/storage/v1/bucket/{id}`                 | — (recursive on an empty prefix)                         | `{message}`      |
+| `POST`   | `/storage/v1/object/list/{bucket}`        | `{prefix, search?, limit:100, offset?}` (recursive walk) | `[{name, id?}]`  |
+| `GET`    | `/storage/v1/bucket`                      | — (no-args + `-r`: delete all buckets)                   | `[{name, id}]`   |
+| `GET`    | `/v1/projects/{ref}/api-keys?reveal=true` | — (linked, Management API)                               | service-role key |
 
 ## Environment Variables
 
-| Variable                | Purpose                                              | Required?                                               |
-| ----------------------- | ---------------------------------------------------- | ------------------------------------------------------- |
-| `SUPABASE_ACCESS_TOKEN` | auth token (bypasses credential file/keyring lookup) | no (falls back to keyring → `~/.supabase/access-token`) |
-| `SUPABASE_API_URL`      | override Management API base URL                     | no (defaults to `https://api.supabase.com`)             |
+`SUPABASE_AUTH_SERVICE_ROLE_KEY`, `SUPABASE_AUTH_JWT_SECRET`, `SUPABASE_ACCESS_TOKEN`,
+`SUPABASE_PROJECT_ID`, `SUPABASE_SERVICES_HOSTNAME`, plus `SUPABASE_YES` (auto-confirm).
 
 ## Exit Codes
 
-| Code | Condition                             |
-| ---- | ------------------------------------- |
-| `0`  | success                               |
-| `1`  | API error (non-2xx response)          |
-| `1`  | authentication error (no token found) |
-| `1`  | network / connection failure          |
+| Code | Condition                                                                                                                                                                    |
+| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `0`  | success (including a declined confirmation, and a tolerated `Bucket not found`)                                                                                              |
+| `1`  | invalid/parse url, missing bucket (root path), missing `-r` flag (directory or no args), object-not-found (recursive empty prefix), API non-2xx, network, auth, config parse |
 
 ## Output
 
 ### `--output-format text` (Go CLI compatible)
 
-Prints a success message after objects are removed.
+- `Confirm deleting files in bucket <bold bucket>?` prompt (default no); `--yes`/`SUPABASE_YES`
+  echoes `<label> [y/N] y` and proceeds.
+- `Deleting objects: [<space-separated prefixes>]` (Go slice repr) per delete batch (stderr).
+- `Object not found: <prefix>` (non-recursive) / `Deleting bucket: <bucket>` /
+  `Bucket not found: <bucket>` (stderr).
 
 ### `--output-format json`
 
-Not applicable (proxied to Go binary).
+```json
+{ "deleted": ["abstract.pdf"], "buckets_deleted": ["private"] }
+```
 
 ### `--output-format stream-json`
 
-Not applicable (proxied to Go binary).
+```ndjson
+{"type":"result","data":{"deleted":["abstract.pdf"],"buckets_deleted":["private"]}}
+```
+
+## Telemetry Events Fired
+
+| Event                  | When                                       | Notable properties               |
+| ---------------------- | ------------------------------------------ | -------------------------------- |
+| `cli_command_executed` | post-run, success or failure (via wrapper) | `flags` (recursive/linked/local) |
 
 ## Notes
 
-- Accepts one or more `ss:///bucket/path` arguments.
-- `--recursive` / `-r` removes directories recursively.
-- `--linked` (default) connects to linked project Storage API.
-- `--local` connects to local database Storage API.
-- Phase 0 proxy: all invocations are forwarded to the bundled Go binary.
+- Validation (missing bucket, missing `-r` for a directory) runs before any network call;
+  the no-args missing-`-r` error runs after the client is built (matching Go).
+- A declined confirmation skips that bucket and is not an error.
+- Explicit deletes are attempted first ("in case the paths resolve to extensionless files");
+  prefixes not returned as removed are then walked recursively when `-r` is set.
+- Object deletes are chunked at `DELETE_OBJECTS_LIMIT` (1000) per request.
diff --git a/apps/cli/src/legacy/commands/storage/rm/rm.command.ts b/apps/cli/src/legacy/commands/storage/rm/rm.command.ts
index 2a1bc32d39..4884cf6497 100644
--- a/apps/cli/src/legacy/commands/storage/rm/rm.command.ts
+++ b/apps/cli/src/legacy/commands/storage/rm/rm.command.ts
@@ -1,4 +1,15 @@
+import { Effect } from "effect";
 import { Argument, Command, Flag } from "effect/unstable/cli";
+
+import { CliArgs } from "../../../../shared/cli/cli-args.service.ts";
+import { withJsonErrorHandling } from "../../../../shared/output/json-error-handling.ts";
+import { withLegacyCommandInstrumentation } from "../../../telemetry/legacy-command-instrumentation.ts";
+import { legacyStorageGatewayRuntimeLayer } from "../../../shared/legacy-storage-runtime.layer.ts";
+import {
+  LegacyStorageLinkedFlagDef,
+  LegacyStorageLocalFlagDef,
+  legacyAssertStorageTargetsExclusive,
+} from "../storage.flags.ts";
 import { legacyStorageRm } from "./rm.handler.ts";
 
 const config = {
@@ -10,12 +21,8 @@ const config = {
     Flag.withAlias("r"),
     Flag.withDescription("Recursively remove a directory."),
   ),
-  local: Flag.boolean("local").pipe(
-    Flag.withDescription("Connects to Storage API of the local database."),
-  ),
-  linked: Flag.boolean("linked").pipe(
-    Flag.withDescription("Connects to Storage API of the linked project."),
-  ),
+  linked: LegacyStorageLinkedFlagDef,
+  local: LegacyStorageLocalFlagDef,
 } as const;
 
 export const legacyStorageRmCommand = Command.make("rm", config).pipe(
@@ -32,11 +39,21 @@ export const legacyStorageRmCommand = Command.make("rm", config).pipe(
     },
   ]),
   Command.withHandler((flags) =>
-    legacyStorageRm({
-      files: flags.files.map(String),
-      recursive: flags.recursive,
-      local: flags.local,
-      linked: flags.linked,
-    }),
+    Effect.gen(function* () {
+      const cliArgs = yield* CliArgs;
+      yield* legacyAssertStorageTargetsExclusive(cliArgs.args);
+      const telemetryFlags = {
+        recursive: flags.recursive,
+        linked: flags.linked,
+        local: flags.local,
+      };
+      return yield* legacyStorageRm({
+        files: flags.files.map(String),
+        recursive: flags.recursive,
+        linked: flags.linked,
+        local: flags.local,
+      }).pipe(withLegacyCommandInstrumentation({ flags: telemetryFlags }));
+    }).pipe(withJsonErrorHandling),
   ),
+  Command.provide(legacyStorageGatewayRuntimeLayer(["storage", "rm"])),
 );
diff --git a/apps/cli/src/legacy/commands/storage/rm/rm.handler.ts b/apps/cli/src/legacy/commands/storage/rm/rm.handler.ts
index 85d0196185..b2ef0aa531 100644
--- a/apps/cli/src/legacy/commands/storage/rm/rm.handler.ts
+++ b/apps/cli/src/legacy/commands/storage/rm/rm.handler.ts
@@ -1,21 +1,212 @@
-import { Effect } from "effect";
-import { LegacyGoProxy } from "../../../../shared/legacy/go-proxy.service.ts";
+import { Effect, Option } from "effect";
 
-interface LegacyStorageRmFlags {
+import { LegacyCliConfig } from "../../../config/legacy-cli-config.service.ts";
+import { LegacyProjectRefResolver } from "../../../config/legacy-project-ref.service.ts";
+import { LegacyLinkedProjectCache } from "../../../telemetry/legacy-linked-project-cache.service.ts";
+import { LegacyTelemetryState } from "../../../telemetry/legacy-telemetry-state.service.ts";
+import { LegacyYesFlag } from "../../../../shared/legacy/global-flags.ts";
+import { Output } from "../../../../shared/output/output.service.ts";
+import { legacyBold } from "../../../shared/legacy-colors.ts";
+import { legacyPromptYesNo } from "../../../shared/legacy-prompt-yes-no.ts";
+import {
+  LEGACY_DELETE_OBJECTS_LIMIT,
+  type LegacyStorageGateway,
+} from "../../../shared/legacy-storage-gateway.ts";
+import { LegacyStorageGatewayStatusError } from "../../../shared/legacy-storage-gateway.errors.ts";
+import { legacySplitBucketPrefix, legacyStorageIsDir } from "../../../shared/legacy-storage-url.ts";
+import {
+  legacyConnectStorageGateway,
+  legacyLoadStorageConfig,
+  legacyParseStorageUrlEffect,
+} from "../storage.frame.ts";
+import {
+  LegacyStorageMissingBucketError,
+  LegacyStorageMissingFlagError,
+  LegacyStorageObjectNotFoundError,
+} from "../storage.errors.ts";
+import { legacyListStoragePaths } from "../storage.iterate.ts";
+
+export interface LegacyStorageRmFlags {
   readonly files: ReadonlyArray<string>;
   readonly recursive: boolean;
-  readonly local: boolean;
+  // `linked` is carried for parity with the ls/cp/mv handler signatures; routing
+  // reads only `local` (Go `storage.go:21-32` reads `GetBool("local")`).
   readonly linked: boolean;
+  readonly local: boolean;
+}
+
+interface RmSummary {
+  readonly deleted: Array<string>;
+  readonly buckets_deleted: Array<string>;
 }
 
+/**
+ * `supabase storage rm <file>...` — remove objects by path. Port of
+ * `apps/cli-go/internal/storage/rm/rm.go`. Paths are grouped by bucket; each
+ * bucket is confirmed, its explicit prefixes are deleted (chunked at 1000), and
+ * any prefix that resolved to a directory is removed recursively when `-r` is set.
+ */
 export const legacyStorageRm = Effect.fn("legacy.storage.rm")(function* (
   flags: LegacyStorageRmFlags,
 ) {
-  const proxy = yield* LegacyGoProxy;
-  const args: string[] = ["storage", "rm"];
-  if (flags.recursive) args.push("--recursive");
-  if (flags.local) args.push("--local");
-  if (flags.linked) args.push("--linked");
-  args.push(...flags.files);
-  yield* proxy.exec(args);
+  const output = yield* Output;
+  const cliConfig = yield* LegacyCliConfig;
+  const telemetryState = yield* LegacyTelemetryState;
+  const linkedProjectCache = yield* LegacyLinkedProjectCache;
+  const resolver = yield* LegacyProjectRefResolver;
+  const yes = yield* LegacyYesFlag;
+
+  let linkedRef = "";
+
+  yield* Effect.gen(function* () {
+    const projectRef = flags.local ? "" : yield* resolver.loadProjectRef(Option.none());
+    linkedRef = projectRef;
+    const loaded = yield* legacyLoadStorageConfig(cliConfig.workdir, projectRef);
+    if (loaded.appliedRemote !== undefined) {
+      yield* output.raw(`Loading config override: [remotes.${loaded.appliedRemote}]\n`, "stderr");
+    }
+
+    // Group paths by bucket, validating BEFORE building the client (Go `rm.go:31-47`).
+    const groups = new Map<string, Array<string>>();
+    for (const objectPath of flags.files) {
+      const remotePath = yield* legacyParseStorageUrlEffect(objectPath);
+      const [bucket, prefix] = legacySplitBucketPrefix(remotePath);
+      if (bucket.length === 0) {
+        return yield* new LegacyStorageMissingBucketError();
+      }
+      if (legacyStorageIsDir(prefix) && !flags.recursive) {
+        return yield* new LegacyStorageMissingFlagError();
+      }
+      const existing = groups.get(bucket);
+      if (existing === undefined) groups.set(bucket, [prefix]);
+      else existing.push(prefix);
+    }
+
+    const summary: RmSummary = { deleted: [], buckets_deleted: [] };
+
+    yield* legacyConnectStorageGateway(
+      { projectRef, config: loaded.config, userAgent: cliConfig.userAgent },
+      (gateway) =>
+        Effect.gen(function* () {
+          // No paths: `-r` deletes every bucket, otherwise it's a missing-flag
+          // error (Go `rm.go:52-63`, after the client is built).
+          if (groups.size === 0) {
+            if (!flags.recursive) {
+              return yield* new LegacyStorageMissingFlagError();
+            }
+            const buckets = yield* gateway.listBuckets();
+            for (const b of buckets) groups.set(b.name, [""]);
+          }
+
+          for (const [bucket, prefixes] of groups) {
+            const shouldDelete = yield* legacyPromptYesNo(
+              output,
+              yes,
+              `Confirm deleting files in bucket ${legacyBold(bucket)}?`,
+              false,
+            );
+            if (!shouldDelete) continue;
+
+            // Always try deleting first in case the paths are extensionless files.
+            yield* output.raw(`Deleting objects: [${prefixes.join(" ")}]\n`, "stderr");
+            const removed = yield* deleteObjects(gateway, bucket, prefixes, summary);
+            const removedSet = new Set(removed.map((o) => o.name));
+
+            for (const prefix of prefixes) {
+              if (removedSet.has(prefix)) continue;
+              if (!flags.recursive) {
+                yield* output.raw(`Object not found: ${prefix}\n`, "stderr");
+                continue;
+              }
+              const dirPrefix = prefix.length > 0 ? `${prefix}/` : prefix;
+              yield* removeStoragePathAll(gateway, output, bucket, dirPrefix, summary);
+            }
+          }
+
+          if (output.format !== "text") {
+            yield* output.success("", {
+              deleted: summary.deleted,
+              buckets_deleted: summary.buckets_deleted,
+            });
+          }
+        }),
+    );
+  }).pipe(
+    Effect.ensuring(
+      Effect.suspend(() => (linkedRef === "" ? Effect.void : linkedProjectCache.cache(linkedRef))),
+    ),
+    Effect.ensuring(telemetryState.flush),
+  );
 });
+
+/** Go `rm.deleteObjects` (`rm.go:145-156`): DELETE in chunks of DELETE_OBJECTS_LIMIT. */
+const deleteObjects = (
+  gateway: LegacyStorageGateway,
+  bucket: string,
+  prefixes: ReadonlyArray<string>,
+  summary: RmSummary,
+) =>
+  Effect.gen(function* () {
+    const removed: Array<{ name: string }> = [];
+    for (let start = 0; start < prefixes.length; start += LEGACY_DELETE_OBJECTS_LIMIT) {
+      const end = Math.min(start + LEGACY_DELETE_OBJECTS_LIMIT, prefixes.length);
+      const objects = yield* gateway.deleteObjects(bucket, prefixes.slice(start, end));
+      removed.push(...objects);
+    }
+    for (const o of removed) summary.deleted.push(o.name);
+    return removed;
+  });
+
+/**
+ * Go `RemoveStoragePathAll` (`rm.go:102-143`): BFS over the prefix tree (LIFO),
+ * deleting files per directory, then deleting the bucket itself when the prefix
+ * is empty. `prefix` is terminated by `/` or empty.
+ */
+const removeStoragePathAll = (
+  gateway: LegacyStorageGateway,
+  output: typeof Output.Service,
+  bucket: string,
+  prefix: string,
+  summary: RmSummary,
+) =>
+  Effect.gen(function* () {
+    const queue: Array<string> = [prefix];
+    while (queue.length > 0) {
+      const dirPrefix = queue.pop();
+      if (dirPrefix === undefined) break;
+      const paths = yield* legacyListStoragePaths(gateway, output, `/${bucket}/${dirPrefix}`);
+      if (paths.length === 0 && prefix.length > 0) {
+        return yield* new LegacyStorageObjectNotFoundError(`${bucket}/${prefix}`);
+      }
+      const files: Array<string> = [];
+      for (const objectName of paths) {
+        const objectPrefix = dirPrefix + objectName;
+        if (objectName.endsWith("/")) {
+          queue.push(objectPrefix);
+        } else {
+          files.push(objectPrefix);
+        }
+      }
+      if (files.length > 0) {
+        yield* output.raw(`Deleting objects: [${files.join(" ")}]\n`, "stderr");
+        yield* deleteObjects(gateway, bucket, files, summary);
+      }
+    }
+    if (prefix.length === 0) {
+      yield* output.raw(`Deleting bucket: ${bucket}\n`, "stderr");
+      yield* gateway.deleteBucket(bucket).pipe(
+        Effect.flatMap((message) =>
+          Effect.gen(function* () {
+            yield* output.raw(`${message}\n`, "stderr");
+            summary.buckets_deleted.push(bucket);
+          }),
+        ),
+        Effect.catch((error) =>
+          error instanceof LegacyStorageGatewayStatusError &&
+          error.body.includes('"error":"Bucket not found"')
+            ? output.raw(`Bucket not found: ${bucket}\n`, "stderr")
+            : Effect.fail(error),
+        ),
+      );
+    }
+  });
diff --git a/apps/cli/src/legacy/commands/storage/rm/rm.integration.test.ts b/apps/cli/src/legacy/commands/storage/rm/rm.integration.test.ts
new file mode 100644
index 0000000000..ce02c1234d
--- /dev/null
+++ b/apps/cli/src/legacy/commands/storage/rm/rm.integration.test.ts
@@ -0,0 +1,394 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, Exit } from "effect";
+
+import { setupLegacyStorage } from "../../../../../tests/helpers/legacy-storage.ts";
+import { useLegacyTempWorkdir } from "../../../../../tests/helpers/legacy-mocks.ts";
+import { legacyStorageRm } from "./rm.handler.ts";
+
+const BUCKET = "/storage/v1/bucket";
+const DELETE_OBJECT = (bucket: string) => `/storage/v1/object/${bucket}`;
+const DELETE_BUCKET = (bucket: string) => `/storage/v1/bucket/${bucket}`;
+const LIST = (bucket: string) => `/storage/v1/object/list/${bucket}`;
+
+function prefixCount(body: unknown): number {
+  return typeof body === "object" &&
+    body !== null &&
+    Array.isArray((body as { prefixes?: unknown }).prefixes)
+    ? (body as { prefixes: unknown[] }).prefixes.length
+    : -1;
+}
+
+describe("legacy storage rm", () => {
+  const tmp = useLegacyTempWorkdir("supabase-storage-rm-");
+
+  it.live("deletes multiple objects after confirmation", () => {
+    const { layer, requests } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      yes: true,
+      routes: [
+        {
+          method: "DELETE",
+          match: DELETE_OBJECT("private"),
+          body: [{ name: "abstract.pdf" }, { name: "docs/readme.md" }],
+        },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageRm({
+        files: ["ss:///private/abstract.pdf", "ss:///private/docs/readme.md"],
+        recursive: false,
+        linked: true,
+        local: true,
+      }).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      const del = requests.find(
+        (r) => r.method === "DELETE" && r.url.includes(DELETE_OBJECT("private")),
+      );
+      expect(del?.body).toEqual({ prefixes: ["abstract.pdf", "docs/readme.md"] });
+    });
+  });
+
+  it.live("echoes the confirmation and deletes with --yes", () => {
+    const { layer, out } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      yes: true,
+      routes: [{ method: "DELETE", match: DELETE_OBJECT("private"), body: [{ name: "a.pdf" }] }],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageRm({
+        files: ["ss:///private/a.pdf"],
+        recursive: false,
+        linked: true,
+        local: true,
+      }).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      expect(out.stderrText).toContain("Confirm deleting files in bucket");
+      expect(out.stderrText).toContain("[y/N] y");
+      expect(out.stderrText).toContain("Deleting objects: [a.pdf]");
+    });
+  });
+
+  it.live("skips the bucket when the confirmation is declined", () => {
+    const { layer, requests } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      confirm: [false],
+      routes: [{ method: "DELETE", match: DELETE_OBJECT("private"), body: [] }],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageRm({
+        files: ["ss:///private/a.pdf"],
+        recursive: false,
+        linked: true,
+        local: true,
+      }).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      expect(requests.some((r) => r.method === "DELETE")).toBe(false);
+    });
+  });
+
+  it.live("uses the default (no) when non-interactive and skips deletion", () => {
+    const { layer, requests } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      format: "json",
+      routes: [{ method: "DELETE", match: DELETE_OBJECT("private"), body: [] }],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageRm({
+        files: ["ss:///private/a.pdf"],
+        recursive: false,
+        linked: true,
+        local: true,
+      }).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      expect(requests.some((r) => r.method === "DELETE")).toBe(false);
+    });
+  });
+
+  it.live("chunks explicit deletes by the storage API limit (1000)", () => {
+    const files = Array.from({ length: 1001 }, (_, i) => `ss:///private/file-${i}.txt`);
+    const { layer, requests } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      yes: true,
+      routes: [
+        {
+          method: "DELETE",
+          match: DELETE_OBJECT("private"),
+          when: (b) => prefixCount(b) === 1000,
+          body: [],
+        },
+        {
+          method: "DELETE",
+          match: DELETE_OBJECT("private"),
+          when: (b) => prefixCount(b) === 1,
+          body: [],
+        },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageRm({
+        files,
+        recursive: false,
+        linked: true,
+        local: true,
+      }).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      const deletes = requests.filter(
+        (r) => r.method === "DELETE" && r.url.includes(DELETE_OBJECT("private")),
+      );
+      expect(deletes).toHaveLength(2);
+      expect(prefixCount(deletes[0]?.body)).toBe(1000);
+      expect(prefixCount(deletes[1]?.body)).toBe(1);
+    });
+  });
+
+  it.live("fails with missing bucket when a path targets the root", () => {
+    const { layer, requests } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageRm({
+        files: ["ss:///"],
+        recursive: false,
+        linked: true,
+        local: true,
+      }).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isFailure(exit)).toBe(true);
+      expect(JSON.stringify(exit)).toContain("You must specify a bucket to delete.");
+      expect(requests).toHaveLength(0);
+    });
+  });
+
+  it.live("requires -r to delete a directory prefix", () => {
+    const { layer, requests } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageRm({
+        files: ["ss:///private/"],
+        recursive: false,
+        linked: true,
+        local: true,
+      }).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isFailure(exit)).toBe(true);
+      expect(JSON.stringify(exit)).toContain("You must specify -r flag to delete directories.");
+      expect(requests).toHaveLength(0);
+    });
+  });
+
+  it.live("requires -r when no paths are given", () => {
+    const { layer } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageRm({
+        files: [],
+        recursive: false,
+        linked: true,
+        local: true,
+      }).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isFailure(exit)).toBe(true);
+      expect(JSON.stringify(exit)).toContain("You must specify -r flag to delete directories.");
+    });
+  });
+
+  it.live("with -r and no paths, clears and deletes every bucket", () => {
+    const { layer, out, requests } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      yes: true,
+      routes: [
+        { method: "GET", match: BUCKET, body: [{ name: "b1", id: "b1" }] },
+        { method: "DELETE", match: DELETE_OBJECT("b1"), body: [] },
+        { method: "POST", match: LIST("b1"), body: [] },
+        { method: "DELETE", match: DELETE_BUCKET("b1"), body: { message: "Successfully deleted" } },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageRm({
+        files: [],
+        recursive: true,
+        linked: true,
+        local: true,
+      }).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      expect(out.stderrText).toContain("Deleting bucket: b1");
+      expect(
+        requests.some((r) => r.method === "DELETE" && r.url.includes(DELETE_BUCKET("b1"))),
+      ).toBe(true);
+    });
+  });
+
+  it.live("recursively deletes a directory and tolerates a missing bucket on delete", () => {
+    const { layer, out } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      yes: true,
+      routes: [
+        // explicit delete of the whole-bucket arg
+        { method: "DELETE", match: DELETE_OBJECT("test"), body: [] },
+        // recursive walk: empty
+        { method: "POST", match: LIST("test"), body: [] },
+        // delete the now-empty bucket → 404 tolerated
+        {
+          method: "DELETE",
+          match: DELETE_BUCKET("test"),
+          status: 404,
+          body: { error: "Bucket not found" },
+        },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageRm({
+        files: ["ss:///test"],
+        recursive: true,
+        linked: true,
+        local: true,
+      }).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      expect(out.stderrText).toContain("Bucket not found: test");
+    });
+  });
+
+  it.live("recursively deletes a nested directory tree", () => {
+    const { layer, requests } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      yes: true,
+      routes: [
+        // explicit delete of the "dir" prefix → not removed (it's a directory)
+        {
+          method: "DELETE",
+          match: DELETE_OBJECT("private"),
+          when: (b) => prefixCount(b) === 1 && (b as { prefixes: string[] }).prefixes[0] === "dir",
+          body: [],
+        },
+        // walk "dir/": a subdir + a file
+        {
+          method: "POST",
+          match: LIST("private"),
+          when: (b) => (b as { prefix?: string }).prefix === "dir/",
+          body: [
+            { name: "sub", id: null },
+            { name: "f.txt", id: "fi" },
+          ],
+        },
+        // delete the file at this level
+        {
+          method: "DELETE",
+          match: DELETE_OBJECT("private"),
+          when: (b) => (b as { prefixes: string[] }).prefixes.includes("dir/f.txt"),
+          body: [{ name: "dir/f.txt" }],
+        },
+        // descend into dir/sub/
+        {
+          method: "POST",
+          match: LIST("private"),
+          when: (b) => (b as { prefix?: string }).prefix === "dir/sub/",
+          body: [{ name: "g.txt", id: "gi" }],
+        },
+        {
+          method: "DELETE",
+          match: DELETE_OBJECT("private"),
+          when: (b) => (b as { prefixes: string[] }).prefixes.includes("dir/sub/g.txt"),
+          body: [{ name: "dir/sub/g.txt" }],
+        },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageRm({
+        files: ["ss:///private/dir"],
+        recursive: true,
+        linked: true,
+        local: true,
+      }).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      expect(
+        requests.some(
+          (r) =>
+            r.method === "DELETE" &&
+            (r.body as { prefixes?: string[] }).prefixes?.includes("dir/sub/g.txt"),
+        ),
+      ).toBe(true);
+    });
+  });
+
+  it.live("deletes a now-empty bucket and prints its success message", () => {
+    const { layer, out } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      yes: true,
+      routes: [
+        { method: "DELETE", match: DELETE_OBJECT("test"), body: [] },
+        { method: "POST", match: LIST("test"), body: [] },
+        {
+          method: "DELETE",
+          match: DELETE_BUCKET("test"),
+          body: { message: "Successfully deleted" },
+        },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageRm({
+        files: ["ss:///test"],
+        recursive: true,
+        linked: true,
+        local: true,
+      }).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      expect(out.stderrText).toContain("Deleting bucket: test");
+      expect(out.stderrText).toContain("Successfully deleted");
+    });
+  });
+
+  it.live("fails with Object not found for an empty recursive directory", () => {
+    const { layer } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      yes: true,
+      routes: [
+        { method: "DELETE", match: DELETE_OBJECT("private"), body: [] },
+        { method: "POST", match: LIST("private"), body: [] },
+      ],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageRm({
+        files: ["ss:///private/dir"],
+        recursive: true,
+        linked: true,
+        local: true,
+      }).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isFailure(exit)).toBe(true);
+      expect(JSON.stringify(exit)).toContain("Object not found: private/dir/");
+    });
+  });
+
+  it.live("emits a { deleted, buckets_deleted } result in json mode", () => {
+    const { layer, out } = setupLegacyStorage(tmp.current, {
+      toml: 'project_id = "test"\n',
+      local: true,
+      yes: true,
+      format: "json",
+      routes: [{ method: "DELETE", match: DELETE_OBJECT("private"), body: [{ name: "a.pdf" }] }],
+    });
+    return Effect.gen(function* () {
+      const exit = yield* legacyStorageRm({
+        files: ["ss:///private/a.pdf"],
+        recursive: false,
+        linked: true,
+        local: true,
+      }).pipe(Effect.provide(layer), Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+      const success = out.messages.find((m) => m.type === "success");
+      expect(success?.data?.["deleted"]).toEqual(["a.pdf"]);
+      expect(success?.data?.["buckets_deleted"]).toEqual([]);
+    });
+  });
+});
diff --git a/apps/cli/src/legacy/commands/storage/storage.command.ts b/apps/cli/src/legacy/commands/storage/storage.command.ts
index 5f9f06bf67..2ada88a7b5 100644
--- a/apps/cli/src/legacy/commands/storage/storage.command.ts
+++ b/apps/cli/src/legacy/commands/storage/storage.command.ts
@@ -7,6 +7,9 @@ import { legacyStorageRmCommand } from "./rm/rm.command.ts";
 export const legacyStorageCommand = Command.make("storage").pipe(
   Command.withDescription("Manage Supabase Storage objects."),
   Command.withShortDescription("Manage Supabase Storage objects"),
+  // `--linked`/`--local` are declared per-leaf (see `storage.flags.ts`), not as
+  // group scoped globals, because Effect CLI requires global-flag names to be
+  // unique tree-wide and `seed` already owns `linked`/`local`.
   Command.withSubcommands([
     legacyStorageLsCommand,
     legacyStorageCpCommand,
diff --git a/apps/cli/src/legacy/commands/storage/storage.e2e.test.ts b/apps/cli/src/legacy/commands/storage/storage.e2e.test.ts
new file mode 100644
index 0000000000..c3e814400d
--- /dev/null
+++ b/apps/cli/src/legacy/commands/storage/storage.e2e.test.ts
@@ -0,0 +1,63 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+
+import { runSupabase } from "../../../../tests/helpers/cli.ts";
+
+const E2E_TIMEOUT_MS = 30_000;
+
+/**
+ * Golden-path e2e for the `storage` group: the real compiled-binary surface and
+ * the parser boundary for the persistent `--linked`/`--local` flags. Object
+ * list/copy/move/remove parity is covered by the integration + unit suites
+ * (they don't need a live local stack); these only exercise what the in-process
+ * suites bypass.
+ */
+describe("supabase storage (legacy)", () => {
+  let projectDir: string;
+
+  beforeAll(() => {
+    projectDir = mkdtempSync(join(tmpdir(), "supabase-storage-e2e-"));
+    mkdirSync(join(projectDir, "supabase"), { recursive: true });
+    writeFileSync(join(projectDir, "supabase", "config.toml"), 'project_id = "test"\n');
+  });
+
+  afterAll(() => {
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  test("lists the four subcommands in --help", { timeout: E2E_TIMEOUT_MS }, async () => {
+    const { exitCode, stdout } = await runSupabase(["storage", "--help"], {
+      entrypoint: "legacy",
+      cwd: projectDir,
+    });
+    expect(exitCode).toBe(0);
+    for (const sub of ["ls", "cp", "mv", "rm"]) {
+      expect(stdout).toContain(sub);
+    }
+  });
+
+  test("rejects passing both --local and --linked", { timeout: E2E_TIMEOUT_MS }, async () => {
+    const { exitCode, stdout, stderr } = await runSupabase(
+      ["storage", "ls", "--local", "--linked", "ss:///"],
+      { entrypoint: "legacy", cwd: projectDir },
+    );
+    expect(exitCode).toBe(1);
+    expect(`${stdout}${stderr}`).toContain(
+      "if any flags in the group [linked local] are set none of the others can be",
+    );
+  });
+
+  test("accepts --local after the subcommand token", { timeout: E2E_TIMEOUT_MS }, async () => {
+    // `--linked`/`--local` are per-leaf flags (Effect CLI requires unique
+    // global-flag names tree-wide and `seed` owns them), so they follow the
+    // subcommand. There's no live local stack here, so the command fails to
+    // connect — but it must PARSE (no "Unrecognized flag").
+    const { stdout, stderr } = await runSupabase(["storage", "ls", "ss:///", "--local"], {
+      entrypoint: "legacy",
+      cwd: projectDir,
+    });
+    expect(`${stdout}${stderr}`).not.toContain("Unrecognized flag");
+  });
+});
diff --git a/apps/cli/src/legacy/commands/storage/storage.errors.ts b/apps/cli/src/legacy/commands/storage/storage.errors.ts
new file mode 100644
index 0000000000..af87bd9059
--- /dev/null
+++ b/apps/cli/src/legacy/commands/storage/storage.errors.ts
@@ -0,0 +1,137 @@
+import { Data } from "effect";
+
+import { legacyAqua } from "../../shared/legacy-colors.ts";
+
+/**
+ * Domain errors for `supabase storage ls/cp/mv/rm`, mirroring the Go error paths
+ * in `internal/storage/{client,ls,cp,mv,rm}`. Each `message` byte-matches the Go
+ * CLI's stderr text.
+ *
+ * The Storage gateway errors (`LegacyStorageGateway{Network,Status}Error`) and
+ * credential-derivation errors live in the shared modules
+ * `legacy/shared/legacy-storage-gateway.errors.ts` and
+ * `legacy/shared/legacy-storage-credentials.errors.ts`; the url-parse failures
+ * are thrown by `legacy/shared/legacy-storage-url.ts` and mapped here.
+ */
+
+/** `client.ErrInvalidURL` (`internal/storage/client/scheme.go:12`). */
+export class LegacyStorageInvalidUrlError extends Data.TaggedError("LegacyStorageInvalidUrlError")<{
+  readonly message: string;
+}> {
+  constructor() {
+    super({ message: "URL must match pattern ss:///bucket/[prefix]" });
+  }
+}
+
+/**
+ * A `url.Parse` failure, wrapped like Go's
+ * `errors.Errorf("failed to parse … url: %w", err)`. The `message` already
+ * contains the full `failed to parse storage url: parse "…": …` text.
+ */
+export class LegacyStorageUrlParseError extends Data.TaggedError("LegacyStorageUrlParseError")<{
+  readonly message: string;
+}> {}
+
+/**
+ * `cp`'s local→local branch (`internal/storage/cp/cp.go:59-60`). Go sets
+ * `utils.CmdSuggestion` to the aqua `cp -r` hint, printed verbatim after the
+ * error — the legacy text error renderer prints `suggestion` the same way.
+ */
+export class LegacyStorageUnsupportedOperationError extends Data.TaggedError(
+  "LegacyStorageUnsupportedOperationError",
+)<{
+  readonly message: string;
+  readonly suggestion: string;
+}> {
+  constructor() {
+    super({
+      message: "Unsupported operation",
+      suggestion: `Run ${legacyAqua("cp -r <src> <dst>")} to copy between local directories.`,
+    });
+  }
+}
+
+/** `cp`'s remote→remote branch (`internal/storage/cp/cp.go:57`). */
+export class LegacyStorageCopyBetweenBucketsError extends Data.TaggedError(
+  "LegacyStorageCopyBetweenBucketsError",
+)<{
+  readonly message: string;
+}> {
+  constructor() {
+    super({ message: "Copying between buckets is not supported" });
+  }
+}
+
+/** `mv`'s cross-bucket branch (`internal/storage/mv/mv.go:19,38`). */
+export class LegacyStorageUnsupportedMoveError extends Data.TaggedError(
+  "LegacyStorageUnsupportedMoveError",
+)<{
+  readonly message: string;
+}> {
+  constructor() {
+    super({ message: "Moving between buckets is unsupported" });
+  }
+}
+
+/** `mv`'s both-root branch (`internal/storage/mv/mv.go:20,35`). */
+export class LegacyStorageMissingPathError extends Data.TaggedError(
+  "LegacyStorageMissingPathError",
+)<{
+  readonly message: string;
+}> {
+  constructor() {
+    super({ message: "You must specify an object path" });
+  }
+}
+
+/** `rm`'s root-arg branch (`internal/storage/rm/rm.go:21,41`). */
+export class LegacyStorageMissingBucketError extends Data.TaggedError(
+  "LegacyStorageMissingBucketError",
+)<{
+  readonly message: string;
+}> {
+  constructor() {
+    super({ message: "You must specify a bucket to delete." });
+  }
+}
+
+/** `rm`'s directory-without-`-r` branch (`internal/storage/rm/rm.go:22,44,53`). */
+export class LegacyStorageMissingFlagError extends Data.TaggedError(
+  "LegacyStorageMissingFlagError",
+)<{
+  readonly message: string;
+}> {
+  constructor() {
+    super({ message: "You must specify -r flag to delete directories." });
+  }
+}
+
+/**
+ * `Object not found: <path>` — `cp` recursive download with no objects
+ * (`cp.go:94`), `mv` recursive with no objects (`mv.go:85`), `rm` recursive on
+ * an empty prefix (`rm.go:114`).
+ */
+export class LegacyStorageObjectNotFoundError extends Data.TaggedError(
+  "LegacyStorageObjectNotFoundError",
+)<{
+  readonly message: string;
+}> {
+  constructor(path: string) {
+    super({ message: `Object not found: ${path}` });
+  }
+}
+
+/** `failed to read file:` / `failed to create file:` (`pkg/storage/objects.go`). */
+export class LegacyStorageFileError extends Data.TaggedError("LegacyStorageFileError")<{
+  readonly message: string;
+}> {}
+
+/**
+ * Both `--linked` and `--local` set, reproducing cobra's
+ * `MarkFlagsMutuallyExclusive("linked", "local")` (`apps/cli-go/cmd/storage.go:99`).
+ */
+export class LegacyStorageMutuallyExclusiveFlagsError extends Data.TaggedError(
+  "LegacyStorageMutuallyExclusiveFlagsError",
+)<{
+  readonly message: string;
+}> {}
diff --git a/apps/cli/src/legacy/commands/storage/storage.flags.ts b/apps/cli/src/legacy/commands/storage/storage.flags.ts
new file mode 100644
index 0000000000..52645ea177
--- /dev/null
+++ b/apps/cli/src/legacy/commands/storage/storage.flags.ts
@@ -0,0 +1,54 @@
+import { Effect } from "effect";
+import { Flag } from "effect/unstable/cli";
+
+import { legacyChangedLinkedLocalFlags } from "../../shared/legacy-db-target-flags.ts";
+import { LegacyStorageMutuallyExclusiveFlagsError } from "./storage.errors.ts";
+
+/**
+ * `--linked` / `--local` mirror Go's `storageCmd.PersistentFlags()`
+ * (`apps/cli-go/cmd/storage.go:96-99`): `--linked` defaults to `true`, `--local`
+ * to `false`, and the two are mutually exclusive. The routing reads the **value**
+ * of `--local` (Go's `GetBool("local")`, `storage.go:21-32`): when true the
+ * project ref is cleared (local stack), otherwise the linked path resolves it.
+ *
+ * These are declared **per-leaf** rather than as `storage`-group scoped globals
+ * because Effect CLI requires global-flag names to be unique across the whole
+ * command tree (`Command.runWith` builds one registry from every declared
+ * global), and `seed` already owns scoped globals named `linked`/`local` with
+ * different defaults/descriptions. The only behavioural cost vs Go's persistent
+ * flags is that `--linked`/`--local` must follow the subcommand token
+ * (`storage ls --local`, not `storage --local ls`) — the same shape the `db`
+ * family uses for its per-leaf `--linked`/`--local`.
+ */
+export const LegacyStorageLinkedFlagDef = Flag.boolean("linked").pipe(
+  Flag.withDescription("Connects to Storage API of the linked project."),
+  Flag.withDefault(true),
+);
+
+export const LegacyStorageLocalFlagDef = Flag.boolean("local").pipe(
+  Flag.withDescription("Connects to Storage API of the local database."),
+);
+
+/** Changed `--linked`/`--local` set (cobra `pflag.Changed`), for the exclusivity check. */
+export function legacyStorageChangedTargetFlags(
+  args: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+  return legacyChangedLinkedLocalFlags(args);
+}
+
+/**
+ * Reproduce cobra's `MarkFlagsMutuallyExclusive("linked", "local")`
+ * (`apps/cli-go/cmd/storage.go:99`). Go rejects this at flag validation — before
+ * `RunE`/`PersistentPostRun` — so it must NOT emit `cli_command_executed`; each
+ * leaf calls this BEFORE `withLegacyCommandInstrumentation`.
+ */
+export const legacyAssertStorageTargetsExclusive = Effect.fnUntraced(function* (
+  args: ReadonlyArray<string>,
+) {
+  const setFlags = legacyStorageChangedTargetFlags(args);
+  if (setFlags.length > 1) {
+    return yield* new LegacyStorageMutuallyExclusiveFlagsError({
+      message: `if any flags in the group [linked local] are set none of the others can be; [${setFlags.join(" ")}] were all set`,
+    });
+  }
+});
diff --git a/apps/cli/src/legacy/commands/storage/storage.flags.unit.test.ts b/apps/cli/src/legacy/commands/storage/storage.flags.unit.test.ts
new file mode 100644
index 0000000000..218c1dfbe8
--- /dev/null
+++ b/apps/cli/src/legacy/commands/storage/storage.flags.unit.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, Exit } from "effect";
+
+import {
+  legacyAssertStorageTargetsExclusive,
+  legacyStorageChangedTargetFlags,
+} from "./storage.flags.ts";
+
+describe("legacyStorageChangedTargetFlags", () => {
+  it("detects neither when no target flag is present", () => {
+    expect(legacyStorageChangedTargetFlags(["storage", "ls", "ss:///"])).toEqual([]);
+  });
+
+  it("detects --linked and --local in cobra's sorted order", () => {
+    expect(legacyStorageChangedTargetFlags(["storage", "--local", "--linked", "ls"])).toEqual([
+      "linked",
+      "local",
+    ]);
+  });
+
+  it("treats the negation form as changed", () => {
+    expect(legacyStorageChangedTargetFlags(["storage", "ls", "--no-local"])).toEqual(["local"]);
+  });
+
+  it("does not mistake a value token for a target flag", () => {
+    // `--workdir --linked`: `--linked` is the value of `--workdir`, not a selector.
+    expect(legacyStorageChangedTargetFlags(["storage", "--workdir", "--linked", "ls"])).toEqual([]);
+  });
+
+  it("ignores tokens after the -- sentinel", () => {
+    expect(legacyStorageChangedTargetFlags(["storage", "ls", "--", "--local"])).toEqual([]);
+  });
+
+  it("detects flags given after the subcommand token (persistent globals)", () => {
+    expect(legacyStorageChangedTargetFlags(["storage", "rm", "ss:///b/x", "--local"])).toEqual([
+      "local",
+    ]);
+  });
+});
+
+describe("legacyAssertStorageTargetsExclusive", () => {
+  it("rejects passing both --linked and --local (byte-exact cobra message)", () =>
+    Effect.gen(function* () {
+      const exit = yield* legacyAssertStorageTargetsExclusive([
+        "storage",
+        "--linked",
+        "--local",
+        "ls",
+      ]).pipe(Effect.exit);
+      expect(Exit.isFailure(exit)).toBe(true);
+      expect(JSON.stringify(exit)).toContain(
+        "if any flags in the group [linked local] are set none of the others can be; [linked local] were all set",
+      );
+    }));
+
+  it("accepts only --local", () =>
+    Effect.gen(function* () {
+      const exit = yield* legacyAssertStorageTargetsExclusive(["storage", "--local", "ls"]).pipe(
+        Effect.exit,
+      );
+      expect(Exit.isSuccess(exit)).toBe(true);
+    }));
+
+  it("accepts neither flag", () =>
+    Effect.gen(function* () {
+      const exit = yield* legacyAssertStorageTargetsExclusive(["storage", "ls"]).pipe(Effect.exit);
+      expect(Exit.isSuccess(exit)).toBe(true);
+    }));
+});
diff --git a/apps/cli/src/legacy/commands/storage/storage.frame.ts b/apps/cli/src/legacy/commands/storage/storage.frame.ts
new file mode 100644
index 0000000000..f4d5fd15f9
--- /dev/null
+++ b/apps/cli/src/legacy/commands/storage/storage.frame.ts
@@ -0,0 +1,135 @@
+import {
+  loadProjectConfig,
+  type LoadProjectConfigOptions,
+  ProjectConfigSchema,
+  type ProjectConfig,
+} from "@supabase/config";
+import { Effect, Schema } from "effect";
+import { FetchHttpClient } from "effect/unstable/http";
+
+import {
+  legacyResolveStorageCredentials,
+  legacyStorageGatewayFetch,
+} from "../../shared/legacy-storage-credentials.ts";
+import {
+  legacyMakeStorageGateway,
+  type LegacyStorageGateway,
+} from "../../shared/legacy-storage-gateway.ts";
+import {
+  LegacyGoUrlParseError,
+  LegacyStorageUrlPatternError,
+  legacyParseStorageUrl,
+} from "../../shared/legacy-storage-url.ts";
+import { LegacyStorageConfigError } from "../../shared/legacy-storage-credentials.errors.ts";
+import { LegacyStorageInvalidUrlError, LegacyStorageUrlParseError } from "./storage.errors.ts";
+
+/**
+ * Shared plumbing for the four `storage` subcommands. Each handler resolves the
+ * project ref (the value of `--local` decides local vs linked, mirroring Go's
+ * `storage.go:21-32`), then uses these helpers for the parts Go shares via
+ * `utils.Config` + `client.NewStorageAPI`.
+ */
+
+const decodeDefaultProjectConfig = Schema.decodeUnknownSync(ProjectConfigSchema);
+
+interface LegacyLoadedStorageConfig {
+  readonly config: ProjectConfig;
+  readonly document: Record<string, unknown> | undefined;
+  readonly appliedRemote: string | undefined;
+}
+
+/**
+ * Load `supabase/config.toml`, mirroring Go's always-loaded `utils.Config`
+ * (DQ-4): a parse failure aborts (`LegacyStorageConfigError`); a missing file
+ * falls back to the embedded defaults (Go's package-global config, initialized
+ * to defaults, with `config.Load` a no-op on a missing file). When a
+ * `[remotes.<name>]` block matches the linked ref, `appliedRemote` carries its
+ * name so the caller can print Go's `Loading config override:` line.
+ */
+export const legacyLoadStorageConfig = Effect.fnUntraced(function* (
+  workdir: string,
+  projectRef: string,
+) {
+  const loadOptions: LoadProjectConfigOptions | undefined =
+    projectRef !== "" ? { projectRef } : undefined;
+  const loaded = yield* loadProjectConfig(workdir, loadOptions).pipe(
+    Effect.catchTag(
+      "ProjectConfigParseError",
+      (cause) =>
+        new LegacyStorageConfigError({
+          message: `failed to parse supabase/config.toml: ${String(cause.cause)}`,
+        }),
+    ),
+  );
+  if (loaded === null) {
+    return {
+      config: decodeDefaultProjectConfig({}),
+      document: undefined,
+      appliedRemote: undefined,
+    } satisfies LegacyLoadedStorageConfig;
+  }
+  return {
+    config: loaded.config,
+    document: loaded.document,
+    appliedRemote: loaded.appliedRemote,
+  } satisfies LegacyLoadedStorageConfig;
+});
+
+/**
+ * Resolve Storage credentials and run `body` against a freshly-built gateway,
+ * with the `FetchHttpClient.Fetch` override applied to the gateway calls only
+ * (CA-trusting for a local https gateway, plain `globalThis.fetch` otherwise).
+ *
+ * The credential lookup (the `--linked` api-keys call) runs BEFORE the override
+ * scope, so it still honors `--dns-resolver https` through the Management API
+ * client — mirroring Go, where Storage uses `status.NewKongClient` /
+ * `http.DefaultClient` while `tenant.GetApiKeys` uses the DoH-wrapped client.
+ *
+ * `legacyMakeStorageGateway` only constructs the client object (no network), so
+ * building it inside the override scope is fine; the override is read per request
+ * from the fiber context when a gateway call executes.
+ */
+export const legacyConnectStorageGateway = <E, R>(
+  opts: { readonly projectRef: string; readonly config: ProjectConfig; readonly userAgent: string },
+  body: (gateway: LegacyStorageGateway) => Effect.Effect<void, E, R>,
+) =>
+  Effect.gen(function* () {
+    const credentials = yield* legacyResolveStorageCredentials({
+      projectRef: opts.projectRef,
+      config: opts.config,
+    });
+    const gatewayOps = Effect.gen(function* () {
+      const gateway = yield* legacyMakeStorageGateway({
+        baseUrl: credentials.baseUrl,
+        apiKey: credentials.apiKey,
+        userAgent: opts.userAgent,
+      });
+      return yield* body(gateway);
+    });
+    return yield* gatewayOps.pipe(
+      Effect.provideService(
+        FetchHttpClient.Fetch,
+        legacyStorageGatewayFetch(credentials.localKongCa),
+      ),
+    );
+  });
+
+/**
+ * Go `client.ParseStorageURL` as an Effect: returns the object path or fails
+ * with the tagged `LegacyStorageInvalidUrlError` (pattern mismatch) /
+ * `LegacyStorageUrlParseError` (url-parse failure, wrapped like Go's
+ * `failed to parse storage url: %w`). Used by `ls`, `mv`, and `rm`; `cp` parses
+ * `src`/`dst` with `legacyGoUrlParse` directly (it branches on the scheme and
+ * wraps as `failed to parse src url` / `failed to parse dst url`).
+ */
+export const legacyParseStorageUrlEffect = (objectUrl: string) =>
+  Effect.try({
+    try: () => legacyParseStorageUrl(objectUrl),
+    catch: (cause) => {
+      if (cause instanceof LegacyStorageUrlPatternError) {
+        return new LegacyStorageInvalidUrlError();
+      }
+      const message = cause instanceof LegacyGoUrlParseError ? cause.message : String(cause);
+      return new LegacyStorageUrlParseError({ message: `failed to parse storage url: ${message}` });
+    },
+  });
diff --git a/apps/cli/src/legacy/commands/storage/storage.iterate.ts b/apps/cli/src/legacy/commands/storage/storage.iterate.ts
new file mode 100644
index 0000000000..279ea435bb
--- /dev/null
+++ b/apps/cli/src/legacy/commands/storage/storage.iterate.ts
@@ -0,0 +1,126 @@
+import { Effect } from "effect";
+
+import { Output } from "../../../shared/output/output.service.ts";
+import type { LegacyStorageGatewayError } from "../../shared/legacy-storage-gateway.errors.ts";
+import {
+  LEGACY_PAGE_LIMIT,
+  type LegacyStorageGateway,
+} from "../../shared/legacy-storage-gateway.ts";
+import { legacyGoPathSplit, legacySplitBucketPrefix } from "../../shared/legacy-storage-url.ts";
+
+/**
+ * Pagination + BFS traversal shared by `storage ls/cp/mv/rm`, ported 1:1 from
+ * `internal/storage/ls/ls.go`. The `callback` receives each entry name (or full
+ * path, for the recursive variant); a directory entry has a trailing `/`. Errors
+ * from the gateway or the callback short-circuit, exactly as Go's loop returns
+ * the first error.
+ *
+ * The `Loading page:` notice (Go `fmt.Fprintln(os.Stderr, "Loading page:", N)`)
+ * is emitted only in text mode — json/stream-json consumers don't want the
+ * pagination noise on stderr.
+ */
+
+/**
+ * Go `ls.IterateStoragePaths` (`ls.go:44-82`): when the path resolves to the
+ * bucket root, list buckets filtered by the (possibly empty) bucket prefix;
+ * otherwise page through objects under the prefix.
+ */
+export const legacyIterateStoragePaths = <E>(
+  gateway: LegacyStorageGateway,
+  output: typeof Output.Service,
+  remotePath: string,
+  callback: (objectName: string) => Effect.Effect<void, E>,
+): Effect.Effect<void, LegacyStorageGatewayError | E> =>
+  Effect.gen(function* () {
+    const [bucket, prefix] = legacySplitBucketPrefix(remotePath);
+    if (bucket.length === 0 || (prefix.length === 0 && !remotePath.endsWith("/"))) {
+      const buckets = yield* gateway.listBuckets();
+      for (const b of buckets) {
+        if (b.name.startsWith(bucket)) {
+          yield* callback(`${b.name}/`);
+        }
+      }
+      return;
+    }
+    let pages = 1;
+    for (let page = 0; page < pages; page++) {
+      const objects = yield* gateway.listObjects(bucket, prefix, page);
+      for (const object of objects) {
+        yield* callback(object.isDir ? `${object.name}/` : object.name);
+      }
+      if (objects.length === LEGACY_PAGE_LIMIT) {
+        if (output.format === "text") {
+          yield* output.raw(`Loading page: ${pages}\n`, "stderr");
+        }
+        pages++;
+      }
+    }
+  });
+
+/**
+ * Go `ls.ListStoragePaths` (`ls.go:35-42`): collect every entry name under the
+ * path into an array.
+ */
+export const legacyListStoragePaths = (
+  gateway: LegacyStorageGateway,
+  output: typeof Output.Service,
+  remotePath: string,
+): Effect.Effect<ReadonlyArray<string>, LegacyStorageGatewayError> =>
+  Effect.gen(function* () {
+    const result: Array<string> = [];
+    yield* legacyIterateStoragePaths(gateway, output, remotePath, (objectName) =>
+      Effect.sync(() => {
+        result.push(objectName);
+      }),
+    );
+    return result;
+  });
+
+/**
+ * Go `ls.IterateStoragePathsAll` (`ls.go:94-136`): BFS over the directory tree
+ * (LIFO queue), invoking `callback` with each object's full path. An empty
+ * bucket is reported as `<bucket>/`.
+ */
+export const legacyIterateStoragePathsAll = <E>(
+  gateway: LegacyStorageGateway,
+  output: typeof Output.Service,
+  remotePath: string,
+  callback: (objectPath: string) => Effect.Effect<void, E>,
+): Effect.Effect<void, LegacyStorageGatewayError | E> =>
+  Effect.gen(function* () {
+    const basePath = remotePath.endsWith("/") ? remotePath : legacyGoPathSplit(remotePath)[0];
+    const dirQueue: Array<string> = [];
+
+    yield* legacyIterateStoragePaths(gateway, output, remotePath, (objectName) =>
+      Effect.gen(function* () {
+        const objectPath = basePath + objectName;
+        if (objectName.endsWith("/")) {
+          dirQueue.push(objectPath);
+          return;
+        }
+        yield* callback(objectPath);
+      }),
+    );
+
+    while (dirQueue.length > 0) {
+      const dirPath = dirQueue.pop();
+      if (dirPath === undefined) break;
+      let empty = true;
+      yield* legacyIterateStoragePaths(gateway, output, dirPath, (objectName) =>
+        Effect.gen(function* () {
+          empty = false;
+          const objectPath = dirPath + objectName;
+          if (objectName.endsWith("/")) {
+            dirQueue.push(objectPath);
+            return;
+          }
+          yield* callback(objectPath);
+        }),
+      );
+      // Also report empty buckets (Go: a top-level empty bucket → `<bucket>/`).
+      const [bucket, prefix] = legacySplitBucketPrefix(dirPath);
+      if (empty && prefix.length === 0) {
+        yield* callback(`${bucket}/`);
+      }
+    }
+  });
diff --git a/apps/cli/src/legacy/shared/legacy-db-target-flags.ts b/apps/cli/src/legacy/shared/legacy-db-target-flags.ts
index b6c82b1412..8828252880 100644
--- a/apps/cli/src/legacy/shared/legacy-db-target-flags.ts
+++ b/apps/cli/src/legacy/shared/legacy-db-target-flags.ts
@@ -71,6 +71,61 @@ export const VALUE_CONSUMING_SHORT_FLAGS = new Set([
   "o", // --output / -o
 ]);
 
+/**
+ * Detects which of `--linked` / `--local` were explicitly set on the command
+ * line, reproducing cobra's `pflag.Changed` for the `MarkFlagsMutuallyExclusive`
+ * groups on `seedCmd` (`apps/cli-go/cmd/seed.go:32`) and `storageCmd`
+ * (`apps/cli-go/cmd/storage.go:99`). Shared by `seed buckets` and
+ * `storage ls/cp/mv/rm`.
+ *
+ * Effect CLI's parsed flags carry no `Changed` bit, so this re-derives it from
+ * raw argv, skipping value tokens of space-separated value-consuming flags
+ * (`--workdir <path>`, `-o <fmt>`, …) to avoid false positives. The negation
+ * form (`--no-linked`/`--no-local`) counts as changed. Returned in cobra's
+ * alphabetically-sorted order `["linked", "local"]` so the rendered conflict
+ * string matches Go exactly.
+ */
+export function legacyChangedLinkedLocalFlags(args: ReadonlyArray<string>): ReadonlyArray<string> {
+  let linked = false;
+  let local = false;
+  let skipNext = false;
+
+  for (const token of args) {
+    if (skipNext) {
+      skipNext = false;
+      continue;
+    }
+    if (token === "--") break;
+
+    if (token.startsWith("--")) {
+      const eqIdx = token.indexOf("=");
+      const name = eqIdx === -1 ? token.slice(2) : token.slice(2, eqIdx);
+      const isBare = eqIdx === -1;
+      if (name === "linked" || name === "no-linked") {
+        linked = true;
+        continue;
+      }
+      if (name === "local" || name === "no-local") {
+        local = true;
+        continue;
+      }
+      if (isBare && VALUE_CONSUMING_LONG_FLAGS.has(name)) skipNext = true;
+      continue;
+    }
+
+    if (token.startsWith("-") && token.length >= 2 && token.charAt(1) !== "-") {
+      if (token.length === 2 && VALUE_CONSUMING_SHORT_FLAGS.has(token.charAt(1))) {
+        skipNext = true;
+      }
+    }
+  }
+
+  const setFlags: Array<string> = [];
+  if (linked) setFlags.push("linked");
+  if (local) setFlags.push("local");
+  return setFlags;
+}
+
 /**
  * Resolves the DB target selection from raw CLI args.
  *
diff --git a/apps/cli/src/legacy/shared/legacy-prompt-yes-no.ts b/apps/cli/src/legacy/shared/legacy-prompt-yes-no.ts
new file mode 100644
index 0000000000..28a042be28
--- /dev/null
+++ b/apps/cli/src/legacy/shared/legacy-prompt-yes-no.ts
@@ -0,0 +1,32 @@
+import { Effect } from "effect";
+
+import { Output } from "../../shared/output/output.service.ts";
+
+/**
+ * Confirm-or-default prompt mirroring Go's `console.PromptYesNo`
+ * (`apps/cli-go/internal/utils/console.go`), shared by `seed buckets` and
+ * `storage rm`:
+ *  - `--yes`/`SUPABASE_YES` echoes `<label> [Y/n|y/N] y` and returns true even
+ *    on a TTY (Go auto-confirms with the affirmative echo);
+ *  - a real TTY in text mode otherwise prompts with the given default;
+ *  - everything else (non-interactive, json/stream-json) uses the default
+ *    silently.
+ */
+export const legacyPromptYesNo = Effect.fnUntraced(function* (
+  output: typeof Output.Service,
+  yes: boolean,
+  label: string,
+  defaultValue: boolean,
+) {
+  if (yes) {
+    const choices = defaultValue ? "Y/n" : "y/N";
+    yield* output.raw(`${label} [${choices}] y\n`, "stderr");
+    return true;
+  }
+  if (output.format !== "text") {
+    return defaultValue;
+  }
+  return yield* output
+    .promptConfirm(label, { defaultValue })
+    .pipe(Effect.catchTag("NonInteractiveError", () => Effect.succeed(defaultValue)));
+});
diff --git a/apps/cli/src/legacy/shared/legacy-storage-bucket-config.ts b/apps/cli/src/legacy/shared/legacy-storage-bucket-config.ts
new file mode 100644
index 0000000000..1f76e73cc1
--- /dev/null
+++ b/apps/cli/src/legacy/shared/legacy-storage-bucket-config.ts
@@ -0,0 +1,84 @@
+import { ramInBytes } from "./legacy-size-units.ts";
+import type { LegacyUpsertBucketProps } from "./legacy-storage-gateway.ts";
+
+/**
+ * Pure helpers that turn a `[storage.buckets.*]` config entry into the
+ * create/update bucket props the Storage gateway sends. Shared by `seed buckets`
+ * (which seeds every configured bucket) and `storage cp` (which auto-creates a
+ * bucket on a `Bucket not found` upload, reading the same config —
+ * `internal/storage/cp/cp.go:154-160`). Kept free of Effect/services so the
+ * Go-parity rules (size parsing, storage-level inheritance, `public` tri-state)
+ * stay unit-testable.
+ */
+
+/**
+ * Parse a `file_size_limit` config string (e.g. `"50MiB"`) to the int64 byte
+ * count Go sends in the create/update bucket body (`int64(bucket.FileSizeLimit)`,
+ * `pkg/storage/batch.go:38/49`). `@supabase/config` keeps the field as the raw
+ * human-readable string, so the conversion Go performs at config-load happens
+ * here. Throws on an unparseable value (Go aborts config load), which the caller
+ * maps to a config-load error.
+ */
+export function legacyParseFileSizeLimit(sizeStr: string): number {
+  return ramInBytes(sizeStr);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Whether the bucket's TOML entry explicitly declares `key`. Go reads `public`
+ * into a `*bool` and `file_size_limit` into a pointer, so an absent key is
+ * omitted (not the decoded schema default), and that "omitted" signal drives the
+ * `public` tri-state and the storage-level `file_size_limit` inheritance.
+ * `@supabase/config` loses it (decodes to the schema default), so recover
+ * presence from the raw (post-`env()`) document.
+ */
+export function legacyBucketHasKey(
+  document: Record<string, unknown> | undefined,
+  name: string,
+  key: string,
+): boolean {
+  if (document === undefined) return false;
+  const storage = document["storage"];
+  if (!isRecord(storage)) return false;
+  const buckets = storage["buckets"];
+  if (!isRecord(buckets)) return false;
+  const bucket = buckets[name];
+  return isRecord(bucket) && key in bucket;
+}
+
+interface LegacyBucketConfigEntry {
+  readonly public: boolean;
+  readonly file_size_limit: string;
+  readonly allowed_mime_types: ReadonlyArray<string>;
+}
+
+/**
+ * Resolve a bucket's create/update props, mirroring Go's `config.resolve()`
+ * (`pkg/config/config.go:753-756`) + the `sizeInBytes` decode at config-load:
+ *  - an omitted or zero `file_size_limit` inherits the (already-parsed)
+ *    storage-level limit;
+ *  - `public` is the explicit value only when the TOML declares it, else
+ *    `undefined` (Go's `*bool` nil → omitted from the request body).
+ *
+ * Throws on an unparseable bucket `file_size_limit` (the caller maps it to a
+ * config-load error). `storageFileSizeLimitBytes` must already be parsed.
+ */
+export function legacyResolveBucketProps(opts: {
+  readonly document: Record<string, unknown> | undefined;
+  readonly name: string;
+  readonly bucket: LegacyBucketConfigEntry;
+  readonly storageFileSizeLimitBytes: number;
+}): LegacyUpsertBucketProps {
+  const bucketBytes = legacyBucketHasKey(opts.document, opts.name, "file_size_limit")
+    ? legacyParseFileSizeLimit(opts.bucket.file_size_limit)
+    : 0;
+  const fileSizeLimit = bucketBytes === 0 ? opts.storageFileSizeLimitBytes : bucketBytes;
+  return {
+    public: legacyBucketHasKey(opts.document, opts.name, "public") ? opts.bucket.public : undefined,
+    fileSizeLimit,
+    allowedMimeTypes: opts.bucket.allowed_mime_types,
+  };
+}
diff --git a/apps/cli/src/legacy/shared/legacy-storage-bucket-config.unit.test.ts b/apps/cli/src/legacy/shared/legacy-storage-bucket-config.unit.test.ts
new file mode 100644
index 0000000000..31dd1706af
--- /dev/null
+++ b/apps/cli/src/legacy/shared/legacy-storage-bucket-config.unit.test.ts
@@ -0,0 +1,107 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  legacyBucketHasKey,
+  legacyParseFileSizeLimit,
+  legacyResolveBucketProps,
+} from "./legacy-storage-bucket-config.ts";
+
+describe("legacyParseFileSizeLimit", () => {
+  it("parses a human-readable size to bytes", () => {
+    expect(legacyParseFileSizeLimit("50MiB")).toBe(50 * 1024 * 1024);
+  });
+
+  it("returns 0 for a zero limit", () => {
+    expect(legacyParseFileSizeLimit("0")).toBe(0);
+  });
+
+  it("throws on an unparseable value", () => {
+    expect(() => legacyParseFileSizeLimit("not-a-size")).toThrow();
+  });
+
+  it("accepts Go-valid numeral forms (strconv.ParseFloat parity)", () => {
+    expect(legacyParseFileSizeLimit(".5MiB")).toBe(Math.trunc(0.5 * 1024 * 1024));
+    expect(legacyParseFileSizeLimit("1.MiB")).toBe(1024 * 1024);
+    expect(legacyParseFileSizeLimit("1e6")).toBe(1_000_000);
+    expect(legacyParseFileSizeLimit("1_000MiB")).toBe(1000 * 1024 * 1024);
+    expect(legacyParseFileSizeLimit("1_0MiB")).toBe(10 * 1024 * 1024);
+  });
+
+  it("rejects badly-placed underscores (Go literal rule)", () => {
+    expect(() => legacyParseFileSizeLimit("_1000MiB")).toThrow("invalid size");
+    expect(() => legacyParseFileSizeLimit("1__0MiB")).toThrow("invalid size");
+  });
+
+  it("rejects malformed numerals that JS parseFloat would truncate", () => {
+    expect(() => legacyParseFileSizeLimit("1.2.3MiB")).toThrow("invalid size");
+    expect(() => legacyParseFileSizeLimit("1 2MiB")).toThrow("invalid size");
+    expect(() => legacyParseFileSizeLimit("-5MiB")).toThrow("invalid size");
+  });
+
+  it("rejects an overflowing numeral (Go ParseFloat range error)", () => {
+    expect(() => legacyParseFileSizeLimit("1e309")).toThrow("invalid size");
+  });
+});
+
+describe("legacyBucketHasKey", () => {
+  const doc = { storage: { buckets: { docs: { public: true } } } };
+
+  it("detects a declared key", () => {
+    expect(legacyBucketHasKey(doc, "docs", "public")).toBe(true);
+  });
+
+  it("returns false for an omitted key", () => {
+    expect(legacyBucketHasKey(doc, "docs", "file_size_limit")).toBe(false);
+  });
+
+  it("returns false when the document, storage, buckets, or bucket is absent", () => {
+    expect(legacyBucketHasKey(undefined, "docs", "public")).toBe(false);
+    expect(legacyBucketHasKey({}, "docs", "public")).toBe(false);
+    expect(legacyBucketHasKey({ storage: {} }, "docs", "public")).toBe(false);
+    expect(legacyBucketHasKey({ storage: { buckets: {} } }, "docs", "public")).toBe(false);
+  });
+});
+
+describe("legacyResolveBucketProps", () => {
+  const entry = { public: true, file_size_limit: "10MiB", allowed_mime_types: ["image/png"] };
+
+  it("uses the explicit public + parsed file_size_limit when declared", () => {
+    const doc = {
+      storage: { buckets: { media: { public: true, file_size_limit: "10MiB" } } },
+    };
+    expect(
+      legacyResolveBucketProps({
+        document: doc,
+        name: "media",
+        bucket: entry,
+        storageFileSizeLimitBytes: 5 * 1024 * 1024,
+      }),
+    ).toEqual({
+      public: true,
+      fileSizeLimit: 10 * 1024 * 1024,
+      allowedMimeTypes: ["image/png"],
+    });
+  });
+
+  it("inherits the storage-level limit and omits public when both are absent", () => {
+    expect(
+      legacyResolveBucketProps({
+        document: { storage: { buckets: { media: {} } } },
+        name: "media",
+        bucket: { public: false, file_size_limit: "50MiB", allowed_mime_types: [] },
+        storageFileSizeLimitBytes: 5 * 1024 * 1024,
+      }),
+    ).toEqual({ public: undefined, fileSizeLimit: 5 * 1024 * 1024, allowedMimeTypes: [] });
+  });
+
+  it("throws on an unparseable bucket file_size_limit", () => {
+    expect(() =>
+      legacyResolveBucketProps({
+        document: { storage: { buckets: { media: { file_size_limit: "bad" } } } },
+        name: "media",
+        bucket: { public: false, file_size_limit: "bad", allowed_mime_types: [] },
+        storageFileSizeLimitBytes: 0,
+      }),
+    ).toThrow("invalid size");
+  });
+});
diff --git a/apps/cli/src/legacy/shared/legacy-storage-content-type.ts b/apps/cli/src/legacy/shared/legacy-storage-content-type.ts
new file mode 100644
index 0000000000..dbc148fba3
--- /dev/null
+++ b/apps/cli/src/legacy/shared/legacy-storage-content-type.ts
@@ -0,0 +1,133 @@
+import * as nodePath from "node:path";
+
+import { Effect, FileSystem, Option } from "effect";
+
+import { legacyDetectContentType } from "./legacy-detect-content-type.ts";
+
+/**
+ * Upload content-type resolution, ported from Go's `pkg/storage/objects.go`
+ * (`ParseFileOptions` + `UploadObject`) and shared by `seed buckets` and
+ * `storage cp`: run `http.DetectContentType` on the first ≤512 bytes (the bytes
+ * decide), then refine a generic `text/plain` by file extension. So a PNG named
+ * `.txt` stores as `image/png` (bytes win), while a JSON text file refines to
+ * `application/json`.
+ */
+
+// Content-type sniff window: Go reads the first 512 bytes (`io.LimitReader(f, 512)`).
+const LEGACY_SNIFF_LEN = 512;
+
+/**
+ * Read ONLY the first ≤512 bytes of a file for content-type sniffing, mirroring
+ * Go's `io.LimitReader(f, 512)` (`pkg/storage/objects.go:78-79`) — the file is
+ * NOT fully buffered. Returns an empty buffer on EOF or any read error (an
+ * unreadable file then fails at the streaming upload open, so the sniff is moot).
+ */
+export const legacyReadSniffBytes = Effect.fnUntraced(function* (
+  fs: FileSystem.FileSystem,
+  absPath: string,
+) {
+  return yield* Effect.scoped(
+    Effect.gen(function* () {
+      const handle = yield* fs.open(absPath, { flag: "r" });
+      return yield* handle.readAlloc(LEGACY_SNIFF_LEN);
+    }),
+  ).pipe(
+    Effect.map(Option.getOrElse(() => new Uint8Array(0))),
+    Effect.catch(() => Effect.succeed(new Uint8Array(0))),
+  );
+});
+
+/**
+ * Refine a content-type by file extension, but only when it is a generic
+ * `text/plain` (Go's `if strings.Contains(fo.ContentType, "text/plain")` gate,
+ * `objects.go:105-108`). Applied to both the sniffed type and an explicit
+ * `--content-type` value, matching Go's `ParseFileOptions` → `UploadObject` flow.
+ */
+export function legacyRefineUploadContentType(contentType: string, filePath: string): string {
+  if (contentType.includes("text/plain")) {
+    const ext = nodePath.extname(filePath).toLowerCase();
+    const refined = MIME_BY_EXTENSION[ext];
+    if (refined !== undefined && refined !== "") return refined;
+  }
+  return contentType;
+}
+
+/**
+ * Content-type for an uploaded object from its sniffed bytes: detect, then refine
+ * a generic `text/plain` by extension. `sniff` is the first ≤512 bytes.
+ */
+export function legacyContentTypeForUpload(sniff: Uint8Array, filePath: string): string {
+  return legacyRefineUploadContentType(legacyDetectContentType(sniff), filePath);
+}
+
+// Go's built-in `mime` extension table (`mime/type.go` `builtinTypesLower`), used
+// only to refine a generic `text/plain` sniff result. NOTE: Go's
+// `mime.TypeByExtension` also augments this from the OS MIME database
+// (`/etc/mime.types`, the Windows registry), which is host-dependent and not
+// reproduced here — the deterministic built-in table is the faithful baseline.
+const MIME_BY_EXTENSION: Readonly<Record<string, string>> = {
+  ".ai": "application/postscript",
+  ".apk": "application/vnd.android.package-archive",
+  ".apng": "image/apng",
+  ".avif": "image/avif",
+  ".bin": "application/octet-stream",
+  ".bmp": "image/bmp",
+  ".com": "application/octet-stream",
+  ".css": "text/css; charset=utf-8",
+  ".csv": "text/csv; charset=utf-8",
+  ".doc": "application/msword",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".ehtml": "text/html; charset=utf-8",
+  ".eml": "message/rfc822",
+  ".eps": "application/postscript",
+  ".exe": "application/octet-stream",
+  ".flac": "audio/flac",
+  ".gif": "image/gif",
+  ".gz": "application/gzip",
+  ".htm": "text/html; charset=utf-8",
+  ".html": "text/html; charset=utf-8",
+  ".ico": "image/vnd.microsoft.icon",
+  ".ics": "text/calendar; charset=utf-8",
+  ".jfif": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json",
+  ".m4a": "audio/mp4",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".mp3": "audio/mpeg",
+  ".mp4": "video/mp4",
+  ".oga": "audio/ogg",
+  ".ogg": "audio/ogg",
+  ".ogv": "video/ogg",
+  ".opus": "audio/ogg",
+  ".pdf": "application/pdf",
+  ".pjp": "image/jpeg",
+  ".pjpeg": "image/jpeg",
+  ".png": "image/png",
+  ".ppt": "application/vnd.ms-powerpoint",
+  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  ".ps": "application/postscript",
+  ".rdf": "application/rdf+xml",
+  ".rtf": "application/rtf",
+  ".shtml": "text/html; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".text": "text/plain; charset=utf-8",
+  ".tif": "image/tiff",
+  ".tiff": "image/tiff",
+  ".txt": "text/plain; charset=utf-8",
+  ".vtt": "text/vtt; charset=utf-8",
+  ".wasm": "application/wasm",
+  ".wav": "audio/wav",
+  ".webm": "audio/webm",
+  ".webp": "image/webp",
+  ".xbl": "text/xml; charset=utf-8",
+  ".xbm": "image/x-xbitmap",
+  ".xht": "application/xhtml+xml",
+  ".xhtml": "application/xhtml+xml",
+  ".xls": "application/vnd.ms-excel",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ".xml": "text/xml; charset=utf-8",
+  ".xsl": "text/xml; charset=utf-8",
+  ".zip": "application/zip",
+};
diff --git a/apps/cli/src/legacy/shared/legacy-storage-content-type.unit.test.ts b/apps/cli/src/legacy/shared/legacy-storage-content-type.unit.test.ts
new file mode 100644
index 0000000000..712a57833a
--- /dev/null
+++ b/apps/cli/src/legacy/shared/legacy-storage-content-type.unit.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  legacyContentTypeForUpload,
+  legacyRefineUploadContentType,
+} from "./legacy-storage-content-type.ts";
+
+/** Latin-1 byte view of a string fixture. */
+function bytes(s: string): Uint8Array {
+  const out = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i) & 0xff;
+  return out;
+}
+
+describe("legacyContentTypeForUpload", () => {
+  // Go: http.DetectContentType (bytes win) then refine only generic text/plain
+  // by extension via mime.TypeByExtension (objects.go:77-108).
+  it("lets the sniffed bytes win over the extension (PNG named .txt)", () => {
+    const png = bytes("\x89PNG\x0D\x0A\x1A\x0A\x00\x00");
+    expect(legacyContentTypeForUpload(png, "/x/a.txt")).toBe("image/png");
+  });
+
+  it("refines a generic text/plain sniff via the file extension", () => {
+    const text = bytes('{"a":1}'); // sniffs as text/plain
+    expect(legacyContentTypeForUpload(text, "/x/a.json")).toBe("application/json");
+    expect(legacyContentTypeForUpload(text, "/x/a.css")).toBe("text/css; charset=utf-8");
+  });
+
+  it("is case-insensitive on the extension for the text refinement", () => {
+    expect(legacyContentTypeForUpload(bytes("plain text"), "/x/A.JSON")).toBe("application/json");
+  });
+
+  it("keeps text/plain when a text file has no/unknown extension", () => {
+    expect(legacyContentTypeForUpload(bytes("plain text"), "/x/a.unknownext")).toBe(
+      "text/plain; charset=utf-8",
+    );
+    expect(legacyContentTypeForUpload(bytes("plain text"), "/x/noext")).toBe(
+      "text/plain; charset=utf-8",
+    );
+  });
+
+  it("does not refine a non-text sniff result by extension", () => {
+    const svg = bytes('<?xml version="1.0"?><svg></svg>');
+    expect(legacyContentTypeForUpload(svg, "/x/a.svg")).toBe("text/xml; charset=utf-8");
+  });
+
+  it("falls back to application/octet-stream for unrecognized binary content", () => {
+    const blob = bytes("\x00\x01\x02\x03\x04\x05garbage");
+    expect(legacyContentTypeForUpload(blob, "/x/a.bin")).toBe("application/octet-stream");
+  });
+});
+
+describe("legacyRefineUploadContentType", () => {
+  it("refines an explicit text/plain content-type by extension (Go refines the flag too)", () => {
+    expect(legacyRefineUploadContentType("text/plain", "/x/a.json")).toBe("application/json");
+  });
+
+  it("leaves a non-text content-type untouched", () => {
+    expect(legacyRefineUploadContentType("image/png", "/x/a.json")).toBe("image/png");
+  });
+});
diff --git a/apps/cli/src/legacy/shared/legacy-storage-credentials.errors.ts b/apps/cli/src/legacy/shared/legacy-storage-credentials.errors.ts
new file mode 100644
index 0000000000..f6f36d126c
--- /dev/null
+++ b/apps/cli/src/legacy/shared/legacy-storage-credentials.errors.ts
@@ -0,0 +1,45 @@
+import { Data } from "effect";
+
+/**
+ * Errors raised while deriving Storage connection credentials, shared by
+ * `seed buckets` and `storage ls/cp/mv/rm`.
+ *
+ * `LegacyStorageConfigError` covers the config-load-time validations Go runs
+ * before `NewStorageAPI` (`auth.jwt_secret` length, Kong TLS cert/key pairing
+ * and readability). The remaining three mirror Go's `tenant.GetApiKeys` failure
+ * modes on the `--linked` path (`internal/utils/tenant/client.go`).
+ */
+export class LegacyStorageConfigError extends Data.TaggedError("LegacyStorageConfigError")<{
+  readonly message: string;
+}> {}
+
+/**
+ * Raised on `--linked` when the project's api-keys response yields no keys,
+ * mirroring Go's `tenant.GetApiKeys` → `errMissingKey` ("Anon key not found.",
+ * `internal/utils/tenant/client.go:16,80-82`), which aborts before the remote
+ * Storage client is built.
+ */
+export class LegacyStorageMissingApiKeyError extends Data.TaggedError(
+  "LegacyStorageMissingApiKeyError",
+)<{
+  readonly message: string;
+}> {}
+
+/** Transport failure fetching the project's api-keys (`failed to get api keys: <cause>`). */
+export class LegacyStorageApiKeysNetworkError extends Data.TaggedError(
+  "LegacyStorageApiKeysNetworkError",
+)<{
+  readonly message: string;
+}> {}
+
+/**
+ * `GET /v1/projects/{ref}/api-keys?reveal=true` returned a non-200 on a
+ * `--linked` run. Byte-matches Go's `tenant.GetApiKeys` → `ErrAuthToken`,
+ * `"Authorization failed for the access token and project ref pair: " + body`
+ * (`internal/utils/tenant/client.go:15,77-78`).
+ */
+export class LegacyStorageAuthTokenError extends Data.TaggedError("LegacyStorageAuthTokenError")<{
+  readonly status: number;
+  readonly body: string;
+  readonly message: string;
+}> {}
diff --git a/apps/cli/src/legacy/shared/legacy-storage-credentials.ts b/apps/cli/src/legacy/shared/legacy-storage-credentials.ts
new file mode 100644
index 0000000000..0826a7de8f
--- /dev/null
+++ b/apps/cli/src/legacy/shared/legacy-storage-credentials.ts
@@ -0,0 +1,271 @@
+import { KONG_LOCAL_CA_CERT } from "@supabase/config";
+import { defaultJwtSecret, generateJwt } from "@supabase/stack/effect";
+import { Effect, FileSystem, Path } from "effect";
+
+import { LegacyPlatformApiFactory } from "../auth/legacy-platform-api-factory.service.ts";
+import { LegacyCliConfig } from "../config/legacy-cli-config.service.ts";
+import { legacyMapTenantApiKeysError } from "./legacy-get-tenant-api-keys.ts";
+import { legacyGetHostname } from "./legacy-hostname.ts";
+import { legacyExtractServiceKeys } from "./legacy-tenant-keys.ts";
+import {
+  LegacyStorageApiKeysNetworkError,
+  LegacyStorageAuthTokenError,
+  LegacyStorageConfigError,
+  LegacyStorageMissingApiKeyError,
+} from "./legacy-storage-credentials.errors.ts";
+
+/**
+ * Resolves the Storage gateway base URL + service-role key (+ local Kong CA),
+ * mirroring Go's `client.NewStorageAPI` (`internal/storage/client/api.go:15-46`).
+ * Shared by `seed buckets` and `storage ls/cp/mv/rm`.
+ *
+ *  - `projectRef === ""` (local): base URL from `api.external_url` (else
+ *    `<scheme>://<host>:<api.port>`), service-role key derived from
+ *    `auth.{service_role_key,jwt_secret}`, and the Kong CA when the URL is https.
+ *  - remote: base URL `https://<ref>.<projectHost>`; key from
+ *    `SUPABASE_AUTH_SERVICE_ROLE_KEY` else `tenant.GetApiKeys`.
+ *
+ * Requires `LegacyCliConfig` (workdir, projectHost) and — only on the remote
+ * branch — `LegacyPlatformApiFactory` (lazy, so the local path never touches the
+ * Management API).
+ */
+
+/** Structural subset of `@supabase/config`'s ProjectConfig used here. */
+export interface LegacyStorageConfigView {
+  readonly api: {
+    readonly enabled: boolean;
+    readonly external_url?: string;
+    readonly port: number;
+    readonly tls: {
+      readonly enabled: boolean;
+      readonly cert_path?: string;
+      readonly key_path?: string;
+    };
+  };
+  readonly auth: {
+    readonly jwt_secret?: string;
+    readonly service_role_key?: string;
+  };
+}
+
+interface LegacyStorageCredentials {
+  readonly baseUrl: string;
+  readonly apiKey: string;
+  /** The CA PEM to trust for a local https gateway; `undefined` otherwise. */
+  readonly localKongCa: string | undefined;
+}
+
+export const legacyResolveStorageCredentials = Effect.fnUntraced(function* (opts: {
+  readonly projectRef: string;
+  readonly config: LegacyStorageConfigView;
+}) {
+  const cliConfig = yield* LegacyCliConfig;
+
+  if (opts.projectRef !== "") {
+    const baseUrl = `https://${opts.projectRef}.${cliConfig.projectHost}`;
+    // Go: `viper.IsSet("AUTH_SERVICE_ROLE_KEY")` → use the env-provided key and
+    // skip the tenant lookup (`api.go:19-21`).
+    const envKey = process.env["SUPABASE_AUTH_SERVICE_ROLE_KEY"];
+    if (envKey !== undefined && envKey.length > 0) {
+      return { baseUrl, apiKey: envKey, localKongCa: undefined } satisfies LegacyStorageCredentials;
+    }
+    // Resolve the Management API client lazily so the local path never triggers
+    // auth (`api.go:22` → `tenant.GetApiKeys`).
+    const api = yield* (yield* LegacyPlatformApiFactory).make;
+    const keys = legacyExtractServiceKeys(
+      yield* api.v1.getProjectApiKeys({ ref: opts.projectRef, reveal: true }).pipe(
+        Effect.catch(
+          legacyMapTenantApiKeysError({
+            networkError: LegacyStorageApiKeysNetworkError,
+            statusError: LegacyStorageAuthTokenError,
+          }),
+        ),
+      ),
+    );
+    // Go's `tenant.GetApiKeys` fails with `errMissingKey` ("Anon key not found.")
+    // when the response yields nothing (`client.go:24-26,80-82`).
+    if (keys.anon === "" && keys.serviceRole === "") {
+      return yield* new LegacyStorageMissingApiKeyError({ message: "Anon key not found." });
+    }
+    return {
+      baseUrl,
+      apiKey: keys.serviceRole,
+      localKongCa: undefined,
+    } satisfies LegacyStorageCredentials;
+  }
+
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const baseUrl = resolveLocalBaseUrl(opts.config);
+  const apiKey = yield* resolveLocalServiceRoleKey(opts.config.auth);
+
+  // Go installs `status.NewKongClient` unconditionally for the local client; its
+  // embedded CA only matters for https. `(*api).Validate` resolves cert_path /
+  // key_path and validates the pairing only when `api.enabled && api.tls.enabled`
+  // (`config.go:795,841-861`). Inject a CA whenever the resolved URL is https
+  // (Go derives the scheme from `api.tls.enabled` alone, `config.go:639-642`).
+  let localKongCa: string | undefined;
+  const validatedCa =
+    opts.config.api.enabled && opts.config.api.tls.enabled
+      ? yield* validateLocalKongTls(
+          fs,
+          path,
+          cliConfig.workdir,
+          opts.config.api.tls.cert_path,
+          opts.config.api.tls.key_path,
+        )
+      : undefined;
+  if (baseUrl.startsWith("https:")) {
+    localKongCa = validatedCa ?? KONG_LOCAL_CA_CERT;
+  }
+  return { baseUrl, apiKey, localKongCa } satisfies LegacyStorageCredentials;
+});
+
+/**
+ * Local API URL, mirroring Go's `config.go:634-644` + `misc.go:298`: an explicit
+ * `api.external_url` wins, otherwise `<scheme>://<host>:<port>` where the scheme
+ * follows `api.tls.enabled`, the host is `legacyGetHostname` (Go's
+ * `utils.GetHostname`), and the port is `api.port`.
+ */
+function resolveLocalBaseUrl(config: LegacyStorageConfigView): string {
+  if (config.api.external_url !== undefined && config.api.external_url.length > 0) {
+    return config.api.external_url;
+  }
+  const host = legacyGetHostname();
+  const scheme = config.api.tls.enabled ? "https" : "http";
+  // Go builds host:port with net.JoinHostPort (config.go:636-638), bracketing an
+  // IPv6 host. legacyGetHostname returns the unbracketed host, so bracket here.
+  const hostPort = host.includes(":")
+    ? `[${host}]:${config.api.port}`
+    : `${host}:${config.api.port}`;
+  return `${scheme}://${hostPort}`;
+}
+
+/**
+ * Resolve the service-role key for the local Storage gateway, mirroring Go's
+ * `(*auth).generateAPIKeys` (`pkg/config/apikeys.go:43-63`) + the Viper
+ * `AutomaticEnv`/`SUPABASE_` prefix precedence (`config.go:492-497`):
+ *  - jwt secret: `SUPABASE_AUTH_JWT_SECRET` → `auth.jwt_secret` → `defaultJwtSecret`;
+ *    a resolved secret shorter than 16 chars is rejected;
+ *  - service-role key: `SUPABASE_AUTH_SERVICE_ROLE_KEY` → `auth.service_role_key`
+ *    → sign from the resolved secret.
+ *
+ * Empty checks use length, so an explicit `service_role_key = ""` is regenerated
+ * like Go (not sent as the empty string).
+ */
+const resolveLocalServiceRoleKey = Effect.fnUntraced(function* (auth: {
+  readonly jwt_secret?: string;
+  readonly service_role_key?: string;
+}) {
+  const envSecret = process.env["SUPABASE_AUTH_JWT_SECRET"];
+  const configuredSecret =
+    envSecret !== undefined && envSecret.length > 0 ? envSecret : auth.jwt_secret;
+
+  let jwtSecret: string;
+  if (configuredSecret === undefined || configuredSecret.length === 0) {
+    jwtSecret = defaultJwtSecret;
+  } else if (configuredSecret.length < 16) {
+    return yield* new LegacyStorageConfigError({
+      message: "Invalid config for auth.jwt_secret. Must be at least 16 characters",
+    });
+  } else {
+    jwtSecret = configuredSecret;
+  }
+
+  const envKey = process.env["SUPABASE_AUTH_SERVICE_ROLE_KEY"];
+  const configuredKey = envKey !== undefined && envKey.length > 0 ? envKey : auth.service_role_key;
+  return configuredKey !== undefined && configuredKey.length > 0
+    ? configuredKey
+    : generateJwt(jwtSecret, "service_role");
+});
+
+/**
+ * Validate + resolve the local Kong TLS config, mirroring Go's `(*api).Validate`
+ * (`pkg/config/config.go:845-861`): cert without key (or vice-versa) errors; both
+ * present and readable returns the cert PEM; neither returns the embedded CA.
+ *
+ * Only called when `api.enabled && api.tls.enabled` (Go gates both path
+ * resolution and validation on `c.Api.Enabled`). The CLI uses only the CA cert,
+ * but Go reads the key to validate the pairing, so this mirrors that.
+ */
+const validateLocalKongTls = Effect.fnUntraced(function* (
+  fs: FileSystem.FileSystem,
+  path: Path.Path,
+  workdir: string,
+  certPath: string | undefined,
+  keyPath: string | undefined,
+) {
+  const hasCert = certPath !== undefined && certPath.length > 0;
+  const hasKey = keyPath !== undefined && keyPath.length > 0;
+
+  if (hasCert && !hasKey) {
+    return yield* new LegacyStorageConfigError({
+      message: "Missing required field in config: api.tls.key_path",
+    });
+  }
+  if (hasKey && !hasCert) {
+    return yield* new LegacyStorageConfigError({
+      message: "Missing required field in config: api.tls.cert_path",
+    });
+  }
+
+  if (hasCert) {
+    // Go joins TLS paths unconditionally with the supabase dir — NO IsAbs guard
+    // (config.go:795-801 uses path.Join, which absorbs a leading "/").
+    const absCert = path.join(workdir, "supabase", certPath);
+    const certContent = yield* fs.readFileString(absCert).pipe(
+      Effect.catchTag(
+        "PlatformError",
+        (cause) =>
+          new LegacyStorageConfigError({
+            message: `failed to read TLS cert: ${String(cause.cause ?? cause)}`,
+          }),
+      ),
+    );
+    const absKey = path.join(workdir, "supabase", keyPath!);
+    yield* fs.readFileString(absKey).pipe(
+      Effect.catchTag(
+        "PlatformError",
+        (cause) =>
+          new LegacyStorageConfigError({
+            message: `failed to read TLS key: ${String(cause.cause ?? cause)}`,
+          }),
+      ),
+    );
+    return certContent;
+  }
+
+  return KONG_LOCAL_CA_CERT;
+});
+
+/**
+ * Builds a `typeof globalThis.fetch` that injects `tls.ca` into every request,
+ * trusting the provided CA PEM for HTTPS connections to the local Kong gateway.
+ * Mirrors Go's `newLocalClient` (`internal/storage/client/api.go:30-37`).
+ *
+ * Bun's fetch accepts `{ tls: { ca: string } }` via `BunFetchRequestInit`, which
+ * extends `RequestInit`; no `as` cast is needed.
+ */
+function legacyKongCaFetch(ca: string): typeof globalThis.fetch {
+  const fetchImpl = async (
+    input: string | URL | Request,
+    init?: RequestInit,
+  ): Promise<Response> => {
+    const caInit: BunFetchRequestInit = { ...init, tls: { ca } };
+    return globalThis.fetch(input, caInit);
+  };
+  return Object.assign(fetchImpl, { preconnect: globalThis.fetch.preconnect });
+}
+
+/**
+ * The `FetchHttpClient.Fetch` override to provide for Storage gateway calls: a
+ * CA-trusting fetch for a local https gateway, plain `globalThis.fetch`
+ * otherwise. Storage calls never use DoH in Go (`newLocalClient` /
+ * `newRemoteClient` use `status.NewKongClient` / `http.DefaultClient`), so the
+ * DoH-wrapped shared client is always overridden at the gateway scope.
+ */
+export function legacyStorageGatewayFetch(
+  localKongCa: string | undefined,
+): typeof globalThis.fetch {
+  return localKongCa !== undefined ? legacyKongCaFetch(localKongCa) : globalThis.fetch;
+}
diff --git a/apps/cli/src/legacy/shared/legacy-storage-gateway.errors.ts b/apps/cli/src/legacy/shared/legacy-storage-gateway.errors.ts
new file mode 100644
index 0000000000..1c1d041319
--- /dev/null
+++ b/apps/cli/src/legacy/shared/legacy-storage-gateway.errors.ts
@@ -0,0 +1,32 @@
+import { Data } from "effect";
+
+/**
+ * Errors for the Supabase Storage **service gateway** (Kong), shared by every
+ * command that talks to Storage directly (`seed buckets`, `storage ls/cp/mv/rm`).
+ * Mirrors Go's `pkg/fetcher` error shapes:
+ *   - transport failure (`failed to execute http request`) →
+ *     `LegacyStorageGatewayNetworkError`
+ *   - non-200 response (`Error status <d>: <body>`, `pkg/fetcher/http.go:112`) →
+ *     `LegacyStorageGatewayStatusError`
+ *
+ * `message` reproduces Go's verbatim error text. `body` is carried on the status
+ * error so callers can classify it (e.g. `mv`'s `"error":"not_found"` and `rm`'s
+ * `"error":"Bucket not found"` substrings, and `seed`'s vector graceful-skip).
+ */
+export class LegacyStorageGatewayNetworkError extends Data.TaggedError(
+  "LegacyStorageGatewayNetworkError",
+)<{
+  readonly message: string;
+}> {}
+
+export class LegacyStorageGatewayStatusError extends Data.TaggedError(
+  "LegacyStorageGatewayStatusError",
+)<{
+  readonly status: number;
+  readonly body: string;
+  readonly message: string;
+}> {}
+
+export type LegacyStorageGatewayError =
+  | LegacyStorageGatewayNetworkError
+  | LegacyStorageGatewayStatusError;
diff --git a/apps/cli/src/legacy/commands/seed/buckets/buckets.gateway.ts b/apps/cli/src/legacy/shared/legacy-storage-gateway.ts
similarity index 50%
rename from apps/cli/src/legacy/commands/seed/buckets/buckets.gateway.ts
rename to apps/cli/src/legacy/shared/legacy-storage-gateway.ts
index 72d6a4a7c5..96bf8eabfb 100644
--- a/apps/cli/src/legacy/commands/seed/buckets/buckets.gateway.ts
+++ b/apps/cli/src/legacy/shared/legacy-storage-gateway.ts
@@ -1,29 +1,42 @@
-import { Effect, FileSystem } from "effect";
+import { Effect, FileSystem, Stream } from "effect";
 import * as HttpClient from "effect/unstable/http/HttpClient";
 import * as HttpClientError from "effect/unstable/http/HttpClientError";
 import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
 
-import { LegacySeedStorageNetworkError, LegacySeedStorageStatusError } from "./buckets.errors.ts";
+import {
+  LegacyStorageGatewayNetworkError,
+  LegacyStorageGatewayStatusError,
+} from "./legacy-storage-gateway.errors.ts";
+import { legacyGoPathSplit } from "./legacy-storage-url.ts";
 
 /**
  * Native TypeScript client for the Supabase Storage **service gateway** (Kong),
- * mirroring `apps/cli-go/pkg/storage/{buckets,objects,vector}.go` and the
+ * mirroring `apps/cli-go/pkg/storage/{buckets,objects,vector,api}.go` and the
  * `fetcher.NewServiceGateway` auth headers: the `apikey` header is always sent,
  * and `Authorization: Bearer <key>` is added only when the key is a JWT — Go's
  * `withAuthToken` (`pkg/fetcher/gateway.go:22`) omits it for opaque `sb_...`
  * keys, which are not bearer tokens.
  *
- * Scope is limited to what `seed buckets` reaches against the **local** stack
- * (list/create/update buckets, upload objects, vector list/create/delete). No
- * TS gateway client existed before this port (storage ls/cp/mv/rm are still Go
- * proxies); this is the hoist candidate for `legacy/shared/` once those land.
+ * Shared by `seed buckets` (bucket/object/vector upsert against the local stack)
+ * and `storage ls/cp/mv/rm` (object list/download/move/delete + bucket delete).
  */
 
+/** `pkg/storage/api.go:9-11`. */
+export const LEGACY_PAGE_LIMIT = 100;
+export const LEGACY_DELETE_OBJECTS_LIMIT = 1000;
+
 interface LegacyBucketSummary {
   readonly name: string;
   readonly id: string;
 }
 
+/** A `/storage/v1/object/list/{bucket}` entry: a directory when Go's `Id == nil`. */
+interface LegacyStorageObject {
+  readonly name: string;
+  readonly isDir: boolean;
+}
+
 export interface LegacyUpsertBucketProps {
   /**
    * Tri-state to match Go's `Public *bool` with `json:"public,omitempty"`:
@@ -36,72 +49,106 @@ export interface LegacyUpsertBucketProps {
   readonly allowedMimeTypes: ReadonlyArray<string>;
 }
 
+/** Upload headers, mirroring Go's `FileOptions` (`pkg/storage/objects.go:60-64`). */
+interface LegacyUploadObjectOptions {
+  readonly contentType: string;
+  readonly cacheControl: string;
+  readonly overwrite: boolean;
+}
+
 export interface LegacyStorageGateway {
   readonly listBuckets: () => Effect.Effect<
     ReadonlyArray<LegacyBucketSummary>,
-    LegacySeedStorageNetworkError | LegacySeedStorageStatusError
+    LegacyStorageGatewayNetworkError | LegacyStorageGatewayStatusError
   >;
   readonly createBucket: (
     name: string,
     props: LegacyUpsertBucketProps,
-  ) => Effect.Effect<void, LegacySeedStorageNetworkError | LegacySeedStorageStatusError>;
+  ) => Effect.Effect<void, LegacyStorageGatewayNetworkError | LegacyStorageGatewayStatusError>;
   readonly updateBucket: (
     id: string,
     props: LegacyUpsertBucketProps,
-  ) => Effect.Effect<void, LegacySeedStorageNetworkError | LegacySeedStorageStatusError>;
+  ) => Effect.Effect<void, LegacyStorageGatewayNetworkError | LegacyStorageGatewayStatusError>;
+  readonly deleteBucket: (
+    id: string,
+  ) => Effect.Effect<string, LegacyStorageGatewayNetworkError | LegacyStorageGatewayStatusError>;
+  readonly listObjects: (
+    bucket: string,
+    prefix: string,
+    page: number,
+  ) => Effect.Effect<
+    ReadonlyArray<LegacyStorageObject>,
+    LegacyStorageGatewayNetworkError | LegacyStorageGatewayStatusError
+  >;
+  /** Streams the object body; fails before the first byte on a non-200 status. */
+  readonly downloadObject: (
+    remotePath: string,
+  ) => Stream.Stream<
+    Uint8Array,
+    LegacyStorageGatewayNetworkError | LegacyStorageGatewayStatusError
+  >;
+  readonly uploadObject: (
+    remotePath: string,
+    absPath: string,
+    options: LegacyUploadObjectOptions,
+  ) => Effect.Effect<void, LegacyStorageGatewayNetworkError | LegacyStorageGatewayStatusError>;
+  readonly moveObject: (
+    bucketId: string,
+    srcKey: string,
+    dstKey: string,
+  ) => Effect.Effect<string, LegacyStorageGatewayNetworkError | LegacyStorageGatewayStatusError>;
+  readonly deleteObjects: (
+    bucket: string,
+    prefixes: ReadonlyArray<string>,
+  ) => Effect.Effect<
+    ReadonlyArray<{ readonly name: string }>,
+    LegacyStorageGatewayNetworkError | LegacyStorageGatewayStatusError
+  >;
   readonly listVectorBuckets: () => Effect.Effect<
     ReadonlyArray<string>,
-    LegacySeedStorageNetworkError | LegacySeedStorageStatusError
+    LegacyStorageGatewayNetworkError | LegacyStorageGatewayStatusError
   >;
   readonly createVectorBucket: (
     name: string,
-  ) => Effect.Effect<void, LegacySeedStorageNetworkError | LegacySeedStorageStatusError>;
+  ) => Effect.Effect<void, LegacyStorageGatewayNetworkError | LegacyStorageGatewayStatusError>;
   readonly deleteVectorBucket: (
     name: string,
-  ) => Effect.Effect<void, LegacySeedStorageNetworkError | LegacySeedStorageStatusError>;
-  readonly uploadObject: (
-    remotePath: string,
-    absPath: string,
-    contentType: string,
-  ) => Effect.Effect<void, LegacySeedStorageNetworkError | LegacySeedStorageStatusError>;
+  ) => Effect.Effect<void, LegacyStorageGatewayNetworkError | LegacyStorageGatewayStatusError>;
   readonly listAnalyticsBuckets: () => Effect.Effect<
     ReadonlyArray<string>,
-    LegacySeedStorageNetworkError | LegacySeedStorageStatusError
+    LegacyStorageGatewayNetworkError | LegacyStorageGatewayStatusError
   >;
   readonly createAnalyticsBucket: (
     name: string,
-  ) => Effect.Effect<void, LegacySeedStorageNetworkError | LegacySeedStorageStatusError>;
+  ) => Effect.Effect<void, LegacyStorageGatewayNetworkError | LegacyStorageGatewayStatusError>;
   readonly deleteAnalyticsBucket: (
     name: string,
-  ) => Effect.Effect<void, LegacySeedStorageNetworkError | LegacySeedStorageStatusError>;
+  ) => Effect.Effect<void, LegacyStorageGatewayNetworkError | LegacyStorageGatewayStatusError>;
 }
 
 /**
  * Strict JSON decode mirroring Go's `fetcher.ParseJSON[T]`
  * (`pkg/fetcher/http.go` — `json.NewDecoder(r).Decode(&data)`): a body whose
- * shape doesn't match the typed target aborts before any bucket mutation. Only
- * missing fields, `null` (decoded as the zero-value struct/field), empty arrays,
- * and extra keys are tolerated (zero values); a non-matching top-level type, a
- * non-null non-object element (number/array/string), or a present-but-wrong-typed
- * string field all fail. The graceful-skip classifiers
- * never see these (the message doesn't match), so they propagate, like Go.
+ * shape doesn't match the typed target aborts. Only missing fields, `null`
+ * (decoded as the zero value), empty arrays, and extra keys are tolerated; a
+ * non-matching top-level type, a non-null non-object element, or a
+ * present-but-wrong-typed string field fail.
  */
-function failParse(detail: string): LegacySeedStorageNetworkError {
-  return new LegacySeedStorageNetworkError({ message: `failed to parse response body: ${detail}` });
+function failParse(detail: string): LegacyStorageGatewayNetworkError {
+  return new LegacyStorageGatewayNetworkError({
+    message: `failed to parse response body: ${detail}`,
+  });
 }
 
 /**
- * The port to use for the local-gateway port-conflict hint, mirroring Go's
- * `localGatewayHint` (`apps/cli-go/pkg/fetcher/http.go:117-143`), which parses
- * the configured **server URL**: the hint only fires for a loopback host
- * (`127.0.0.1`/`localhost`/`::1`) that has a port, and reports THAT URL's port —
- * not `api.port`, which can differ when `api.external_url` is overridden. Returns
- * undefined for a non-loopback/remote host (so `--linked` never gets the hint).
+ * Port for Go's `localGatewayHint` (`pkg/fetcher/http.go:117-143`): the
+ * port-conflict hint fires only for a loopback host with a port, reporting THAT
+ * URL's port (not `api.port`, which can differ when `api.external_url` is set).
  */
 function localGatewayHintPort(baseUrl: string): string | undefined {
   try {
     const url = new URL(baseUrl);
-    const host = url.hostname.replace(/^\[|\]$/g, ""); // WHATWG brackets IPv6
+    const host = url.hostname.replace(/^\[|\]$/g, "");
     if ((host === "127.0.0.1" || host === "localhost" || host === "::1") && url.port.length > 0) {
       return url.port;
     }
@@ -111,12 +158,7 @@ function localGatewayHintPort(baseUrl: string): string | undefined {
   return undefined;
 }
 
-/**
- * Byte-identical to Go's `localGatewayHint` message. Go gates on its net/http
- * error strings (`malformed HTTP response` / timeout); Bun/undici don't emit
- * those, so the caller gates on an Effect `TransportError` instead — the text is
- * unchanged. Hoist to `legacy/shared/` when `storage ls/cp/mv/rm` land.
- */
+/** Byte-identical to Go's `localGatewayHint` message. */
 function legacyLocalGatewayHint(port: string): string {
   return (
     "The local Supabase API gateway did not return a valid HTTP response. " +
@@ -126,12 +168,10 @@ function legacyLocalGatewayHint(port: string): string {
 }
 
 /**
- * Whether a transport failure is a plain connection-refused (the local stack is
- * stopped). Go's `localGatewayHint` only fires for a malformed HTTP response,
- * header timeout, or context-deadline timeout — NOT `ECONNREFUSED` — so the
- * port-conflict hint is suppressed for refused connections. Bun/undici don't
- * emit Go's net/http strings, so this is a substring check over the transport
- * error's description/cause/message.
+ * Whether a transport failure is a plain connection-refused. Go's
+ * `localGatewayHint` fires only for malformed-response / timeout — NOT
+ * `ECONNREFUSED` — so the port-conflict hint is suppressed for refused
+ * connections.
  */
 function isConnectionRefused(error: HttpClientError.TransportError): boolean {
   const detail =
@@ -139,21 +179,13 @@ function isConnectionRefused(error: HttpClientError.TransportError): boolean {
   return /econnrefused|connection ?refused|unable to connect/.test(detail);
 }
 
-const parseJsonBody = (body: string): Effect.Effect<unknown, LegacySeedStorageNetworkError> =>
+const parseJsonBody = (body: string): Effect.Effect<unknown, LegacyStorageGatewayNetworkError> =>
   Effect.try({
     try: () => JSON.parse(body) as unknown,
     catch: (cause) => failParse(String(cause)),
   });
 
-/**
- * A JSON object → itself; a JSON `null` → `{}` (Go's zero-value struct: decoding
- * `null` into a non-pointer struct is a no-op that leaves it zero, no error —
- * same `encoding/json` rule as the string-field level below); a number / array /
- * string → `null` to signal a real Go-struct decode failure (`encoding/json`
- * errors on those). Combined with the null-tolerant `decodeStringField`, a `null`
- * list element decodes to the zero-value struct (empty `name`/`id`) and the
- * upsert loops continue, exactly as Go's do.
- */
+/** A JSON object → itself; `null` → `{}` (Go zero-value struct); other → `null`. */
 function asObject(entry: unknown): Record<string, unknown> | null {
   if (entry === null) return {};
   return typeof entry === "object" && !Array.isArray(entry)
@@ -161,25 +193,16 @@ function asObject(entry: unknown): Record<string, unknown> | null {
     : null;
 }
 
-/**
- * Go-struct string field: absent OR JSON `null` → "" (zero value, tolerated).
- * Go decodes via `json.NewDecoder(...).Decode(&data)` (fetcher/http.go:144-151)
- * into plain `string` fields (not `*string`), and `encoding/json` leaves a
- * non-pointer scalar at its zero value for a `null` JSON value rather than
- * erroring — so `{"name": null}` is `Name == ""`, not a parse failure. A
- * present-but-not-a-string value → `null` (decode failure, matching Go's
- * type-mismatch error). Distinguish the failure via `=== null`.
- */
+/** Go-struct string field: absent/`null` → ""; wrong type → `null` (decode failure). */
 function decodeStringField(obj: Record<string, unknown>, key: string): string | null {
   const value = obj[key];
   if (value === undefined || value === null) return "";
   return typeof value === "string" ? value : null;
 }
 
-/** Decode an array body of `{name, id}` objects (Go `[]BucketResponse`). */
 const decodeBucketSummaries = (
   body: string,
-): Effect.Effect<ReadonlyArray<LegacyBucketSummary>, LegacySeedStorageNetworkError> =>
+): Effect.Effect<ReadonlyArray<LegacyBucketSummary>, LegacyStorageGatewayNetworkError> =>
   Effect.gen(function* () {
     const parsed = yield* parseJsonBody(body);
     if (parsed === null) return [];
@@ -199,10 +222,43 @@ const decodeBucketSummaries = (
     return result;
   });
 
-/** Decode the `{vectorBuckets: [{vectorBucketName}]}` body (Go `ListVectorBucketsResponse`). */
+/**
+ * Decode `[]ObjectResponse` (`pkg/storage/objects.go:26-33`): `Id` is a `*string`,
+ * so an absent or `null` id marks a directory (Go's `o.Id == nil`,
+ * `internal/storage/ls/ls.go:67`); a present id (any non-null) marks a file. A
+ * non-string non-null id fails the decode, matching Go's `*string` unmarshal.
+ */
+const decodeStorageObjects = (
+  body: string,
+): Effect.Effect<ReadonlyArray<LegacyStorageObject>, LegacyStorageGatewayNetworkError> =>
+  Effect.gen(function* () {
+    const parsed = yield* parseJsonBody(body);
+    if (parsed === null) return [];
+    if (!Array.isArray(parsed)) {
+      return yield* Effect.fail(failParse("expected an array of objects"));
+    }
+    const result: Array<LegacyStorageObject> = [];
+    for (const entry of parsed) {
+      const obj = asObject(entry);
+      if (obj === null) {
+        return yield* Effect.fail(failParse("invalid object entry"));
+      }
+      const name = decodeStringField(obj, "name");
+      if (name === null) {
+        return yield* Effect.fail(failParse("invalid object entry"));
+      }
+      const idValue = obj["id"];
+      if (idValue !== undefined && idValue !== null && typeof idValue !== "string") {
+        return yield* Effect.fail(failParse("invalid object entry"));
+      }
+      result.push({ name, isDir: idValue === undefined || idValue === null });
+    }
+    return result;
+  });
+
 const decodeVectorBucketNames = (
   body: string,
-): Effect.Effect<ReadonlyArray<string>, LegacySeedStorageNetworkError> =>
+): Effect.Effect<ReadonlyArray<string>, LegacyStorageGatewayNetworkError> =>
   Effect.gen(function* () {
     const parsed = yield* parseJsonBody(body);
     const root = asObject(parsed);
@@ -210,8 +266,6 @@ const decodeVectorBucketNames = (
       return yield* Effect.fail(failParse("expected a vector bucket list object"));
     }
     const list = root["vectorBuckets"];
-    // Absent or null → empty: Go decodes `{"vectorBuckets": null}` (and the
-    // zero `ListVectorBucketsResponse{}`) into a nil slice, i.e. no buckets.
     if (list === undefined || list === null) return [];
     if (!Array.isArray(list)) {
       return yield* Effect.fail(failParse("vectorBuckets must be an array"));
@@ -229,32 +283,50 @@ const decodeVectorBucketNames = (
   });
 
 /**
- * Validate a create/update bucket success body. Go's `CreateBucket`/`UpdateBucket`
- * decode the 200 body via `fetcher.ParseJSON` into `{name}`/`{message}`
- * (`pkg/storage/buckets.go:46,65`) and fail on a non-JSON/empty body before later
- * uploads. The decoded value is unused (Go ignores it too) — this is purely the
- * validity gate. `null` is tolerated (Go's `json.Decode` accepts it); a non-object
- * top-level or a present-but-wrong-typed field fails.
+ * Validate a `{<field>}` success body and return the field's value. Go's
+ * mutations decode the 200 body via `fetcher.ParseJSON` into `{name}`/`{message}`
+ * and fail on a non-JSON/empty body. `null` is tolerated (Go's zero value); a
+ * non-object top-level or a wrong-typed field fails.
  */
-const decodeMutationResponse = (
+const decodeFieldResponse = (
   body: string,
   field: string,
-): Effect.Effect<void, LegacySeedStorageNetworkError> =>
+): Effect.Effect<string, LegacyStorageGatewayNetworkError> =>
   Effect.gen(function* () {
     const parsed = yield* parseJsonBody(body);
-    if (parsed === null) return;
+    if (parsed === null) return "";
     const obj = asObject(parsed);
-    if (obj === null || decodeStringField(obj, field) === null) {
-      return yield* Effect.fail(
-        failParse(`invalid ${field === "name" ? "create" : "update"} bucket response`),
-      );
+    const value = obj === null ? null : decodeStringField(obj, field);
+    if (value === null) {
+      return yield* Effect.fail(failParse(`invalid ${field} response`));
+    }
+    return value;
+  });
+
+const decodeDeleteObjects = (
+  body: string,
+): Effect.Effect<ReadonlyArray<{ readonly name: string }>, LegacyStorageGatewayNetworkError> =>
+  Effect.gen(function* () {
+    const parsed = yield* parseJsonBody(body);
+    if (parsed === null) return [];
+    if (!Array.isArray(parsed)) {
+      return yield* Effect.fail(failParse("expected an array of deleted objects"));
+    }
+    const result: Array<{ name: string }> = [];
+    for (const entry of parsed) {
+      const obj = asObject(entry);
+      const name = obj === null ? null : decodeStringField(obj, "name");
+      if (name === null) {
+        return yield* Effect.fail(failParse("invalid deleted object entry"));
+      }
+      result.push({ name });
     }
+    return result;
   });
 
-/** Decode an array body of `{name, ...}` objects to names (Go `[]AnalyticsBucketResponse`). */
 const decodeAnalyticsBucketNames = (
   body: string,
-): Effect.Effect<ReadonlyArray<string>, LegacySeedStorageNetworkError> =>
+): Effect.Effect<ReadonlyArray<string>, LegacyStorageGatewayNetworkError> =>
   Effect.gen(function* () {
     const parsed = yield* parseJsonBody(body);
     if (parsed === null) return [];
@@ -277,7 +349,6 @@ const decodeAnalyticsBucketNames = (
  * Build the create/update bucket body with Go's `omitempty` semantics
  * (`pkg/storage/buckets.go:29-54`): `public` (a `*bool`) is omitted when absent
  * from the TOML, `file_size_limit` when 0, `allowed_mime_types` when empty.
- * Exported for focused unit coverage.
  */
 export function legacyBucketBody(props: LegacyUpsertBucketProps): Record<string, unknown> {
   const body: Record<string, unknown> = {};
@@ -301,14 +372,9 @@ export const legacyMakeStorageGateway = Effect.fnUntraced(function* (opts: {
   const httpClient = yield* HttpClient.HttpClient;
   const fs = yield* FileSystem.FileSystem;
 
-  // Port for Go's local-gateway hint, derived from the actual base URL: only a
-  // loopback host with a port qualifies (so remote/custom hosts never get it).
   const hintPort = localGatewayHintPort(opts.baseUrl);
 
-  // Map a transport/request failure to a network error, appending Go's
-  // local-gateway port-conflict hint when the base URL is a local loopback
-  // gateway and the failure is at the transport layer (`localGatewayHint`).
-  const networkError = (cause: unknown): LegacySeedStorageNetworkError => {
+  const networkError = (cause: unknown): LegacyStorageGatewayNetworkError => {
     const base = `failed to execute http request: ${cause}`;
     if (
       hintPort !== undefined &&
@@ -316,16 +382,15 @@ export const legacyMakeStorageGateway = Effect.fnUntraced(function* (opts: {
       cause.reason._tag === "TransportError" &&
       !isConnectionRefused(cause.reason)
     ) {
-      return new LegacySeedStorageNetworkError({
+      return new LegacyStorageGatewayNetworkError({
         message: `${base}\n\n${legacyLocalGatewayHint(hintPort)}`,
       });
     }
-    return new LegacySeedStorageNetworkError({ message: base });
+    return new LegacyStorageGatewayNetworkError({ message: base });
   };
 
   // Go's `withAuthToken` (`pkg/fetcher/gateway.go:22`) gates the bearer header on
-  // a plain `sb_` prefix check: opaque `sb_...` keys are not JWTs, so only the
-  // `apikey` header is sent for them.
+  // a plain `sb_` prefix check: opaque `sb_...` keys are not JWTs.
   const isOpaqueServiceKey = opts.apiKey.startsWith("sb_");
   const withAuth = (
     req: HttpClientRequest.HttpClientRequest,
@@ -339,12 +404,9 @@ export const legacyMakeStorageGateway = Effect.fnUntraced(function* (opts: {
       : withApiKey.pipe(HttpClientRequest.setHeader("Authorization", `Bearer ${opts.apiKey}`));
   };
 
-  // Sends a request and returns the response body text, reproducing the Go
-  // fetcher's error shapes (`pkg/fetcher/http.go`): transport failure →
-  // network error; non-200 → `Error status <d>: <body>` status error. Go's
-  // service gateway installs `WithExpectedStatus(http.StatusOK)`
-  // (`pkg/fetcher/gateway.go:17`), so only exactly 200 is a success — a 201/204
-  // from an incompatible route is an error, not a silent pass.
+  // Sends a request and returns the response body text, reproducing Go's
+  // fetcher error shapes (`pkg/fetcher/http.go`). Go's service gateway installs
+  // `WithExpectedStatus(http.StatusOK)`, so only exactly 200 is a success.
   const send = Effect.fnUntraced(function* (req: HttpClientRequest.HttpClientRequest) {
     const { status, body } = yield* Effect.gen(function* () {
       const response = yield* httpClient.execute(req);
@@ -353,7 +415,7 @@ export const legacyMakeStorageGateway = Effect.fnUntraced(function* (opts: {
     }).pipe(Effect.mapError(networkError));
     if (status !== 200) {
       return yield* Effect.fail(
-        new LegacySeedStorageStatusError({
+        new LegacyStorageGatewayStatusError({
           status,
           body,
           message: `Error status ${status}: ${body}`,
@@ -375,13 +437,112 @@ export const legacyMakeStorageGateway = Effect.fnUntraced(function* (opts: {
         withAuth(HttpClientRequest.post(url("/storage/v1/bucket"))).pipe(
           HttpClientRequest.bodyJsonUnsafe({ name, ...legacyBucketBody(props) }),
         ),
-      ).pipe(Effect.flatMap((body) => decodeMutationResponse(body, "name"))),
+      ).pipe(
+        Effect.flatMap((body) => decodeFieldResponse(body, "name")),
+        Effect.asVoid,
+      ),
     updateBucket: (id, props) =>
       send(
         withAuth(HttpClientRequest.put(url(`/storage/v1/bucket/${id}`))).pipe(
           HttpClientRequest.bodyJsonUnsafe(legacyBucketBody(props)),
         ),
-      ).pipe(Effect.flatMap((body) => decodeMutationResponse(body, "message"))),
+      ).pipe(
+        Effect.flatMap((body) => decodeFieldResponse(body, "message")),
+        Effect.asVoid,
+      ),
+    deleteBucket: (id) =>
+      send(withAuth(HttpClientRequest.make("DELETE")(url(`/storage/v1/bucket/${id}`)))).pipe(
+        Effect.flatMap((body) => decodeFieldResponse(body, "message")),
+      ),
+    listObjects: (bucket, prefix, page) => {
+      const [dir, name] = legacyGoPathSplit(prefix);
+      const query: Record<string, unknown> = { prefix: dir };
+      if (name.length > 0) query["search"] = name;
+      query["limit"] = LEGACY_PAGE_LIMIT;
+      if (page > 0) query["offset"] = LEGACY_PAGE_LIMIT * page;
+      return send(
+        withAuth(HttpClientRequest.post(url(`/storage/v1/object/list/${bucket}`))).pipe(
+          HttpClientRequest.bodyJsonUnsafe(query),
+        ),
+      ).pipe(Effect.flatMap(decodeStorageObjects));
+    },
+    downloadObject: (remotePath) => {
+      const trimmed = remotePath.startsWith("/") ? remotePath.slice(1) : remotePath;
+      const req = withAuth(HttpClientRequest.get(url(`/storage/v1/object/${trimmed}`)));
+      return HttpClientResponse.stream(
+        httpClient.execute(req).pipe(
+          Effect.mapError(networkError),
+          Effect.flatMap((response) =>
+            response.status === 200
+              ? Effect.succeed(response)
+              : response.text.pipe(
+                  Effect.mapError(networkError),
+                  Effect.flatMap((body) =>
+                    Effect.fail(
+                      new LegacyStorageGatewayStatusError({
+                        status: response.status,
+                        body,
+                        message: `Error status ${response.status}: ${body}`,
+                      }),
+                    ),
+                  ),
+                ),
+          ),
+        ),
+      ).pipe(
+        Stream.mapError((cause) =>
+          cause instanceof LegacyStorageGatewayNetworkError ||
+          cause instanceof LegacyStorageGatewayStatusError
+            ? cause
+            : networkError(cause),
+        ),
+      );
+    },
+    uploadObject: (remotePath, absPath, options) => {
+      const trimmed = remotePath.startsWith("/") ? remotePath.slice(1) : remotePath;
+      let req = withAuth(HttpClientRequest.post(url(`/storage/v1/object/${trimmed}`)));
+      if (options.cacheControl.length > 0) {
+        req = req.pipe(HttpClientRequest.setHeader("Cache-Control", options.cacheControl));
+      }
+      if (options.overwrite) {
+        req = req.pipe(HttpClientRequest.setHeader("x-upsert", "true"));
+      }
+      // `bodyFile` stats the file for Content-Length and streams it via
+      // FileSystem rather than buffering — the analogue of Go's open-and-stream
+      // upload. The captured FileSystem is supplied here so the gateway's public
+      // Effect type stays free of a service requirement.
+      const withBody =
+        options.contentType.length > 0
+          ? HttpClientRequest.bodyFile(req, absPath, { contentType: options.contentType })
+          : HttpClientRequest.bodyFile(req, absPath);
+      return withBody.pipe(
+        Effect.provideService(FileSystem.FileSystem, fs),
+        Effect.mapError(
+          (cause) =>
+            new LegacyStorageGatewayNetworkError({
+              message: `failed to execute http request: ${cause}`,
+            }),
+        ),
+        Effect.flatMap(send),
+        Effect.asVoid,
+      );
+    },
+    moveObject: (bucketId, srcKey, dstKey) =>
+      send(
+        withAuth(HttpClientRequest.post(url("/storage/v1/object/move"))).pipe(
+          HttpClientRequest.bodyJsonUnsafe({
+            bucketId,
+            sourceKey: srcKey,
+            destinationKey: dstKey,
+          }),
+        ),
+      ).pipe(Effect.flatMap((body) => decodeFieldResponse(body, "message"))),
+    deleteObjects: (bucket, prefixes) =>
+      send(
+        withAuth(HttpClientRequest.make("DELETE")(url(`/storage/v1/object/${bucket}`))).pipe(
+          HttpClientRequest.bodyJsonUnsafe({ prefixes }),
+        ),
+      ).pipe(Effect.flatMap(decodeDeleteObjects)),
     listVectorBuckets: () =>
       send(
         withAuth(HttpClientRequest.post(url("/storage/v1/vector/ListVectorBuckets"))).pipe(
@@ -414,28 +575,6 @@ export const legacyMakeStorageGateway = Effect.fnUntraced(function* (opts: {
       send(
         withAuth(HttpClientRequest.make("DELETE")(url(`/storage/v1/iceberg/bucket/${name}`))),
       ).pipe(Effect.asVoid),
-    uploadObject: (remotePath, absPath, contentType) => {
-      const trimmed = remotePath.startsWith("/") ? remotePath.slice(1) : remotePath;
-      const req = withAuth(HttpClientRequest.post(url(`/storage/v1/object/${trimmed}`))).pipe(
-        HttpClientRequest.setHeader("Cache-Control", "max-age=3600"),
-        HttpClientRequest.setHeader("x-upsert", "true"),
-      );
-      // `bodyFile` stats the file for Content-Length and streams it via
-      // FileSystem rather than buffering — the analogue of Go's open-and-stream
-      // upload. The captured FileSystem is supplied here so the gateway's public
-      // Effect type stays free of a service requirement.
-      return HttpClientRequest.bodyFile(req, absPath, { contentType }).pipe(
-        Effect.provideService(FileSystem.FileSystem, fs),
-        Effect.mapError(
-          (cause) =>
-            new LegacySeedStorageNetworkError({
-              message: `failed to execute http request: ${cause}`,
-            }),
-        ),
-        Effect.flatMap(send),
-        Effect.asVoid,
-      );
-    },
   };
 
   return gateway;
diff --git a/apps/cli/src/legacy/shared/legacy-storage-gateway.unit.test.ts b/apps/cli/src/legacy/shared/legacy-storage-gateway.unit.test.ts
new file mode 100644
index 0000000000..4d4b604e1c
--- /dev/null
+++ b/apps/cli/src/legacy/shared/legacy-storage-gateway.unit.test.ts
@@ -0,0 +1,170 @@
+import { BunServices } from "@effect/platform-bun";
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, Exit, Layer } from "effect";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
+import type * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
+
+import { legacyBucketBody, legacyMakeStorageGateway } from "./legacy-storage-gateway.ts";
+
+describe("legacyBucketBody", () => {
+  it("omits public when undefined (Go *bool nil / omitempty)", () => {
+    expect(legacyBucketBody({ public: undefined, fileSizeLimit: 0, allowedMimeTypes: [] })).toEqual(
+      {},
+    );
+  });
+
+  it("includes public when explicitly set (true or false)", () => {
+    expect(legacyBucketBody({ public: true, fileSizeLimit: 0, allowedMimeTypes: [] })).toEqual({
+      public: true,
+    });
+    expect(legacyBucketBody({ public: false, fileSizeLimit: 0, allowedMimeTypes: [] })).toEqual({
+      public: false,
+    });
+  });
+
+  it("includes file_size_limit and allowed_mime_types only when non-empty", () => {
+    expect(
+      legacyBucketBody({ public: undefined, fileSizeLimit: 0, allowedMimeTypes: [] }),
+    ).not.toHaveProperty("file_size_limit");
+    expect(
+      legacyBucketBody({
+        public: false,
+        fileSizeLimit: 52_428_800,
+        allowedMimeTypes: ["image/png"],
+      }),
+    ).toEqual({ public: false, file_size_limit: 52_428_800, allowed_mime_types: ["image/png"] });
+  });
+});
+
+interface Recorded {
+  method: string;
+  url: string;
+  headers: Record<string, string | undefined>;
+  body: unknown;
+}
+
+function setup(routes: ReadonlyArray<{ match: string; status?: number; body?: unknown }>) {
+  const requests: Recorded[] = [];
+  const httpLayer = Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request: HttpClientRequest.HttpClientRequest) => {
+      let body: unknown;
+      if (request.body._tag === "Uint8Array") {
+        try {
+          body = JSON.parse(new TextDecoder().decode(request.body.body));
+        } catch {
+          body = undefined;
+        }
+      }
+      requests.push({
+        method: request.method,
+        url: request.url,
+        headers: { ...request.headers },
+        body,
+      });
+      const route = routes.find((r) => request.url.includes(r.match));
+      return Effect.succeed(
+        HttpClientResponse.fromWeb(
+          request,
+          new Response(JSON.stringify(route?.body ?? {}), {
+            status: route?.status ?? 200,
+            headers: { "content-type": "application/json" },
+          }),
+        ),
+      );
+    }),
+  );
+  return { requests, layer: Layer.mergeAll(httpLayer, BunServices.layer) };
+}
+
+describe("legacyMakeStorageGateway", () => {
+  it.live("decodes a list with a null id as a directory", () => {
+    const { requests, layer } = setup([
+      {
+        match: "/storage/v1/object/list/private",
+        body: [
+          { name: "folder", id: null },
+          { name: "file.png", id: "9b7f9f48" },
+        ],
+      },
+    ]);
+    return Effect.gen(function* () {
+      const gateway = yield* legacyMakeStorageGateway({
+        baseUrl: "http://127.0.0.1:54321",
+        apiKey: "service-key",
+        userAgent: "SupabaseCLI/test",
+      });
+      const objects = yield* gateway.listObjects("private", "folder/name", 1);
+      expect(objects).toEqual([
+        { name: "folder", isDir: true },
+        { name: "file.png", isDir: false },
+      ]);
+      // path.Split("folder/name") → prefix "folder/", search "name"; page 1 → offset 100.
+      expect(requests[0]?.body).toEqual({
+        prefix: "folder/",
+        search: "name",
+        limit: 100,
+        offset: 100,
+      });
+    }).pipe(Effect.provide(layer));
+  });
+
+  it.live("sends only apikey for an opaque sb_ key, both headers for a JWT", () => {
+    const { requests, layer } = setup([{ match: "/storage/v1/bucket", body: [] }]);
+    return Effect.gen(function* () {
+      const opaque = yield* legacyMakeStorageGateway({
+        baseUrl: "http://127.0.0.1:54321",
+        apiKey: "sb_secret_local",
+        userAgent: "ua",
+      });
+      yield* opaque.listBuckets();
+      expect(requests[0]?.headers["apikey"]).toBe("sb_secret_local");
+      expect(requests[0]?.headers["authorization"]).toBeUndefined();
+
+      const jwt = yield* legacyMakeStorageGateway({
+        baseUrl: "http://127.0.0.1:54321",
+        apiKey: "ey.jwt.key",
+        userAgent: "ua",
+      });
+      yield* jwt.listBuckets();
+      expect(requests[1]?.headers["authorization"]).toBe("Bearer ey.jwt.key");
+    }).pipe(Effect.provide(layer));
+  });
+
+  it.live("maps a non-200 to a status error carrying the body", () => {
+    const { layer } = setup([
+      { match: "/storage/v1/object/move", status: 404, body: { error: "not_found" } },
+    ]);
+    return Effect.gen(function* () {
+      const gateway = yield* legacyMakeStorageGateway({
+        baseUrl: "http://127.0.0.1:54321",
+        apiKey: "k",
+        userAgent: "ua",
+      });
+      const exit = yield* gateway.moveObject("private", "a", "b").pipe(Effect.exit);
+      expect(Exit.isFailure(exit)).toBe(true);
+      const json = JSON.stringify(exit);
+      expect(json).toContain("Error status 404");
+      // The raw response body is carried on the status error for caller classification.
+      expect(json).toContain("not_found");
+    }).pipe(Effect.provide(layer));
+  });
+
+  it.live("sends the prefixes body for deleteObjects and decodes removed names", () => {
+    const { requests, layer } = setup([
+      { match: "/storage/v1/object/private", body: [{ name: "a.txt" }, { name: "b.txt" }] },
+    ]);
+    return Effect.gen(function* () {
+      const gateway = yield* legacyMakeStorageGateway({
+        baseUrl: "http://127.0.0.1:54321",
+        apiKey: "k",
+        userAgent: "ua",
+      });
+      const removed = yield* gateway.deleteObjects("private", ["a.txt", "b.txt"]);
+      expect(removed).toEqual([{ name: "a.txt" }, { name: "b.txt" }]);
+      expect(requests[0]?.method).toBe("DELETE");
+      expect(requests[0]?.body).toEqual({ prefixes: ["a.txt", "b.txt"] });
+    }).pipe(Effect.provide(layer));
+  });
+});
diff --git a/apps/cli/src/legacy/shared/legacy-storage-runtime.layer.ts b/apps/cli/src/legacy/shared/legacy-storage-runtime.layer.ts
new file mode 100644
index 0000000000..4a25c257d9
--- /dev/null
+++ b/apps/cli/src/legacy/shared/legacy-storage-runtime.layer.ts
@@ -0,0 +1,81 @@
+import { Layer } from "effect";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+
+import { legacyCredentialsLayer } from "../auth/legacy-credentials.layer.ts";
+import { legacyPlatformApiFactoryLayer } from "../auth/legacy-platform-api-factory.layer.ts";
+import { LegacyPlatformApiFactory } from "../auth/legacy-platform-api-factory.service.ts";
+import { legacyCliConfigLayer } from "../config/legacy-cli-config.layer.ts";
+import { LegacyCliConfig } from "../config/legacy-cli-config.service.ts";
+import { legacyProjectRefLayer } from "../config/legacy-project-ref.layer.ts";
+import { LegacyProjectRefResolver } from "../config/legacy-project-ref.service.ts";
+import { legacyDebugLoggerLayer } from "./legacy-debug-logger.layer.ts";
+import { LegacyIdentityStitch, legacyIdentityStitchLayer } from "./legacy-identity-stitch.ts";
+import { legacyHttpClientLayer } from "../auth/legacy-http-debug.layer.ts";
+import { legacyLinkedProjectCacheLayer } from "../telemetry/legacy-linked-project-cache.layer.ts";
+import { LegacyLinkedProjectCache } from "../telemetry/legacy-linked-project-cache.service.ts";
+import { legacyTelemetryStateLayer } from "../telemetry/legacy-telemetry-state.layer.ts";
+import { LegacyTelemetryState } from "../telemetry/legacy-telemetry-state.service.ts";
+import { commandRuntimeLayer } from "../../shared/runtime/command-runtime.layer.ts";
+import { CommandRuntime } from "../../shared/runtime/command-runtime.service.ts";
+
+/**
+ * Runtime layer for the commands that talk to the Storage gateway directly:
+ * `seed buckets` and `storage ls/cp/mv/rm`. The Management API client is **lazy**
+ * so the LOCAL path (no `--linked`) never resolves a token / requires a login:
+ * `legacyPlatformApiFactoryLayer` defers token resolution to the first
+ * `factory.make` call, which only fires on the `--linked` branch (the remote
+ * service-role-key fetch).
+ *
+ * `HttpClient` is exposed at the top level because the Storage gateway requires
+ * an `HttpClient` service directly rather than going through the typed
+ * Management API client.
+ */
+export function legacyStorageGatewayRuntimeLayer(subcommand: ReadonlyArray<string>) {
+  const cliConfig = legacyCliConfigLayer.pipe(Layer.provide(legacyDebugLoggerLayer));
+  const httpClient = legacyHttpClientLayer.pipe(Layer.provide(legacyDebugLoggerLayer));
+  const credentials = legacyCredentialsLayer.pipe(
+    Layer.provide(cliConfig),
+    Layer.provide(legacyDebugLoggerLayer),
+  );
+  // Lazy factory: build does NOT resolve a token. Token resolution is deferred
+  // until `factory.make` is first called — i.e. when the `--linked` branch
+  // actually executes. The LOCAL path completes without touching the Management
+  // API.
+  const platformApiFactory = legacyPlatformApiFactoryLayer.pipe(
+    Layer.provide(credentials),
+    Layer.provide(cliConfig),
+    Layer.provide(legacyDebugLoggerLayer),
+    Layer.provide(legacyIdentityStitchLayer),
+  );
+
+  const built = Layer.mergeAll(
+    cliConfig,
+    platformApiFactory,
+    httpClient,
+    legacyProjectRefLayer.pipe(Layer.provide(platformApiFactory), Layer.provide(cliConfig)),
+    legacyLinkedProjectCacheLayer.pipe(
+      Layer.provide(credentials),
+      Layer.provide(cliConfig),
+      Layer.provide(httpClient),
+      Layer.provide(legacyIdentityStitchLayer),
+    ),
+    legacyTelemetryStateLayer,
+    legacyIdentityStitchLayer,
+    commandRuntimeLayer([...subcommand]),
+  );
+
+  const _serviceCoverageCheck: Layer.Layer<LegacyStorageGatewayServices, unknown, unknown> = built;
+  void _serviceCoverageCheck;
+
+  return built;
+}
+
+type LegacyStorageGatewayServices =
+  | LegacyPlatformApiFactory
+  | LegacyCliConfig
+  | LegacyProjectRefResolver
+  | LegacyLinkedProjectCache
+  | LegacyTelemetryState
+  | LegacyIdentityStitch
+  | CommandRuntime
+  | HttpClient.HttpClient;
diff --git a/apps/cli/src/legacy/shared/legacy-storage-url.ts b/apps/cli/src/legacy/shared/legacy-storage-url.ts
new file mode 100644
index 0000000000..4401c56387
--- /dev/null
+++ b/apps/cli/src/legacy/shared/legacy-storage-url.ts
@@ -0,0 +1,286 @@
+/**
+ * Storage URL parsing, ported 1:1 from Go's `internal/storage/client/scheme.go`
+ * plus the slices of `net/url` that `url.Parse` exercises for the `ss://` scheme.
+ *
+ * Two layers:
+ *  - `legacyGoUrlParse` reproduces Go's `url.Parse` for the fields the storage
+ *    commands read (`Scheme`, `Host`, `Path`) and the parse errors they surface
+ *    (`missing protocol scheme`, malformed `%` escape, control byte). `cp` parses
+ *    `src`/`dst` with this directly (Go uses `url.Parse`, not `ParseStorageURL`).
+ *  - `legacyParseStorageUrl` is Go's `ParseStorageURL`: parse, then require
+ *    scheme `ss` (case-insensitive), a non-empty path, and no host.
+ *
+ * Kept pure (no Effect, no command-specific tagged errors) so the handlers map
+ * the thrown errors to their own `Legacy*` tagged errors and the parser stays
+ * unit-testable against `scheme_test.go`.
+ */
+
+/** Go `client.STORAGE_SCHEME` (`scheme.go:10`). */
+export const LEGACY_STORAGE_SCHEME = "ss";
+
+/** Go `client.ErrInvalidURL` message (`scheme.go:12`). */
+const LEGACY_STORAGE_INVALID_URL_MESSAGE = "URL must match pattern ss:///bucket/[prefix]";
+
+/**
+ * Thrown when `legacyGoUrlParse` fails, mirroring Go's `*url.Error`:
+ * `parse "<url>": <inner>` (`net/url.Error.Error`). Callers wrap `.message` in
+ * their own `failed to parse … url: <message>` text, matching Go's
+ * `errors.Errorf("failed to parse … url: %w", err)`.
+ */
+export class LegacyGoUrlParseError extends Error {
+  constructor(rawURL: string, inner: string) {
+    super(`parse "${rawURL}": ${inner}`);
+    this.name = "LegacyGoUrlParseError";
+  }
+}
+
+/**
+ * Thrown when a URL parses but does not match the `ss:///bucket/[prefix]`
+ * pattern (Go's `ErrInvalidURL`). Distinct from `LegacyGoUrlParseError` so the
+ * handler can map it to `LegacyStorageUrlPatternError` rather than the
+ * parse-error tagged error.
+ */
+export class LegacyStorageUrlPatternError extends Error {
+  constructor() {
+    super(LEGACY_STORAGE_INVALID_URL_MESSAGE);
+    this.name = "LegacyStorageUrlPatternError";
+  }
+}
+
+export interface LegacyGoUrl {
+  /** Lowercased scheme (Go lowercases via `strings.ToLower`); `""` when none. */
+  readonly scheme: string;
+  /** Authority host (after `//`); `""` when absent. */
+  readonly host: string;
+  /** Unescaped path (Go `url.Path`); `""` when the URL is opaque/host-only. */
+  readonly path: string;
+}
+
+function isAlpha(c: number): boolean {
+  return (c >= 0x61 && c <= 0x7a) || (c >= 0x41 && c <= 0x5a);
+}
+
+function isDigit(c: number): boolean {
+  return c >= 0x30 && c <= 0x39;
+}
+
+/** Go `net/url.stringContainsCTLByte` (`url.go`). */
+function containsCtlByte(s: string): boolean {
+  for (let i = 0; i < s.length; i++) {
+    const b = s.charCodeAt(i);
+    if ((b < 0x20 && b !== 0x09) || b === 0x7f) return true;
+  }
+  return false;
+}
+
+/**
+ * Go `net/url.getScheme`: a scheme is `ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )`
+ * terminated by `:`. A leading non-alpha, or any out-of-grammar byte before the
+ * first `:`, means there is no scheme (the whole input is the rest). A leading
+ * `:` is the `missing protocol scheme` error.
+ */
+function getScheme(rawURL: string): { scheme: string; rest: string } {
+  for (let i = 0; i < rawURL.length; i++) {
+    const c = rawURL.charCodeAt(i);
+    if (isAlpha(c)) {
+      continue;
+    }
+    if (isDigit(c) || c === 0x2b /* + */ || c === 0x2d /* - */ || c === 0x2e /* . */) {
+      if (i === 0) return { scheme: "", rest: rawURL };
+      continue;
+    }
+    if (c === 0x3a /* : */) {
+      if (i === 0) throw new Error("missing protocol scheme");
+      return { scheme: rawURL.slice(0, i), rest: rawURL.slice(i + 1) };
+    }
+    // Invalid character before any `:` → no scheme.
+    return { scheme: "", rest: rawURL };
+  }
+  return { scheme: "", rest: rawURL };
+}
+
+function isHex(c: number): boolean {
+  return (c >= 0x30 && c <= 0x39) || (c >= 0x61 && c <= 0x66) || (c >= 0x41 && c <= 0x46);
+}
+
+function unhex(c: number): number {
+  if (c >= 0x30 && c <= 0x39) return c - 0x30;
+  if (c >= 0x61 && c <= 0x66) return c - 0x61 + 10;
+  return c - 0x41 + 10;
+}
+
+/**
+ * Go `net/url.unescape(s, encodePath)`: decode `%XX` sequences, erroring on a
+ * malformed escape (`invalid URL escape "%XY"`). In `encodePath` mode `+` is
+ * literal.
+ *
+ * Go decodes `%XX` to raw bytes and the resulting `Path` is a byte string that,
+ * for a UTF-8 source, reads as the Unicode runes. To match, consecutive `%XX`
+ * bytes are collected and decoded as a single UTF-8 run (`%E4%B8%AD` → `中`, not
+ * three per-byte code points); literal characters pass through unchanged.
+ */
+function unescapePath(s: string): string {
+  if (!s.includes("%")) return s;
+  let out = "";
+  let pending: Array<number> = [];
+  const flushPending = () => {
+    if (pending.length > 0) {
+      out += new TextDecoder().decode(new Uint8Array(pending));
+      pending = [];
+    }
+  };
+  for (let i = 0; i < s.length; ) {
+    if (s.charCodeAt(i) === 0x25 /* % */) {
+      const h1 = i + 1 < s.length ? s.charCodeAt(i + 1) : -1;
+      const h2 = i + 2 < s.length ? s.charCodeAt(i + 2) : -1;
+      if (i + 2 >= s.length || h1 < 0 || h2 < 0 || !isHex(h1) || !isHex(h2)) {
+        const bad = s.slice(i, Math.min(i + 3, s.length));
+        throw new Error(`invalid URL escape "${bad}"`);
+      }
+      pending.push(unhex(h1) * 16 + unhex(h2));
+      i += 3;
+    } else {
+      flushPending();
+      out += s[i];
+      i += 1;
+    }
+  }
+  flushPending();
+  return out;
+}
+
+/** Go `net/url` authority host extraction (userinfo split at the last `@`). */
+function hostFromAuthority(authority: string): string {
+  const at = authority.lastIndexOf("@");
+  return at === -1 ? authority : authority.slice(at + 1);
+}
+
+/**
+ * Port of Go's `url.Parse` restricted to `Scheme`/`Host`/`Path`. Throws
+ * `LegacyGoUrlParseError` (Go's `*url.Error`) on the failures the storage
+ * commands can hit. Query (`?…`) and fragment (`#…`) are stripped exactly as Go
+ * splits them, though storage URLs never use them.
+ */
+export function legacyGoUrlParse(rawURL: string): LegacyGoUrl {
+  // Go `Parse` cuts the fragment before calling the internal `parse`.
+  const hashIdx = rawURL.indexOf("#");
+  const u = hashIdx === -1 ? rawURL : rawURL.slice(0, hashIdx);
+
+  if (containsCtlByte(u)) {
+    throw new LegacyGoUrlParseError(u, "net/url: invalid control character in URL");
+  }
+  if (u === "*") {
+    return { scheme: "", host: "", path: "*" };
+  }
+
+  let scheme: string;
+  let rest: string;
+  try {
+    const parsed = getScheme(u);
+    scheme = parsed.scheme.toLowerCase();
+    rest = parsed.rest;
+  } catch (cause) {
+    throw new LegacyGoUrlParseError(u, cause instanceof Error ? cause.message : String(cause));
+  }
+
+  // Strip the query (Go: `rest, RawQuery, _ = strings.Cut(rest, "?")`).
+  const qIdx = rest.indexOf("?");
+  if (qIdx !== -1) rest = rest.slice(0, qIdx);
+
+  if (!rest.startsWith("/")) {
+    if (scheme !== "") {
+      // Rootless path → opaque; Path stays empty.
+      return { scheme, host: "", path: "" };
+    }
+    // Non-request, no scheme: a colon in the first segment is rejected.
+    const slash = rest.indexOf("/");
+    const segment = slash === -1 ? rest : rest.slice(0, slash);
+    if (segment.includes(":")) {
+      throw new LegacyGoUrlParseError(u, "first path segment in URL cannot contain colon");
+    }
+  }
+
+  let host = "";
+  // Go: enter authority parsing only when (scheme set OR not "///"-prefixed) AND "//"-prefixed.
+  if ((scheme !== "" || !rest.startsWith("///")) && rest.startsWith("//")) {
+    const afterSlashes = rest.slice(2);
+    const slash = afterSlashes.indexOf("/");
+    const authority = slash === -1 ? afterSlashes : afterSlashes.slice(0, slash);
+    rest = slash === -1 ? "" : afterSlashes.slice(slash);
+    host = hostFromAuthority(authority);
+  }
+
+  let path: string;
+  try {
+    path = unescapePath(rest);
+  } catch (cause) {
+    throw new LegacyGoUrlParseError(u, cause instanceof Error ? cause.message : String(cause));
+  }
+  return { scheme, host, path };
+}
+
+/**
+ * Go `client.ParseStorageURL` (`scheme.go:14-23`): parse, then require scheme
+ * `ss` (case-insensitive), a non-empty path, and no host. Returns the path.
+ * Throws `LegacyGoUrlParseError` on a url-parse failure (wrapped by the caller
+ * as `failed to parse storage url: …`) or `LegacyStorageUrlPatternError` when
+ * the parsed URL doesn't match the `ss:///bucket/[prefix]` pattern.
+ */
+export function legacyParseStorageUrl(objectURL: string): string {
+  const parsed = legacyGoUrlParse(objectURL);
+  if (
+    parsed.scheme !== LEGACY_STORAGE_SCHEME ||
+    parsed.path.length === 0 ||
+    parsed.host.length > 0
+  ) {
+    throw new LegacyStorageUrlPatternError();
+  }
+  return parsed.path;
+}
+
+/**
+ * Go `client.SplitBucketPrefix` (`scheme.go:25-38`): `/bucket/folder/x` →
+ * `["bucket", "folder/x"]`; `/bucket/` / `/bucket` / `bucket` → `["bucket", ""]`;
+ * `""` / `"/"` → `["", ""]`.
+ */
+export function legacySplitBucketPrefix(objectPath: string): readonly [string, string] {
+  if (objectPath === "" || objectPath === "/") {
+    return ["", ""];
+  }
+  const start = objectPath.charCodeAt(0) === 0x2f /* / */ ? 1 : 0;
+  const sep = objectPath.indexOf("/", start);
+  if (sep < 0) {
+    return [objectPath.slice(start), ""];
+  }
+  return [objectPath.slice(start, sep), objectPath.slice(sep + 1)];
+}
+
+/**
+ * Lowercased scheme for a raw URL, mirroring `cp`'s
+ * `strings.EqualFold(parsed.Scheme, STORAGE_SCHEME)` branch input. `""` when the
+ * URL has no scheme (a local path). Throws `LegacyGoUrlParseError` on a malformed
+ * URL (e.g. `:`), exactly as `cp`'s `url.Parse` does.
+ */
+export function legacyDetectScheme(rawURL: string): string {
+  return legacyGoUrlParse(rawURL).scheme;
+}
+
+/**
+ * Go `cp.IsDir` (`cp.go:174-176`): an object prefix is a directory when it is
+ * empty or ends with `/`.
+ */
+export function legacyStorageIsDir(objectPrefix: string): boolean {
+  return objectPrefix.length === 0 || objectPrefix.endsWith("/");
+}
+
+/**
+ * Go `path.Split`: split after the final slash into `[dir, file]`, where `dir`
+ * keeps its trailing slash. `folder/name.png` → `["folder/", "name.png"]`;
+ * `dir` → `["", "dir"]`; `tmp/` → `["tmp/", ""]`; `""` → `["", ""]`. Used by the
+ * gateway's `listObjects` query (`pkg/storage/objects.go:46`) and the recursive
+ * walk's base-path computation (`internal/storage/ls/ls.go:97`).
+ */
+export function legacyGoPathSplit(p: string): readonly [string, string] {
+  const i = p.lastIndexOf("/");
+  return [p.slice(0, i + 1), p.slice(i + 1)];
+}
diff --git a/apps/cli/src/legacy/shared/legacy-storage-url.unit.test.ts b/apps/cli/src/legacy/shared/legacy-storage-url.unit.test.ts
new file mode 100644
index 0000000000..5e9643f48e
--- /dev/null
+++ b/apps/cli/src/legacy/shared/legacy-storage-url.unit.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  LegacyGoUrlParseError,
+  LegacyStorageUrlPatternError,
+  legacyDetectScheme,
+  legacyParseStorageUrl,
+  legacySplitBucketPrefix,
+  legacyStorageIsDir,
+} from "./legacy-storage-url.ts";
+
+// Oracle: apps/cli-go/internal/storage/client/scheme_test.go
+describe("legacyParseStorageUrl", () => {
+  it("parses a valid url to its path", () => {
+    expect(legacyParseStorageUrl("ss:///bucket/folder/name.png")).toBe("/bucket/folder/name.png");
+  });
+
+  it("rejects a url with a host (ss://bucket)", () => {
+    expect(() => legacyParseStorageUrl("ss://bucket")).toThrow(LegacyStorageUrlPatternError);
+    expect(() => legacyParseStorageUrl("ss://bucket")).toThrow(
+      "URL must match pattern ss:///bucket/[prefix]",
+    );
+  });
+
+  it("rejects a url with no path (ss:)", () => {
+    expect(() => legacyParseStorageUrl("ss:")).toThrow(LegacyStorageUrlPatternError);
+  });
+
+  it("rejects a url with the wrong scheme (.)", () => {
+    expect(() => legacyParseStorageUrl(".")).toThrow(LegacyStorageUrlPatternError);
+  });
+
+  it("surfaces the url-parse error on a missing protocol scheme (:)", () => {
+    expect(() => legacyParseStorageUrl(":")).toThrow(LegacyGoUrlParseError);
+    expect(() => legacyParseStorageUrl(":")).toThrow("missing protocol scheme");
+  });
+
+  it("accepts an uppercase scheme (case-insensitive)", () => {
+    expect(legacyParseStorageUrl("SS:///bucket/x")).toBe("/bucket/x");
+  });
+
+  it("rejects a malformed percent-escape in the path", () => {
+    expect(() => legacyParseStorageUrl("ss:///bucket/a%2")).toThrow(LegacyGoUrlParseError);
+    expect(() => legacyParseStorageUrl("ss:///bucket/a%2")).toThrow('invalid URL escape "%2"');
+  });
+
+  it("decodes percent-escapes in the path (ascii)", () => {
+    expect(legacyParseStorageUrl("ss:///bucket/a%20b")).toBe("/bucket/a b");
+  });
+
+  it("decodes a multi-byte UTF-8 percent-escape as one rune (Go raw-byte path)", () => {
+    // %E4%B8%AD is the UTF-8 encoding of 中 — decoded as one rune, not three.
+    expect(legacyParseStorageUrl("ss:///bucket/%E4%B8%AD.txt")).toBe("/bucket/中.txt");
+  });
+});
+
+// Oracle: SplitBucketPrefix sub-tests in scheme_test.go
+describe("legacySplitBucketPrefix", () => {
+  it.each([
+    ["", ["", ""]],
+    ["/", ["", ""]],
+    ["bucket", ["bucket", ""]],
+    ["/bucket", ["bucket", ""]],
+    ["bucket/", ["bucket", ""]],
+    ["/bucket/folder/name.png", ["bucket", "folder/name.png"]],
+    ["/bucket/folder/", ["bucket", "folder/"]],
+  ] as const)("splits %j → %j", (input, expected) => {
+    expect(legacySplitBucketPrefix(input)).toEqual(expected);
+  });
+});
+
+describe("legacyDetectScheme", () => {
+  it.each([
+    ["ss:///x", "ss"],
+    ["readme.md", ""],
+    ["/tmp/f", ""],
+    ["SS://x", "ss"],
+    [".", ""],
+  ] as const)("detects %j → %j", (input, expected) => {
+    expect(legacyDetectScheme(input)).toBe(expected);
+  });
+
+  it("throws on a missing protocol scheme", () => {
+    expect(() => legacyDetectScheme(":")).toThrow("missing protocol scheme");
+  });
+});
+
+describe("legacyStorageIsDir", () => {
+  it.each([
+    ["", true],
+    ["a/", true],
+    ["a", false],
+    ["folder/name.png", false],
+  ] as const)("classifies %j → %j", (input, expected) => {
+    expect(legacyStorageIsDir(input)).toBe(expected);
+  });
+});
diff --git a/apps/cli/tests/helpers/legacy-storage.ts b/apps/cli/tests/helpers/legacy-storage.ts
new file mode 100644
index 0000000000..aa55eb1f59
--- /dev/null
+++ b/apps/cli/tests/helpers/legacy-storage.ts
@@ -0,0 +1,209 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { BunServices } from "@effect/platform-bun";
+import { Effect, Layer, Option } from "effect";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
+
+import { LegacyPlatformApi } from "../../src/legacy/auth/legacy-platform-api.service.ts";
+import { LegacyPlatformApiFactory } from "../../src/legacy/auth/legacy-platform-api-factory.service.ts";
+import { LegacyProjectNotLinkedError } from "../../src/legacy/config/legacy-project-ref.errors.ts";
+import { LegacyProjectRefResolver } from "../../src/legacy/config/legacy-project-ref.service.ts";
+import { LegacyYesFlag } from "../../src/shared/legacy/global-flags.ts";
+import type { OutputFormat } from "../../src/shared/output/types.ts";
+import { mockOutput, mockRuntimeInfo } from "./mocks.ts";
+import {
+  LEGACY_VALID_REF,
+  legacyJsonResponse,
+  legacyTransportFailure,
+  mockLegacyCliConfig,
+  mockLegacyLinkedProjectCacheTracked,
+  mockLegacyPlatformApiService,
+  mockLegacyTelemetryStateTracked,
+} from "./legacy-mocks.ts";
+
+/**
+ * One Storage gateway / Management API mock route.
+ *
+ * Routes are matched in registration order and **consumed** once matched (like
+ * gock mocks), so pagination and recursive flows register one route per expected
+ * call. `when` further narrows a match by the parsed request body (e.g. paging by
+ * `offset`). `persist` keeps a route matchable across calls (e.g. api-keys).
+ */
+export interface LegacyStorageRoute {
+  readonly method: string;
+  /** Substring matched against the request URL. */
+  readonly match: string;
+  readonly status?: number;
+  /** Response JSON body. */
+  readonly body?: unknown;
+  /** Raw (non-JSON) response body, for streamed object downloads. */
+  readonly rawBody?: string;
+  /** When true, fail with a transport error instead of responding. */
+  readonly transport?: boolean;
+  readonly transportDescription?: string;
+  /** Narrow the match by the parsed request body. */
+  readonly when?: (reqBody: unknown) => boolean;
+  /** Keep this route matchable on every call instead of consuming it. */
+  readonly persist?: boolean;
+}
+
+export interface LegacyRecordedStorageRequest {
+  readonly method: string;
+  readonly url: string;
+  readonly headers: Record<string, string | undefined>;
+  readonly body: unknown;
+}
+
+export interface SetupLegacyStorageOptions {
+  readonly toml?: string;
+  readonly routes?: ReadonlyArray<LegacyStorageRoute>;
+  readonly files?: Readonly<Record<string, string>>;
+  readonly format?: OutputFormat;
+  /** Routing is driven by the `local` field on each command's flags, not here. */
+  readonly local?: boolean;
+  readonly yes?: boolean;
+  readonly confirm?: ReadonlyArray<boolean>;
+  readonly promptConfirmFail?: boolean;
+  /** Project ref returned by the resolver for the linked path. */
+  readonly projectRef?: string;
+  /** api-keys list returned by the Management API mock (linked path). */
+  readonly apiKeys?: ReadonlyArray<{
+    name: string;
+    api_key?: string | null;
+    type?: string | null;
+    secret_jwt_template?: Record<string, unknown> | null;
+  }>;
+  /** When true, `loadProjectRef` fails with `LegacyProjectNotLinkedError`. */
+  readonly linkedFails?: boolean;
+}
+
+/**
+ * Builds the layer + recorded state for a `storage` command integration test.
+ * Mirrors the seed-buckets setup: a recording `HttpClient` for the Storage
+ * gateway, a config.toml on disk, a project-ref resolver, a lazy Management API
+ * factory (api-keys), tracked telemetry + linked-project cache, and the
+ * `--local` scoped-global flag value.
+ */
+export function setupLegacyStorage(workdir: string, opts: SetupLegacyStorageOptions) {
+  if (opts.toml !== undefined) {
+    mkdirSync(join(workdir, "supabase"), { recursive: true });
+    writeFileSync(join(workdir, "supabase", "config.toml"), opts.toml);
+  }
+  for (const [rel, content] of Object.entries(opts.files ?? {})) {
+    const abs = join(workdir, rel);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content);
+  }
+
+  const out = mockOutput({
+    format: opts.format ?? "text",
+    promptConfirmResponses: opts.confirm,
+    promptConfirmFail: opts.promptConfirmFail,
+  });
+
+  const requests: Array<LegacyRecordedStorageRequest> = [];
+  const consumed = new Set<number>();
+  const routes = opts.routes ?? [];
+
+  const httpLayer = Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request) => {
+      let body: unknown;
+      if (request.body._tag === "Uint8Array") {
+        try {
+          body = JSON.parse(new TextDecoder().decode(request.body.body));
+        } catch {
+          body = undefined;
+        }
+      }
+      requests.push({
+        method: request.method,
+        url: request.url,
+        headers: { ...request.headers },
+        body,
+      });
+      let index = -1;
+      for (let i = 0; i < routes.length; i++) {
+        const r = routes[i];
+        if (r === undefined) continue;
+        if (consumed.has(i)) continue;
+        if (r.method !== request.method) continue;
+        if (!request.url.includes(r.match)) continue;
+        if (r.when !== undefined && !r.when(body)) continue;
+        index = i;
+        break;
+      }
+      if (index === -1) {
+        return Effect.succeed(legacyJsonResponse(request, 404, { message: "no mock route" }));
+      }
+      const route = routes[index]!;
+      if (route.persist !== true) consumed.add(index);
+      if (route.transport === true) {
+        return Effect.fail(legacyTransportFailure(request, route.transportDescription));
+      }
+      if (route.rawBody !== undefined) {
+        return Effect.succeed(
+          HttpClientResponse.fromWeb(
+            request,
+            new Response(route.rawBody, { status: route.status ?? 200 }),
+          ),
+        );
+      }
+      return Effect.succeed(legacyJsonResponse(request, route.status ?? 200, route.body ?? {}));
+    }),
+  );
+
+  const telemetry = mockLegacyTelemetryStateTracked();
+  const linkedCache = mockLegacyLinkedProjectCacheTracked();
+
+  const projectRefRef = opts.projectRef ?? LEGACY_VALID_REF;
+  const notLinked = () =>
+    new LegacyProjectNotLinkedError({
+      message: "Cannot find project ref. Have you run supabase link?",
+    });
+  const projectRefLayer = Layer.succeed(LegacyProjectRefResolver, {
+    resolve: () =>
+      opts.linkedFails === true ? Effect.fail(notLinked()) : Effect.succeed(projectRefRef),
+    resolveForLink: () =>
+      opts.linkedFails === true ? Effect.fail(notLinked()) : Effect.succeed(projectRefRef),
+    resolveOptional: () => Effect.succeed(Option.some(projectRefRef)),
+    loadProjectRef: () =>
+      opts.linkedFails === true ? Effect.fail(notLinked()) : Effect.succeed(projectRefRef),
+    promptProjectRef: () => Effect.succeed(projectRefRef),
+  });
+
+  const defaultApiKeys = [
+    {
+      name: "service_role",
+      api_key: "test-service-role-key",
+      type: "secret",
+      secret_jwt_template: { role: "service_role" },
+    },
+  ];
+  const managementApi = mockLegacyPlatformApiService({
+    v1: {
+      getProjectApiKeys: () => Effect.succeed(opts.apiKeys ?? defaultApiKeys),
+    },
+  });
+
+  const layer = Layer.mergeAll(
+    out.layer,
+    httpLayer,
+    telemetry.layer,
+    linkedCache.layer,
+    mockLegacyCliConfig({ workdir }),
+    BunServices.layer,
+    projectRefLayer,
+    Layer.succeed(LegacyPlatformApiFactory, {
+      make: LegacyPlatformApi.pipe(Effect.provide(managementApi.layer)),
+    }),
+    Layer.succeed(LegacyYesFlag, opts.yes ?? false),
+    // `cp` resolves relative local paths against the original cwd (Go's
+    // `utils.CurrentDirAbs`); point it at the temp workdir for tests.
+    mockRuntimeInfo({ cwd: workdir }),
+  );
+
+  return { layer, out, requests, telemetry, linkedCache };
+}