MinIO Object Storage

Use the MinIO API via mc (MinIO Client) or curl to manage S3-compatible object storage for file uploads, downloads, and bucket operations.

Official docs: https://min.io/docs/minio/linux/reference/minio-mc.html

---

When to Use

Use this skill when you need to:

• Upload/download files to S3-compatible storage
• Manage buckets (create, list, delete)
• Generate pre-signed URLs for temporary file access
• List and search objects in storage
• Mirror/sync directories between local and remote

---

Prerequisites

1. Deploy MinIO server or use MinIO Play (public test server)
2. Get access credentials (Access Key and Secret Key)
3. Install MinIO Client (mc)

Install MinIO Client

# macOS
brew install minio/stable/mc

# Linux (amd64)
curl -O https://dl.min.io/client/mc/release/linux-amd64/mc
chmod +x mc && sudo mv mc /usr/local/bin/

# Verify installation
mc --version

Set Environment Variables

export MINIO_ENDPOINT="play.min.io"
export MINIO_ACCESS_KEY="your-access-key"
export MINIO_SECRET_KEY="your-secret-key"

For testing, use MinIO Play (public sandbox):

export MINIO_ENDPOINT="play.min.io"
export MINIO_ACCESS_KEY="Q3AM3UQ867SPQQA43P2F"
export MINIO_SECRET_KEY="zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG"

Configure mc Alias

mc alias set myminio https://${MINIO_ENDPOINT} ${MINIO_ACCESS_KEY} ${MINIO_SECRET_KEY}

---

Important: When using $VAR in a command that pipes to another command, wrap the command containing $VAR in bash -c '...'. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.

bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq .

How to Use

1. List Buckets

mc ls myminio

2. Create a Bucket

mc mb myminio/my-bucket

3. Upload a File

# Upload single file
mc cp /path/to/file.txt myminio/my-bucket/

# Upload with custom name
mc cp /path/to/file.txt myminio/my-bucket/custom-name.txt

# Upload directory recursively
mc cp --recursive /path/to/folder/ myminio/my-bucket/folder/

4. Download a File

# Download single file
mc cp myminio/my-bucket/file.txt /local/path/

# Download entire bucket
mc cp --recursive myminio/my-bucket/ /local/path/

5. List Objects in Bucket

# List all objects
mc ls myminio/my-bucket

# List recursively with details
mc ls --recursive --summarize myminio/my-bucket

6. Delete Objects

# Delete single file
mc rm myminio/my-bucket/file.txt

# Delete all objects in bucket
mc rm --recursive --force myminio/my-bucket/

# Delete bucket (must be empty)
mc rb myminio/my-bucket

7. Generate Pre-signed URL

Create temporary shareable links:

# Download URL (expires in 7 days by default)
mc share download myminio/my-bucket/file.txt

# Download URL with custom expiry (max 7 days)
mc share download --expire 2h myminio/my-bucket/file.txt

# Upload URL (for external uploads)
mc share upload myminio/my-bucket/uploads/

8. Mirror/Sync Directories

# One-way sync local to remote
mc mirror /local/folder/ myminio/my-bucket/folder/

# One-way sync remote to local
mc mirror myminio/my-bucket/folder/ /local/folder/

# Watch and sync changes continuously
mc mirror --watch /local/folder/ myminio/my-bucket/folder/

9. Get Object Info

# Get file metadata
mc stat myminio/my-bucket/file.txt

# Get bucket info
mc stat myminio/my-bucket

10. Search Objects

# Find by name pattern
mc find myminio/my-bucket --name "*.txt"

# Find files larger than 10MB
mc find myminio/my-bucket --larger 10MB

# Find files modified in last 7 days
mc find myminio/my-bucket --newer-than 7d

---

Using curl with Pre-signed URLs

For environments without mc, use pre-signed URLs with curl:

Upload with Pre-signed URL

# First, generate upload URL with mc
UPLOAD_URL=$(mc share upload --json myminio/my-bucket/file.txt | jq -r '.share')

# Then upload with curl
curl -X PUT --upload-file /path/to/file.txt "${UPLOAD_URL}"

Download with Pre-signed URL

# Generate download URL
DOWNLOAD_URL=$(mc share download --json myminio/my-bucket/file.txt | jq -r '.share')

# Download with curl
curl -o /local/path/file.txt "${DOWNLOAD_URL}"

---

Using curl with AWS Signature V2

For direct API access without mc (simple authentication):

#!/bin/bash
# minio-upload.sh - Upload file to MinIO

bucket="$1"
file="$2"
host="${MINIO_ENDPOINT}"
s3_key="${MINIO_ACCESS_KEY}"
s3_secret="${MINIO_SECRET_KEY}"

resource="/${bucket}/${file}"
content_type="application/octet-stream"
date=$(date -R)
signature_string="PUT\n\n${content_type}\n${date}\n${resource}"
signature=$(echo -en "${signature_string}" | openssl sha1 -hmac "${s3_secret}" -binary | base64)

curl -X PUT -T "${file}" --header "Host: ${host}" --header "Date: ${date}" --header "Content-Type: ${content_type}" --header "Authorization: AWS ${s3_key}:${signature}" "https://${host}${resource}"

Usage:

chmod +x minio-upload.sh
./minio-upload.sh my-bucket myfile.txt

---

Using AWS CLI

MinIO is fully compatible with AWS CLI:

# Configure AWS CLI for MinIO
aws configure set aws_access_key_id "${MINIO_ACCESS_KEY}"
aws configure set aws_secret_access_key "${MINIO_SECRET_KEY}"
aws configure set default.s3.signature_version s3v4

# List buckets
aws --endpoint-url "https://${MINIO_ENDPOINT}" s3 ls

# Upload file
aws --endpoint-url "https://${MINIO_ENDPOINT}" s3 cp file.txt s3://my-bucket/

# Download file
aws --endpoint-url "https://${MINIO_ENDPOINT}" s3 cp s3://my-bucket/file.txt ./

# List objects
aws --endpoint-url "https://${MINIO_ENDPOINT}" s3 ls s3://my-bucket/

---

Bucket Policies

Set Bucket to Public Read

mc anonymous set download myminio/my-bucket

Set Bucket to Private

mc anonymous set none myminio/my-bucket

Apply Custom Policy

# Create policy.json
cat > /tmp/policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
  {
  "Effect": "Allow",
  "Principal": {"AWS": ["*"]},
  "Action": ["s3:GetObject"],
  "Resource": ["arn:aws:s3:::my-bucket/public/*"]
  }
  ]
}
EOF

mc anonymous set-json /tmp/policy.json myminio/my-bucket

---

Guidelines

1. Use mc for most operations - It handles authentication and signing automatically
2. Pre-signed URLs for external access - Share files without exposing credentials
3. Use port 9000 for API - Port 9001 is typically the web console
4. Set appropriate expiry - Pre-signed URLs should expire as soon as practical (max 7 days)
5. Use mirror for backups - mc mirror --watch for continuous sync
6. Bucket naming rules - Lowercase, 3-63 characters, no underscores or consecutive dots