r2pub

Upload one file to a public Cloudflare R2 bucket and print the final public URL.

r2pub is a small CLI for URL-first workflows. It is especially useful when another tool needs a public asset URL on stdout after upload, such as openzca voice publishing.

Features

• Upload a local file to Cloudflare R2 with a generated object key
• Print the final public URL to stdout
• Store non-secret config in a local config file
• Use macOS Keychain for secrets on macOS
• Support environment-variable credentials on macOS, Linux, and Windows
• Verify configuration and bucket access with doctor

Requirements

• Node.js 22+
• A Cloudflare R2 bucket
• A public bucket URL or custom domain
• R2 S3 credentials with object read/write access

Install

Clone and link locally:

npm install
npm link

Then verify:

r2pub --help

Setup

macOS

Use init to save non-secret config and store credentials in Keychain:

r2pub init

Linux / Windows

r2pub can use environment variables for credentials. init will still save the non-secret config file, but it will not try to persist secrets outside macOS Keychain.

Set one of these pairs:

export R2PUB_ACCESS_KEY_ID="..."
export R2PUB_SECRET_ACCESS_KEY="..."

or:

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

Then run:

r2pub init

Values you need during setup

• accountId: your Cloudflare account ID
• bucket: the R2 bucket name
• publicBaseUrl: the public base URL for the bucket, for example https://<bucket>.r2.dev
• prefix: optional object key prefix, default voice

Usage

Upload one file:

r2pub ./note.m4a

Print the computed URL without uploading:

r2pub --dry-run ./note.m4a

Override the prefix or object key:

r2pub --prefix uploads ./note.m4a
r2pub --key voice/custom/note.m4a ./note.m4a

Show config:

r2pub config show

Check readiness:

r2pub doctor

doctor exits with a non-zero code if config, credentials, or bucket access are missing.

OpenZCA Integration

Set:

export OPENZCA_VOICE_PUBLISH_CMD="r2pub"

Then openzca msg voice <threadId> ./file.mp3 can normalize the local file, upload it through r2pub, and send the returned public URL.

Config and Credential Storage

Non-secret config:

• macOS/Linux default: ~/.config/r2pub/config.json
• Windows default: %APPDATA%\\r2pub\\config.json
• Linux also respects XDG_CONFIG_HOME

Credential lookup order:

1. R2PUB_ACCESS_KEY_ID / R2PUB_SECRET_ACCESS_KEY
2. AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY
3. macOS Keychain entries saved by r2pub init

Exit Behavior

• Successful upload prints exactly one URL to stdout
• Errors go to stderr
• doctor returns exit code 1 when the setup is not healthy

Development

npm test
node src/cli.js --help

License

MIT