# Blobsy

> Track large files in Git with .bref pointers; store blobs in S3, GCS, Azure (via rclone), local directories, or custom backends. Use when a repo has large binary files, when files must sync across machines without committing bytes to Git, or when the user mentions blobsy, .bref, externalize, or a Git LFS alternative.

- Skill: `jlevy/blobsy` (Agent Skill, multi-file: 145 files)
- Install (CLI): `npx skillmds@latest add jlevy/blobsy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jlevy/blobsy/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: jlevy (https://skillmd.com/u/jlevy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jlevy/blobsy

---

# Blobsy Agent Skill

Git-native large file storage CLI. Track large files with `.bref` pointers in Git while
storing blobs in S3, Google Cloud Storage, Azure (via rclone), local directories, or
custom backends.

## Installation

If blobsy is not installed, run:

```bash
npm install -g blobsy@latest
blobsy setup --auto s3://bucket/prefix/
```

## When to Use

Use blobsy when:

- A repository contains large binary files (models, datasets, media, archives)
- Files need to be shared across machines without committing them to Git
- You need content-addressable, deduplicated blob storage
- The user mentions: blobsy, large files, blob storage, .bref, bref, externalize, Git
  LFS alternative

## Quick Reference

```bash
# Recommended workflow
blobsy add <path...>       # Track + stage to git (recommended)
blobsy push [path...]      # Upload blobs to backend
blobsy pull [path...]      # Download blobs from backend

# Low-level tracking (no git staging)
blobsy track <path...>     # Track files (creates .bref pointers)

# Diagnostics
blobsy status --json       # Current state (JSON)
blobsy doctor --json       # Health check (JSON)

# Configuration
blobsy config [key] [val]  # Get/set config (supports --global, --show-origin, --unset)

# Documentation
blobsy docs --readme       # Display README
blobsy docs [topic]        # User guide (--list for topics, --brief for summary)
```

## Key Options

- `blobsy add --min-size <size>`: Override externalization threshold (e.g. `100kb`,
  `5mb`)
- `blobsy doctor --fix`: Auto-fix detected issues
- `blobsy rm --remote --force`: DANGER: delete the blob from the backend (breaks git
  history)

## Current State

For dynamic info, use:

- `blobsy status --json` - Tracked files, sync state
- `blobsy doctor --json` - Configuration, health, issues

All commands accept: `--json`, `--quiet`, `--verbose`, `--dry-run`