← 🏠


Bucket is a tool for interacting with Amazon S3 buckets.

Click here to download the zip file containing binaries for the following platforms:


Let's say we have a bucket called "mybucket" in region "us-west-1". First you need to initialize Bucket:

$ bucket init
Created .bucket file. Please edit the file to configure.
Note that bucket_url should be the full URL with trailing slash like:

You should edit ".bucket" to contain the URL of "mybucket" and your AWS credentials:

  "bucket_url" : "https://mybucket.s3.us-west-1.amazonaws.com/",
  "aws_id" : "<your aws id>",
  "aws_key" : "<your aws key>"

Now you can interact with the bucket. Let's say your current folder looks like this (note that ".bucket" is hidden):

$ tree
├── hello.txt
└── some
    └── folder
        └── file.txt

You can sync your local folder to the bucket like so:

$ bucket sync
 -> hello.txt
 -> some/folder/file.txt
New revision: 1666469415

Note that syncing skips dotfiles (like ".bucket"), and creates a special local file called "_revision" and a special bucket object called ".manifest". You shouldn't modify those files.

$ ls
hello.txt  _revision  some
$ bucket list
Sun Oct 23 15:44:32 2022    152 B   .manifest
Sun Oct 23 15:44:32 2022      3 B   hello.txt
Sun Oct 23 14:53:15 2022  319.8 KB  some/folder/file.txt
320.0 KB Total

Any local or remote modifications, including deletions, will be picked up on the next sync:

$ rm hello.txt
$ touch yo.txt
$ bucket sync
 -> yo.txt
 -x hello.txt
New revision: 1666471478

The sync command alone should handle most use cases. However, Bucket provides other commands for managing objects individually as well.


	bucket - show this message
	bucket init - initialize .bucket file
	bucket list - list bucket contents
	bucket sync - sync current folder with bucket
	bucket del [bucket path] - delete from bucket
	bucket get [bucket path] - download from bucket
	bucket put [local path] - upload to bucket

How is this different than rclone?

Rclone is a much larger binary (~40 MB) compared to Bucket (<1 MB), and supports other clouds besides AWS. Rclone's "bisync" is similar to Bucket's "sync", but Bucket takes a different approach: