blobz

A blazingly fast terminal-based S3-compatible storage explorer

Explore and manage your cloud storage directly from the terminal with support for AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces, and any S3-compatible service.

Features

• 📁 Interactive file browser with tree and folder view modes
• 🔍 Search/filter files with regex and glob patterns
• 🔖 Bookmark frequently accessed files
• 📊 Sort by name, size, date, or type
• 📎 Generate presigned shareable URLs with QR codes
• 👁️ Preview text files in the terminal
• 🗑️ Delete files and folders
• 🌐 Multi-provider support (AWS, Cloudflare R2, MinIO, DigitalOcean Spaces)

Why blobz?

• 🚀 Fast: Built with Bun and optimized for performance
• 🔌 Universal: Works with any S3-compatible storage service
• 💾 Stateful: Persistent bookmarks and shared links across sessions
• 🎨 Beautiful: Clean terminal UI built with Ink and React

Installation

Global Installation (Recommended)

bun add -g blobz

Local Project Dependency

bun add blobz

NPM/PNPM/Yarn

npm install -g blobz
# or
pnpm add -g blobz
# or
yarn global add blobz

Quick Start

Run the CLI

After installation, simply run:

blobz

First-Time Setup

On first run, blobz will guide you through setting up your storage providers. You can configure multiple providers and switch between them seamlessly.

Configuration File (Recommended)

Create a blobz.config.js (or .ts, .mjs) file in your project root or home directory (~/.blobz/blobz.config.js):

// Can export a config object directly
export default {
  providers: [
    {
      name: 'aws-prod',
      type: 'aws',
      region: 'us-east-1',
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    }
  ],
  defaults: {
    viewMode: 'inline', // Optional: 'inline' (tree view) or 'folder' (single-level view)
  }
}

// Or export an async function for dynamic credentials
export default async function() {
  return {
    providers: [
      {
        name: 'aws-prod',
        type: 'aws',
        region: 'us-east-1',
        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
        buckets: ['my-bucket-1', 'my-bucket-2'], // Optional: limit to specific buckets
      },
      {
        name: 'cloudflare-r2',
        type: 'cloudflare-r2',
        accountId: process.env.CF_ACCOUNT_ID,
        accessKeyId: process.env.CF_R2_ACCESS_KEY_ID,
        secretAccessKey: process.env.CF_R2_SECRET_ACCESS_KEY,
      },
      {
        name: 'minio-local',
        type: 's3-compatible',
        endpoint: 'http://localhost:9000',
        region: 'us-east-1',
        accessKeyId: 'minioadmin',
        secretAccessKey: 'minioadmin',
        forcePathStyle: true,
      }
    ],
    defaults: {
      viewMode: 'folder', // Optional: 'inline' (tree view) or 'folder' (single-level view)
    }
  }
}

See blobz.config.example.js for more configuration examples.

Environment Variables (Legacy Mode)

If no config file is found, blobz falls back to environment variables:

export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_REGION=us-east-1  # Optional, defaults to us-east-1
export AWS_ENDPOINT=http://localhost:9000  # Optional, for S3-compatible services

Keybindings

Navigation

• ↑/↓ - Move selection up/down
• →/Enter - Expand folder (inline mode) or open folder (folder mode)
• ← - Collapse folder (inline mode) or go back (folder mode)

Filtering & Sorting

• / - Activate filter mode (supports regex and glob patterns)
  • * - Match any characters (e.g., *.txt)
  • ? - Match single character
  • /pattern/ - Use regex (e.g., /log.*error/i)
• o - Open sort menu
• n - Quick sort by name (press again to toggle direction)
• z - Quick sort by size
• t - Quick sort by date modified

File Actions

• p - Preview file content
• s - Generate shareable presigned URL with custom expiration
• b - Toggle bookmark for selected file
• m - View all bookmarks
• l - View all shared links
• a - Open action menu
• d - Delete file or folder (with confirmation)

View Modes

• v - Toggle between inline (tree) and folder view modes
• c - Collapse nearest parent folder (inline mode only)

General

• q or Ctrl+C - Quit
• ESC - Clear filter or close dialog

Shareable Link Dialog

• r - Toggle QR code visibility (when viewing a shareable link)

Provider Types

AWS S3

{
  name: 'aws-prod',
  type: 'aws',
  region: 'us-east-1',
  accessKeyId: 'YOUR_ACCESS_KEY',
  secretAccessKey: 'YOUR_SECRET_KEY',
  // Optional: use AWS profile instead of explicit credentials
  profile: 'default',
  // Optional: limit to specific buckets
  buckets: ['bucket1', 'bucket2'],
}

Cloudflare R2

{
  name: 'cloudflare-r2',
  type: 'cloudflare-r2',
  accountId: 'YOUR_ACCOUNT_ID',
  accessKeyId: 'YOUR_ACCESS_KEY',
  secretAccessKey: 'YOUR_SECRET_KEY',
  buckets: ['my-r2-bucket'],
}

S3-Compatible Services (MinIO, DigitalOcean Spaces, etc.)

{
  name: 'minio-local',
  type: 's3-compatible',
  endpoint: 'http://localhost:9000',
  region: 'us-east-1',
  accessKeyId: 'minioadmin',
  secretAccessKey: 'minioadmin',
  forcePathStyle: true,
}

Programmatic Usage

import { S3Explorer, ConfigLoader, ProviderFactory } from 'blobz'
import { render } from 'ink'

// Load config and create providers
const config = await ConfigLoader.load()
const providers = ProviderFactory.createClients(config.providers)

// Render the explorer
render(<S3Explorer providers={providers} />)

Configuration File Search Order

blobz searches for configuration files in the following order:

1. ./blobz.config.{js,ts,mjs,cjs,json,yaml,yml}
2. ~/.blobz/blobz.config.{js,ts,mjs,cjs,json,yaml,yml}
3. Falls back to environment variables

Configuration Options

Global Defaults

You can set default options in the defaults section of your config:

{
  defaults: {
    viewMode: 'inline', // 'inline' for tree view or 'folder' for single-level view
  }
}

Available defaults:

• viewMode: Set the initial view mode. Options: 'inline' (tree view, default) or 'folder' (single-level folder navigation)

Features Explained

Bookmarks

Bookmark files for quick access. Bookmarks are stored in ~/.blobz/bookmarks.json and persist across sessions.

Presigned URLs

Generate temporary shareable links that allow others to download files without AWS credentials. Features include:

• Flexible expiration times: Choose from presets (15 minutes, 1 hour, 6 hours, 1 day, 7 days) or enter a custom duration
• QR code generation: Toggle on-demand QR code display by pressing r in the shareable link dialog
• Link management: View all active and expired shared links with the l key
• Persistent storage: All shared links are saved in ~/.blobz/shared-links.json and tracked across sessions

Filter Patterns

• Simple glob: *.txt, test-*.log
• Regex: /error|warning/i, /\d{4}-\d{2}-\d{2}/

Sorting

Sort files by:

• Name - Natural sort (handles numbers intelligently)
• Size - File size in bytes
• Date - Last modified date
• Type - Directories first, then files (or reverse)

Each sort can be ascending or descending.

Development

# Install dependencies
bun install

# Run in development mode
bun run dev

# Run CLI locally
bun run cli

# Build
bun run build

# Run tests
bun test

License

MIT