A command line for S3 and R2, built for you and your AI agent

Quick start

Install Blob0, connect a storage profile in the desktop app, then copy the CLI executable path from Settings → CLI & Skills.

1. Download Blob0 and open it once on your Mac.
2. In Settings → CLI & Skills, use the copy button next to the CLI path. Paste that exact path into Terminal or your agent’s shell command.
3. Connect and save a profile in Blob0. Storage commands need that profile’s credentials in macOS Keychain and a valid license or active trial.
4. Use the active profile, or pass --profile NAME_OR_ID to choose another saved profile.

alias blob0='/absolute/path/copied/from/Settings'
blob0 profiles

For a shorter command, you can add an alias to your shell configuration or create a symlink in a directory already on PATH. Keep the copied executable path in quotes if it contains spaces.

Command cheat sheet

Use the global --profile NAME_OR_ID option before a command to select a saved connection. put, get, mv, and cp accept --dry-run, --no-clobber, and --concurrency N (default 4, range 1–32); rm accepts --dry-run.

Output formats and exit codes

{
  "ok": true,
  "dryRun": true,
  "total": 1,
  "succeeded": 0,
  "skipped": 0,
  "failed": 0,
  "bytes": 0,
  "items": [
    { "src": "./report.csv", "dst": "reports/report.csv", "size": 2048, "status": "planned" }
  ]
}

{"error":{"kind":"...","message":"...","code":null}}

0  success (skips are allowed)
1  other, I/O, or cancelled
2  command usage
3–9 not_found, auth, license, config, network, s3, conflict
10 a multi-item batch contains failures

Commands return JSON on stdout, including batch summaries with per-item status. cat writes raw bytes, and skills print writes Markdown. Help and version use the CLI parser’s plain text. Command errors go to stderr as JSON. Failed items inside a multi-item batch stay in stdout items; exit code 10 means you should inspect those items for failures.

Safe workflow

Use --dry-run to inspect the planned work before a write. It checks listings or object metadata and does not write object data. Review the planned keys and destinations, then run the command without --dry-run when you are ready.

blob0 --profile archive find "" exports/ --older-than 90d --sort date
blob0 --profile archive ls exports/ -r

blob0 ls tmp/ -r
blob0 rm tmp/ -r --dry-run
# Review every item with status "planned"
blob0 rm tmp/ -r

Deletion is permanent. Recursive deletion of the bucket root (empty key or /) is refused unless you pass --yes-really-delete-everything. Even with that acknowledgement, preview the root operation first and verify the bucket selected by your profile.

blob0 rm "" -r --dry-run --yes-really-delete-everything
# Only after reviewing the complete plan:
blob0 rm "" -r --yes-really-delete-everything

AWS CLI S3 mapping

Blob0 operates on the bucket in the selected profile, so pass object keys and prefixes instead of s3://bucket/ URIs. These commands cover common file operations; Blob0 is not a drop-in replacement for the full AWS CLI.

The desktop app does not live-refresh its file list after a separate CLI process changes the bucket. Refresh or revisit the prefix in Blob0 to load the latest listing.

Choosing between Blob0, s5cmd, and rclone

These mature open-source tools serve different workflows. s5cmd describes itself as a parallel S3 and local-filesystem tool; rclone provides commands across many cloud-storage backends, including sync and mount workflows.

Blob0’s CLI does not implement s5cmd’s or rclone’s full command sets, mount support, or general-purpose sync. Keep the tool that fits your automation and scale; Blob0’s distinction is that its Mac GUI, CLI, profile, and Keychain access share one local setup. Actual performance depends on the Mac, network, and storage provider.

Upload to R2 and share a link

The same commands work with Cloudflare R2 or another configured S3-compatible profile. The destination is a key prefix inside the profile’s bucket.

blob0 put -r ./photos media/ --dry-run
blob0 put -r ./photos media/ --no-clobber
blob0 share media/photos/cover.jpg --expiry 86400

Presigned share expiry is clamped to 1 second through 7 days; the default is 1 hour. --upload creates a presigned upload URL. --public uses the profile’s configured public base URL, which is not an expiring presigned link. Treat presigned URLs as bearer credentials: anyone holding one can use it while the signature and storage permissions remain valid.

Give an AI agent the Blob0 Skill

The bundled official Skill is a SKILL.md instruction file. Export it from Settings → CLI & Skills, or use the CLI commands below. Choose the Skill directory used by Claude Code, Codex, or Cursor; Blob0 exports the file but does not configure the agent for you.

blob0 skills list
blob0 skills print blob0
blob0 skills export ~/.claude/skills

---
name: blob0
description: Operate a Cloudflare R2 or any S3-compatible bucket with the blob0 CLI. Use to browse, upload files or folders, download, organize, share, audit, or safely clean up the user's storage.
---

# blob0 CLI

Use the desktop binary (path in Settings → CLI & Skills), with a configured
profile and valid license/trial. Credentials stay in the OS keychain.

The Skill teaches an agent how to use the local CLI. The agent still needs shell access to the Mac and the same configured Blob0 profile, credentials, and license or active trial as a person running commands.

CLI, not an MCP server

Blob0 provides a local executable that a person or agent can run through Terminal or a shell tool. The Skill is workflow guidance for that executable. Agents can reuse their existing shell access, parse JSON output and per-item batch status, and check process exit codes. Blob0 does not currently expose MCP tools; this integration needs no separate server process or MCP configuration. An agent that cannot run local shell commands cannot use this CLI integration.

Credential security

Access keys are stored in macOS Keychain. The CLI reads the selected profile’s secret when it connects; profile listings contain connection metadata, not the access key or secret. Do not paste credentials into command arguments or persistently log presigned URLs.

Supported providers

Use the profile you configured in Blob0 for Cloudflare R2, Amazon S3, Backblaze B2, Wasabi, MinIO, Alibaba Cloud OSS, Tencent Cloud COS, or another S3-compatible endpoint. Provider-specific API compatibility and endpoint settings still apply.

FAQ