CLI Reference

Cloodsy S3 includes a built-in CLI for server and resource management. All CLI commands work while the server is running — SQLite WAL mode allows concurrent access.

Server

./cloodsys3 serve                        # Start with defaults (port 9000)
./cloodsys3 serve -config config.yaml    # Start with custom config file

See Configuration for all YAML options.

Bucket Management

./cloodsys3 bucket create <name>                          # Create a bucket
./cloodsys3 bucket create <name> --storage-dir=/mnt/ssd   # Create with custom storage directory
./cloodsys3 bucket list                                   # List all buckets
./cloodsys3 bucket info <name>                            # Show bucket details
./cloodsys3 bucket delete <name>                          # Delete bucket (must be empty)
./cloodsys3 bucket quota <name> 10GB                      # Set storage limit (KB/MB/GB/TB, 0=unlimited)
./cloodsys3 bucket storage <name> --dir=/new/path         # Move storage to new location
./cloodsys3 bucket storage <name> --dir=                  # Reset to default storage

Credential Management

Each bucket can have multiple access/secret key pairs. A key grants access only to the bucket it belongs to.

./cloodsys3 credential create <bucket>              # Create read-write key pair
./cloodsys3 credential create <bucket> --read-only  # Create read-only key pair
./cloodsys3 credential list <bucket>                # List keys for a bucket
./cloodsys3 credential delete <access-key>          # Revoke a specific key

Permission model:

  • read-write (default) — GET, PUT, DELETE, HEAD, POST — full access
  • read-only — GET, HEAD, ListObjects only — writes return AccessDenied

Versioning

./cloodsys3 bucket versioning enable <name>    # Enable versioning
./cloodsys3 bucket versioning suspend <name>   # Suspend versioning
./cloodsys3 bucket versioning status <name>    # Check current state

When enabled, every PUT creates a new version with a unique ID. Deleting an object creates a delete marker instead of removing data. Previous versions remain accessible by version ID.

Lifecycle Rules

Automatically expire objects after a specified number of days.

./cloodsys3 bucket lifecycle set <name> --days=30                  # Expire all objects after 30 days
./cloodsys3 bucket lifecycle set <name> --days=7 --prefix=logs/    # Expire only objects under logs/
./cloodsys3 bucket lifecycle get <name>                            # List rules
./cloodsys3 bucket lifecycle delete <name>                         # Delete all rules
./cloodsys3 bucket lifecycle delete <name> --prefix=logs/          # Delete specific rule

The background cleaner runs at a configurable interval (default 1h) and removes expired objects in batches of 100.

Custom Storage Directories

By default all buckets store data under the global root_dir. You can assign custom storage directories per bucket for multi-disk setups:

# Hot data on SSD
./cloodsys3 bucket create hot-data --storage-dir=/mnt/ssd

# Archives on HDD
./cloodsys3 bucket create archives --storage-dir=/mnt/hdd

# Move an existing bucket to a new location (migrates data)
./cloodsys3 bucket storage my-bucket --dir=/mnt/nvme

# Verify
./cloodsys3 bucket info hot-data
# Storage: /mnt/ssd/hot-data/ (custom)

Notes:

  • --storage-dir / --dir must be an absolute path
  • Deleting a bucket removes its storage directory regardless of location
  • Server restart required after CLI-based storage changes while server is running

Webhook Notifications

Receive HTTP callbacks when objects are created or deleted.

./cloodsys3 bucket webhook add <name> --url=https://example.com/hook
./cloodsys3 bucket webhook add <name> --url=https://example.com/hook --events=s3:ObjectCreated:* --secret=mysecret
./cloodsys3 bucket webhook list <name>
./cloodsys3 bucket webhook delete <name> --id=<webhook-id>

Supported events: s3:ObjectCreated:Put, s3:ObjectCreated:Copy, s3:ObjectRemoved:Delete, or * for all.

When a secret is provided, requests include an X-Cloodsy-Signature HMAC-SHA256 header for payload verification. Events are delivered asynchronously with 3 retries and exponential backoff (1s, 2s, 4s).

Admin Management

./cloodsys3 admin create <username>                     # Create with auto-generated password
./cloodsys3 admin create <username> --password=mypass    # Create with custom password
./cloodsys3 admin list                                  # List admin users
./cloodsys3 admin delete <username>                     # Delete admin user
./cloodsys3 admin password <username>                   # Reset with auto-generated password
./cloodsys3 admin password <username> --password=new    # Reset with custom password

Admin users authenticate with the Admin REST API. Passwords are stored as bcrypt hashes. The Admin API must be enabled in config.yaml — see Configuration.

Self-Update

./cloodsys3 update --check     # Check for updates without installing
./cloodsys3 update             # Download and install latest version

The update command detects your OS and architecture automatically and downloads the matching binary from GitHub Releases.

Version Info

./cloodsys3 version

Shows version number, git commit hash, and build date.

Configuration AWS CLI Integration