Quickstart

Install

Every channel tracks the same stable release. Pick the one that fits the machine.

Homebrew

brew tap netspeedy/s3ctl
brew install s3ctl

macOS and Linux. Upgrades arrive with brew upgrade.

Install script

curl -fsSL https://netspeedy.github.io/s3ctl/install.sh | bash

Installs into a bin directory you own and clears the macOS quarantine flag, because releases aren't notarised yet.

Debian / Ubuntu

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://netspeedy.github.io/s3ctl/apt/s3ctl-archive-keyring.gpg \
  | sudo tee /etc/apt/keyrings/s3ctl-archive-keyring.gpg >/dev/null

sudo tee /etc/apt/sources.list.d/s3ctl.sources >/dev/null <<'EOF'
Types: deb
URIs: https://netspeedy.github.io/s3ctl/apt/
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/s3ctl-archive-keyring.gpg
EOF

sudo apt update && sudo apt install s3ctl

Packages are signed with 7E6A 3D77 36C6 E573 16AC 2920 418B 37C1 CF46 53F1.

Docker

docker run --rm ghcr.io/netspeedy/s3ctl:v0.8.38

Multi-arch image on GHCR. :latest and semver tags are published too.

Check it’s on your path:

s3ctl --version

Preview a bucket

Plan a bucket and a key scoped to it. With --dry-run nothing is created; s3ctl only prints what it would do.

s3ctl --bucket app-data --create-scoped-credentials \
  --endpoint https://objects.example.com --dry-run

Output

S3 Provisioning Result
======================
Resources: 1
Mode: dry-run

Bucket: app-data
Endpoint: https://objects.example.com
Region: us-east-1
Bucket create planned: yes
Versioning requested: no
Encryption requested: no
Bucket policy planned: no
Scoped credentials planned: yes
IAM user: app-data
Credential policy template: bucket-readwrite
Access key ID: (generated on apply)
Secret access key: (generated on apply)

Where credentials come from

s3ctl finds S3 credentials the same way the AWS CLI does. Pass --profile to pick a named profile, or --access-key and --secret-key to set them directly.

On OVHcloud the same request goes through the Public Cloud API. There, --region is a Public Cloud region such as UK, GRA or EU-WEST-PAR, not an AWS-style region like us-east-1:

s3ctl --provider ovh --bucket app-data --region UK \
  --ovh-service-name PUBLIC_CLOUD_PROJECT_ID --dry-run

Create it

When the plan looks right, run it again without --dry-run. For a first real bucket:

1. Put shared provider settings in ~/.config/s3ctl/config.json. Configuration shows what goes in it.

2. Run s3ctl --bucket app-data --dry-run --output json.

3. Check the endpoint, region and credential scope in the plan.

4. Run s3ctl --bucket app-data --output json.

5. Store the returned access key and secret somewhere safe.

The secret is shown once

s3ctl prints the secret access key on the run that creates it and never again, so store it before you close the terminal.

Scripting it?

With --output json, s3ctl writes one JSON document to stdout whether the run succeeds or fails, and a failed run still exits non-zero.

Next steps

GuidesConfigurationKeep provider settings in a JSON config. Flags still win over it.GuidesBatch provisioningPlan and create many buckets, one scoped key each, from a CSV.OVHcloudOVHcloudOAuth2 service accounts, key rotation and policy repair.ReferenceCLI referenceEvery flag, default, template and CSV column in one place.