Payload Cloud Upload Export

Download your media files from Payload Cloud's S3 storage to a local directory.

How It Works

The script runs inside your Payload project using the local API to:

1. Discover all upload-enabled collections from your Payload config
2. Query each collection to get every document's filename (including image resize variants)
3. Authenticate with Cognito via @payloadcms/payload-cloud's getStorageClient
4. Download each file from S3 to a local export-uploads/ directory

Setup

1. Copy src/export-uploads.ts into your Payload project's src/ directory

2. Update the config import path to match your project:

   const { default: config } = await import('./payload.config.js') // adjust to your config location

3. Add the following environment variables to your .env:

   From the File Storage tab on your Payload Cloud dashboard, use copy button on far right:

   PAYLOAD_CLOUD=true
   PAYLOAD_CLOUD_ENVIRONMENT=prod
   PAYLOAD_CLOUD_PROJECT_ID=
   PAYLOAD_CLOUD_COGNITO_USER_POOL_ID=
   PAYLOAD_CLOUD_COGNITO_USER_POOL_CLIENT_ID=
   PAYLOAD_CLOUD_COGNITO_IDENTITY_POOL_ID=
   PAYLOAD_CLOUD_BUCKET=
   PAYLOAD_CLOUD_BUCKET_REGION=
   PAYLOAD_CLOUD_COGNITO_PASSWORD=          # from the 'Cognito Password' field
   

   From Settings → Environment Variables:

   PAYLOAD_SECRET=                           # from 'Payload Secret'
   

   From the Database tab:

   DATABASE_URI=                             # your MongoDB connection string
   

   Note: If PAYLOAD_CLOUD_COGNITO_PASSWORD contains a $ character, escape it as \$ in your .env file to prevent variable interpolation.

4. Install tsx as a dev dependency if not already installed:

   npm install -D tsx

5. Add the following scripts to your package.json:

   {
     "scripts": {
       "export-uploads": "tsx src/export-uploads.ts",
       "export-uploads:apply": "tsx src/export-uploads.ts --apply"
     }
   }

Usage

Dry run (default) — lists all files without downloading:

npm run export-uploads

Download — downloads files to ./export-uploads/:

npm run export-uploads:apply

The script is resume-friendly: files that already exist locally are skipped.

Output

Files are organized by collection:

./export-uploads/
  media/
    image1.jpg
    image1-640x480.jpg    # image resize variant
    image2.png
  documents/
    report.pdf