92 lines
3.1 KiB
Markdown
92 lines
3.1 KiB
Markdown
---
|
|
name: r2-upload
|
|
description: Upload files and return a public or temporary URL. Use when you need to publish assets, share files, or provide upload helpers to other skills.
|
|
compatibility: Requires Python 3.8+ and PyYAML. Uses AWS SigV4 signing (no external SDK required).
|
|
metadata:
|
|
author: foundra
|
|
version: "2.1"
|
|
---
|
|
|
|
# R2 Upload
|
|
|
|
Upload files to R2/S3-compatible storage and return a URL.
|
|
|
|
## Use when
|
|
|
|
- Upload images, documents, or other assets to object storage
|
|
- Generate public URLs for web/CDN use
|
|
- Generate presigned URLs for temporary access
|
|
- Provide upload helpers to other skills (like tech-news)
|
|
|
|
## Prerequisites
|
|
|
|
- Python 3.8+ available as `python3`
|
|
- PyYAML (`python3 -m pip install pyyaml`)
|
|
- Config at `scripts/.r2-upload.yml` (bundled with the skill)
|
|
- Decide the bucket, object key/path, and visibility (public vs presigned)
|
|
- If you skip `--key`/`--key-prefix`, the default is `YYYY/MM/DD/<filename>`
|
|
|
|
## Recommended workflow
|
|
|
|
1. Confirm bucket/key and whether the URL should be public or presigned (avoid overwrites unless asked).
|
|
2. Verify config and bucket exist.
|
|
3. Upload with the CLI (recommended) or Python helper.
|
|
4. Return the URL and key; note whether it is public or temporary and the expiration.
|
|
|
|
## Quick commands
|
|
|
|
```bash
|
|
python3 scripts/r2-upload.py ./photo.jpg
|
|
python3 scripts/r2-upload.py ./photo.jpg --key images/YYYY/MM/DD/cover.jpg
|
|
python3 scripts/r2-upload.py ./report.pdf --key reports/YYYY/MM/DD/report.pdf
|
|
python3 scripts/r2-upload.py ./image.png --key-prefix images/YYYY/MM/DD
|
|
python3 scripts/r2-upload.py ./file.zip --presigned --expires 600
|
|
```
|
|
|
|
## Key options
|
|
|
|
- `--bucket <name>`: override the default bucket in config
|
|
- `--key <path>`: set the object key/path
|
|
- `--key-prefix <prefix>`: prepend prefix to the local filename
|
|
- `--expires <seconds>`: presigned URL expiration (1-604800)
|
|
- `--timeout <seconds>`: network timeout
|
|
- `--content-type <mime>`: override content type
|
|
- `--cache-control <value>`: set Cache-Control header
|
|
- `--content-disposition <value>`: set Content-Disposition header
|
|
|
|
## Behavior notes
|
|
|
|
- URL type (public vs presigned) is determined by the `public` field in bucket config.
|
|
- If no key is provided, the default key is `YYYY/MM/DD/<filename>`.
|
|
- Presigned URLs always use the storage endpoint (custom CDN domains are for public URLs).
|
|
- **Local mode**: Set `mode: local` in bucket config to copy files to a local `public` directory instead of uploading to S3. Requires `endpoint` (base URL) and optionally `public_dir` (default: `public`).
|
|
|
|
## Programmatic usage
|
|
|
|
```python
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
r2_dir = Path("/path/to/r2-upload") # update to your local path
|
|
sys.path.insert(0, str(r2_dir / "scripts"))
|
|
|
|
from upload import upload_file, batch_upload, fetch_and_upload
|
|
|
|
url = upload_file(
|
|
local_path="./image.jpg",
|
|
key="images/YYYY/MM/DD/image.jpg",
|
|
make_public=True
|
|
)
|
|
```
|
|
|
|
## Scripts
|
|
|
|
- `scripts/r2-upload.py`: CLI upload tool
|
|
- `scripts/upload.py`: Python helpers (`upload_file`, `batch_upload`, `fetch_and_upload`)
|
|
|
|
## References
|
|
|
|
- `references/CONFIGURATION.md` (provider config examples)
|
|
- `references/IMAGES.md` (image workflow)
|
|
- `references/TROUBLESHOOTING.md` (common errors)
|