Skip to main content
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. 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.
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

ProviderBest ForTeam SharingAgent SupportCost
S3Teams, production workflows✅ Yes✅ YesS3 storage + egress
GCSGCP-native teams✅ Yes✅ YesGCS storage + egress
LocalDevelopment, 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