Storage Providers

Basecut snapshots consist of manifest metadata, schema definitions, warnings (optional), and compressed CSV data files. You can store these artifacts in cloud storage or on your local filesystem.

AWS S3 (Recommended for Teams)

Store snapshots in Amazon S3 for team sharing and self-hosted agent integration.

Configuration

# basecut.yml
output:
  provider: s3
  bucket: my-basecut-snapshots
  region: us-east-1
  # Optional for S3-compatible storage (e.g., Cloudflare R2, MinIO)
  endpoint: https://<accountid>.r2.cloudflarestorage.com
  prefix: team-a # optional: path prefix within bucket

Authentication

Option 1: AWS CLI credentials (recommended for development)

aws configure
# Enter your AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY

Basecut automatically uses your ~/.aws/credentials profile.

S3-Compatible Backends (Cloudflare R2, MinIO, LocalStack)

Use provider: s3 with a custom endpoint:

output:
  provider: s3
  bucket: my-r2-bucket
  region: auto # recommended for Cloudflare R2
  endpoint: https://<accountid>.r2.cloudflarestorage.com
  prefix: team-a

Set credentials using standard AWS environment variables:

export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...

Option 2: Environment variables

export AWS_ACCESS_KEY_ID=your_key_id
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_SESSION_TOKEN=your_token  # if using temporary credentials

Option 3: IAM role (recommended for CI/CD and agents) No credentials needed—EC2 instances, ECS tasks, or GitHub Actions with OIDC can use IAM roles.

Required Permissions

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:GetObject", "s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::my-basecut-snapshots/*",
        "arn:aws:s3:::my-basecut-snapshots"
      ]
    }
  ]
}

Bucket Organization

Cloud object keys are stored under snapshots/<job-id> (optionally prefixed):

s3://my-basecut-snapshots/
└── team-a/                        # optional prefix
    └── snapshots/
        ├── 8f4f4b0e-fbc7-4f70.../
        │   ├── manifest.json
        │   ├── schema.json
        │   ├── warnings.json      # optional
        │   └── tables/
        │       ├── public.users.csv.gz
        │       └── public.orders.csv.gz
        └── 2d3c1a91-3f23-4d83.../

Use basecut snapshot list and basecut snapshot inspect to work with snapshot names/tags; object keys are internal storage details.

Google Cloud Storage (Recommended for Teams)

Store snapshots in Google Cloud Storage buckets.

Configuration

# basecut.yml
output:
  provider: gcs
  bucket: my-basecut-snapshots
  prefix: team-a # optional: path prefix within bucket

Authentication

Option 1: gcloud CLI (recommended for development)

gcloud auth application-default login

Basecut uses Application Default Credentials from ~/.config/gcloud. Option 2: Service account key

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

Option 3: Workload Identity (recommended for GKE) No credentials needed—pods with Workload Identity automatically authenticate.

Required Permissions

Grant the service account Storage Object Admin on the bucket:

gcloud storage buckets add-iam-policy-binding gs://my-basecut-snapshots \
  --member=serviceAccount:basecut@project.iam.gserviceaccount.com \
  --role=roles/storage.objectAdmin

Or use a custom role with:

storage.objects.create
storage.objects.get
storage.objects.list

Local Filesystem

Store snapshots on your local machine. Useful for development and air-gapped environments.

Configuration

# basecut.yml
output:
  provider: local
  path: /absolute/path/to/snapshots
  format: directory

Relative paths are allowed, but absolute paths are recommended for clarity.

Directory Structure

Local output writes the snapshot artifact directly to your configured output.path:

/absolute/path/to/snapshots/
├── manifest.json
├── schema.json
├── warnings.json      # optional
└── tables/
    ├── public.users.csv.gz
    └── public.orders.csv.gz

Machine Identification

Local snapshots capture machine metadata for safety. When restoring on a different machine, Basecut warns you but allows the operation if you have access to the file path.

Use Cases

Development - Quick iteration without cloud storage setup
Air-gapped environments - No internet access required
Testing - Snapshots stay on your machine, no cloud costs

Not recommended for teams: Local snapshots can’t be shared without manual file copying. Use S3/GCS for team collaboration.

Choosing a Provider

Provider	Best For	Team Sharing	Agent Support	Cost
S3	Teams, production workflows	✅ Yes	✅ Yes	S3 storage + egress
GCS	GCP-native teams	✅ Yes	✅ Yes	GCS storage + egress
Local	Development, testing	❌ No	❌ No (local execution only)	Free (disk space)

Recommendation: Start with local for initial testing, migrate to S3/GCS when collaborating with teams or using self-hosted agents.

Snapshot Naming and Versioning

Reference snapshots by name and optional version:

# Latest version of a snapshot
basecut snapshot restore dev-seed:latest

# Specific tag version
basecut snapshot restore dev-seed:brave-lion

# Implicit latest
basecut snapshot restore dev-seed

Each snapshot create with the same --name creates a new tagged version. Previous versions remain accessible.

Next Steps

Execution Modes

Understand how storage provider affects execution mode

CI/CD Integration

Use cloud storage in GitHub Actions

YAML Reference

Complete output configuration options

Troubleshooting

Debug storage authentication issues

Getting Started

Core Concepts

Configuration

Workflows

Integrations

CLI Reference

Deployment

Reference

Storage Providers

AWS S3 (Recommended for Teams)

Configuration

Authentication

S3-Compatible Backends (Cloudflare R2, MinIO, LocalStack)

Required Permissions

Bucket Organization

Google Cloud Storage (Recommended for Teams)

Configuration

Authentication

Required Permissions

Local Filesystem

Configuration

Directory Structure

Machine Identification

Use Cases

Choosing a Provider

Snapshot Naming and Versioning

Next Steps

Execution Modes

CI/CD Integration

YAML Reference

Troubleshooting

​AWS S3 (Recommended for Teams)

​Configuration

​Authentication

​S3-Compatible Backends (Cloudflare R2, MinIO, LocalStack)

​Required Permissions

​Bucket Organization

​Google Cloud Storage (Recommended for Teams)

​Configuration

​Authentication

​Required Permissions

​Local Filesystem

​Configuration

​Directory Structure

​Machine Identification

​Use Cases

​Choosing a Provider

​Snapshot Naming and Versioning

​Next Steps

Execution Modes

CI/CD Integration

YAML Reference

Troubleshooting

AWS S3 (Recommended for Teams)

Configuration

Authentication

S3-Compatible Backends (Cloudflare R2, MinIO, LocalStack)

Required Permissions

Bucket Organization

Google Cloud Storage (Recommended for Teams)

Configuration

Authentication

Required Permissions

Local Filesystem

Configuration

Directory Structure

Machine Identification

Use Cases

Choosing a Provider

Snapshot Naming and Versioning

Next Steps