@bucketos/cli

v1.0.7

Published

4 months ago

BucketOS Command Line Interface

0High
0Medium
0Low

knguyenvn

oclif s3 storage bucketos cli

BucketOS CLI

Professional command-line interface for BucketOS - The modern S3-compatible object storage platform

Installation • Quick Start • Commands • Features • Documentation

🚀 Installation

From npm (Recommended)

npm install -g @bucketos/cli

From Source

git clone https://github.com/pictor-network/bucketos
cd bucketos/apps/cli
pnpm install
pnpm build
npm link

Requirements

Node.js >= 18.0.0
npm/yarn/pnpm

⚡ Quick Start

# 1. Authenticate (interactive menu: email / google / access key)
bucketos auth login

# 2. Check status
bucketos status

# 3. List buckets
bucketos ls mybucket/

# 4. Upload file
bucketos upload file.txt mybucket/

# 5. Smart sync
bucketos sync ./local mybucket/remote/

📋 Commands

Authentication ⭐ INTERACTIVE

bucketos auth login                        # Interactive menu (email / Google / access key)
bucketos auth login --provider google      # Skip menu and go straight to Google OAuth
bucketos auth login --provider access      # Skip menu and enter access key / secret key
bucketos auth logout                       # Logout and clear all stored credentials

Interactive Example (New!):

$ bucketos auth login

🔐 Login to BucketOS

? Choose authentication method:
❯ 📧  Email / Password
  🔵  Google OAuth (device flow)
  🔑  Access Key / Secret Key

# If already logged in:
┌──────────────────────────┐
│ 👤 Current Session       │
├──────────────────────────┤
│ ✓ Already authenticated  │
│ Email: [email protected]  │
│ Role: Owner              │
└──────────────────────────┘

? What would you like to do?
❯ 🔄  Switch account
  🚪  Logout
  ❌  Cancel

Email/Password:

$ bucketos auth login
# Select: 📧 Email / Password

? Email: [email protected]
? Password: ********

⠋ Authenticating...
✓ Authentication successful!

┌─────────────────────────────────┐
│        ✨ Logged In             │
├─────────────────────────────────┤
│  Welcome back!                  │
│                                 │
│  Email: [email protected]        │
│  Role: Owner                    │
└─────────────────────────────────┘

Google OAuth (Device Code Flow):

$ bucketos auth login --provider google

┌────────────────────────────────────────┐
│ 🔐 Google Authentication               │
├────────────────────────────────────────┤
│ Please verify your account:            │
│                                         │
│ 1. Open: http://localhost:3000/api/... │
│ 2. The page will redirect to Google    │
│ 3. After approval, return here          │
│                                         │
│ Code expires in 15 minutes             │
└────────────────────────────────────────┘

⠋ Waiting for approval...
✓ Authentication successful!

List Objects

bucketos ls <path>               # List objects in bucket
bucketos ls mybucket/            # List all objects
bucketos ls mybucket/folder/     # List objects in folder
bucketos ls mybucket/ --long     # Detailed view with size & date

Example:

$ bucketos ls mybucket/ --long

📊 Objects in mybucket/

┌──────────┬─────────────────────┬─────────────────┐
│ Size     │ Modified            │ Name            │
├──────────┼─────────────────────┼─────────────────┤
│ 1.2 MB   │ 1/1/2024, 10:00:00  │ document.pdf    │
│ 500 KB   │ 1/2/2024, 11:30:00  │ image.jpg       │
│ 25 KB    │ 1/3/2024, 14:15:00  │ data.json       │
└──────────┴─────────────────────┴─────────────────┘

Total: 3 object(s), 1.7 MB

Upload Files

bucketos upload <source> <destination>            # Upload file/folder
bucketos upload file.txt mybucket/                # Upload single file
bucketos upload ./folder mybucket/ --recursive    # Upload entire folder

Example:

$ bucketos upload ./dist mybucket/production/ --recursive

📤 Uploading folder
Found 150 file(s)

✓ index.html (12 KB in 0.1s - 120 KB/s)
✓ app.js (850 KB in 0.8s - 1.1 MB/s)
⠋ video.mp4 [██████████░░░░░░░░░░] 50% 50MB/100MB 10MB/s ETA 5s

✓ Upload complete!

📊 Summary:
  Files: 150/150
  Size: 250 MB
  Time: 45.3s
  Speed: 5.5 MB/s

Download Files

bucketos download <source> <destination>          # Download file/folder
bucketos download mybucket/file.txt ./local.txt   # Download single file
bucketos download mybucket/folder/ ./ --recursive # Download entire folder

Example:

$ bucketos download mybucket/backup.zip ./

⠋ backup.zip [████████████████░░░░] 80% 800MB/1GB 25MB/s ETA 8s
✓ backup.zip (1 GB in 40.2s - 25.4 MB/s)

Smart Sync ⭐ KILLER FEATURE

bucketos sync <source> <destination>              # Bi-directional smart sync
bucketos sync ./local mybucket/remote/            # Local → Bucket (upload)
bucketos sync mybucket/remote/ ./local            # Bucket → Local (download)
bucketos sync ./src mybucket/backup/ --delete     # Mirror (delete extras)
bucketos sync ./dist mybucket/ --dry-run          # Preview only
bucketos sync mybucket/backup/ ./ --no-override   # Skip existing files

Example:

$ bucketos sync ./src mybucket/backup/

🔄 Analyzing files

⠋ Scanning local files...
✓ Found 1,250 local file(s)

⠋ Fetching remote files...
✓ Found 1,200 remote file(s)

⠋ Comparing files...

📊 Analysis
  Total: 1,250 files (500 MB)
  ✓ Unchanged: 1,200    ← Skipped! (MD5 match)
  ↑ New: 45 (25 MB)
  ↑ Modified: 5 (5 MB)

📤 Uploading 50 file(s)

✓ new-component.tsx (25 KB in 0.3s - 83 KB/s)
✓ updated-style.css (15 KB in 0.2s - 75 KB/s)
...

✓ Sync complete!

📊 Summary:
  Files: 50/50
  Size: 30 MB
  Time: 15.2s
  Speed: 2.0 MB/s

Why Smart?

✅ MD5 checksum comparison (100% accurate)
✅ Only uploads changed files
✅ 3-10x faster than re-uploading everything
✅ Bi-directional (upload or download)

Delete Files

bucketos rm <path>                               # Delete file/folder
bucketos rm mybucket/file.txt                    # Delete single file
bucketos rm mybucket/folder/ --recursive         # Delete entire folder
bucketos rm mybucket/old.txt --force             # Skip confirmation

Example:

$ bucketos rm mybucket/old-backup/  --recursive

? Delete 50 file(s)? (Y/n) y

🗑️  Deleting 50 file(s)...

✓ file1.txt
✓ file2.jpg
...

✓ Deleted 50/50 file(s)

Bucket Management

bucketos bucket list                             # List all buckets
bucketos bucket create                           # Create new bucket (interactive)
bucketos bucket create --name mybucket --region us-east-1  # Create with flags
bucketos bucket delete mybucket                  # Delete bucket
bucketos bucket delete mybucket --force          # Delete without confirmation

List Buckets:

$ bucketos bucket list

📦 Your Buckets

┌──────────────┬────────────┬────────────────┐
│ Name         │ Region     │ Created        │
├──────────────┼────────────┼────────────────┤
│ mybucket     │ us-east-1  │ 1/1/2024       │
│ production   │ us-west-2  │ 1/15/2024      │
└──────────────┴────────────┴────────────────┘

Total: 2 bucket(s)

Create Bucket:

$ bucketos bucket create

🪣 Create New Bucket

? Bucket name: my-new-bucket
? Region: (Use arrow keys)
❯ 🇺🇸  US East (N. Virginia) - us-east-1
  🇺🇸  US East (Ohio) - us-east-2
  🇺🇸  US West (N. California) - us-west-1
  🇺🇸  US West (Oregon) - us-west-2
  🇪🇺  EU (Ireland) - eu-west-1
  🇪🇺  EU (Frankfurt) - eu-central-1
  🇸🇬  Asia Pacific (Singapore) - ap-southeast-1
  🇯🇵  Asia Pacific (Tokyo) - ap-northeast-1

⠋ Creating bucket 'my-new-bucket'...
✓ Bucket created successfully!

┌──────────────────────────────────────┐
│ 🪣 New Bucket                        │
├──────────────────────────────────────┤
│ ✓ Bucket Created                     │
│                                      │
│ Name: my-new-bucket                  │
│ Region: us-east-1                    │
│ Created: 1/17/2025, 9:35:00 AM      │
└──────────────────────────────────────┘

Tip: Upload files with: bucketos upload <file> my-new-bucket/

Delete Bucket:

$ bucketos bucket delete

🗑️  Delete Bucket

? Select bucket to delete: (Use arrow keys)
❯ old-backup (us-east-1) - Created: 1/1/2024
  test-bucket (us-west-2) - Created: 1/5/2024

⚠️  WARNING: This will permanently delete bucket 'old-backup'
   All objects in this bucket will be deleted!

? Are you sure you want to delete bucket 'old-backup'? (y/N) y

⠋ Deleting bucket 'old-backup'...
✓ Bucket 'old-backup' deleted successfully!

API Key Management

bucketos key list                                # List all API keys
bucketos key create                              # Create new API key
bucketos key delete <key-id>                     # Delete API key

Example:

$ bucketos key create

? Enter a name for this API key: production-deploy

✓ API Key created successfully!

┌────────────────────────────────────────┐
│ 🔑 New API Key                         │
├────────────────────────────────────────┤
│ Name: production-deploy                │
│                                        │
│ Access Key:                            │
│ AK_1234567890abcdef                    │
│                                        │
│ Secret Key:                            │
│ SK_0987654321fedcba                    │
│                                        │
│ ⚠️  Save the secret key now!          │
│    You won't be able to see it again  │
└────────────────────────────────────────┘

$ bucketos key list

🔑 Your API Keys

┌──────────────────────┬──────────────┬──────────┐
│ Name                 │ Access Key   │ Created  │
├──────────────────────┼──────────────┼──────────┤
│ production-deploy    │ AK_1234...   │ 1/1/2024 │
│ staging              │ AK_5678...   │ 1/5/2024 │
└──────────────────────┴──────────────┴──────────┘

Total: 2 key(s)

Status & Quota

bucketos status                                  # Show account status & quota

Example:

$ bucketos status

📋 Your Account Status

╭─────────────────────────────────────╮
│          👤 Account                 │
├─────────────────────────────────────┤
│  Account Information                │
│                                     │
│  Email:   [email protected]          │
│  API URL: http://localhost:3000     │
╰─────────────────────────────────────╯

▸ Quota Usage

  Storage
    [████████████████░░░░] 80% 8GB / 10GB

  Bandwidth
    [██████░░░░░░░░░░░░░░] 30% 15GB / 50GB

  Requests
    [███░░░░░░░░░░░░░░░░░] 15% 150K / 1M

Tip: Upgrade your plan for more quota

Version & Updates

bucketos --version                               # Show version
bucketos update                                  # Update to latest version
bucketos update --version 1.2.0                  # Install specific version
bucketos update check                            # Check for updates
bucketos update stable                           # Update to stable channel
bucketos update beta                             # Update to beta channel

Example:

$ bucketos --version
@bucketos/cli/1.0.0 darwin-arm64 node-v22.20.0

$ bucketos update

╭────────────────────────────────────────╮
│     🆕 New Version Available           │
├────────────────────────────────────────┤
│                                        │
│  Update available: 1.0.0 → 1.2.0      │
│                                        │
│  Run: bucketos update                  │
╰────────────────────────────────────────╯

⠋ Downloading update...
✓ Updated to 1.2.0

Help

bucketos --help                                  # Show all commands
bucketos <command> --help                        # Show command help
bucketos auth login --help                       # Detailed help

🎨 Features

Beautiful UI

✅ Gradient colored headers
✅ Progress bars with speed & ETA
✅ Table formatting
✅ Boxed messages
✅ Icons & symbols
✅ Syntax highlighting

Smart Operations

✅ MD5-based sync (only changed files)
✅ Bi-directional sync (upload or download)
✅ Parallel file scanning
✅ Resume support (coming soon)
✅ Bandwidth control (coming soon)

Developer Friendly

✅ Simple syntax (no s3:// prefix)
✅ Interactive prompts
✅ Clear error messages
✅ Helpful tips
✅ Auto-completion (coming soon)

Enterprise Features

✅ JWT authentication
✅ Email/Password login
✅ Google OAuth (Device Code Flow)
✅ API Key management
✅ Config management (~/.bucketos)
✅ Auto-update checking
✅ Version management
✅ Rollback support

📚 Documentation

In-Depth Guides

COMPARISON.md - vs AWS CLI comparison
PUBLISHING.md - How to publish to npm
VERSION_MANAGEMENT.md - Version & update guide
UI_UX_GUIDE.md - UI/UX design system

Get Help

# General help
bucketos --help

# Command-specific help
bucketos sync --help
bucketos upload --help

# Examples
bucketos <command> --help

⚙️ Configuration

Config File Location

~/.bucketos/config.json

Config Structure

{
  "apiUrl": "http://localhost:3000",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "email": "[email protected]"
}

Change API URL

# Edit config manually
nano ~/.bucketos/config.json

# Or set via environment
export BUCKETOS_API_URL=https://api.bucketos.com

�� Development

Setup

# Clone repo
git clone https://github.com/pictor-network/bucketos
cd bucketos/apps/cli

# Install dependencies
pnpm install

# Build
pnpm build

# Link locally
npm link

Dev Mode

# Run without building
./bin/dev auth login
./bin/dev status

Testing

# Run tests
pnpm test

# Lint
pnpm lint

# Build
pnpm build

📊 Comparison with AWS CLI

| Feature | AWS CLI | BucketOS CLI | Winner | |---------|---------|--------------|--------| | Syntax | Complex | Simple | 🏆 BucketOS | | Setup | Keys + endpoint | Email/Password | 🏆 BucketOS | | Sync | Size/time | MD5 checksum | �� BucketOS | | UI | Plain text | Beautiful colors | 🏆 BucketOS | | Progress | None | Real-time with ETA | 🏆 BucketOS | | Speed | Baseline | 3-10x faster (sync) | 🏆 BucketOS |

Examples

# AWS CLI (Complex)
aws s3 ls --endpoint-url http://localhost:4000
aws s3 cp file.txt s3://bucket/ --endpoint-url http://localhost:4000
aws s3 sync ./local s3://bucket/remote/ --endpoint-url http://localhost:4000

# BucketOS CLI (Simple)
bucketos ls mybucket/
bucketos upload file.txt mybucket/
bucketos sync ./local mybucket/remote/

Much simpler! No s3:// prefix, no --endpoint-url flag!

💡 Tips & Tricks

Shell Aliases

# Add to ~/.zshrc or ~/.bashrc
alias bos='bucketos'
alias bosup='bucketos upload'
alias bosdown='bucketos download'
alias bossync='bucketos sync'
alias bosstat='bucketos status'

# Usage
bos ls mybucket/
bosup file.txt mybucket/
bossync ./src mybucket/backup/

Parallel Uploads (Coming Soon)

bucketos upload ./folder mybucket/ --parallel 10

Watch Mode (Coming Soon)

# Auto-sync on file changes
bucketos sync ./src mybucket/backup/ --watch

🐛 Troubleshooting

Not Logged In

bucketos auth login

Connection Refused

Check that Control Plane is running:

cd apps/control-plane
pnpm dev

Clear Config

rm -rf ~/.bucketos
bucketos auth login

Check Version

bucketos --version

Update CLI

bucketos update

Get Help

bucketos --help
bucketos <command> --help

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md

Report Issues

https://github.com/pictor-network/bucketos/issues

Submit PRs

https://github.com/pictor-network/bucketos/pulls

📄 License

MIT License - see LICENSE

🔗 Links

Website: https://bucketos.com
Documentation: https://docs.bucketos.com
GitHub: https://github.com/pictor-network/bucketos
Discord: https://discord.gg/bucketos
Twitter: https://twitter.com/bucketos

⭐ Why BucketOS CLI?

1. Simpler Syntax

No more s3:// prefix or --endpoint-url flags!

2. Smarter Sync

MD5-based comparison only uploads truly changed files.

3. Beautiful UI

Professional progress bars, colors, and formatting.

4. Faster

3-10x faster for typical sync workflows.

5. Better UX

Interactive prompts, helpful tips, clear errors.

Made with ❤️ by the BucketOS Team

⬆ Back to Top

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

BucketOS CLI

🚀 Installation

From npm (Recommended)

From Source

Requirements

⚡ Quick Start

📋 Commands

Authentication ⭐ INTERACTIVE

List Objects

Upload Files

Download Files

Smart Sync ⭐ KILLER FEATURE

Delete Files

Bucket Management

API Key Management

Status & Quota

Version & Updates

Help

🎨 Features

Beautiful UI

Smart Operations

Developer Friendly

Enterprise Features

📚 Documentation

In-Depth Guides

Get Help

⚙️ Configuration

Config File Location

Config Structure

Change API URL

�� Development

Setup

Dev Mode

Testing

📊 Comparison with AWS CLI

Examples

💡 Tips & Tricks

Shell Aliases

Parallel Uploads (Coming Soon)

Watch Mode (Coming Soon)

🐛 Troubleshooting

Not Logged In

Connection Refused

Clear Config

Check Version

Update CLI

Get Help

🤝 Contributing

Report Issues

Submit PRs

📄 License

🔗 Links

⭐ Why BucketOS CLI?

1. Simpler Syntax

2. Smarter Sync

3. Beautiful UI

4. Faster

5. Better UX