CLI reference

Usage

s3ctl [flags]
s3ctl --help        # the commands you'll use most
s3ctl --help-full   # every flag, template and CSV column

Flags win over the JSON config, and the config wins over built-in defaults. Most flags have a config key of the same name in snake case, so --enable-versioning becomes enable_versioning; the tables note the exceptions. Without --config, s3ctl reads $XDG_CONFIG_HOME/s3ctl/config.json, then $HOME/.config/s3ctl/config.json.

Input

Which provider to use, which buckets to work on, and where the rest of the settings come from. Batch provisioning lists the CSV columns.

Flag	Default	Description
-c--config PATH	None	Path to a JSON config file. Flag only.
--provider NAME	s3	Provisioning provider: s3 or ovh.
-b--bucket NAMErepeatable	None	Bucket name to create or delete. In the config, bucket for one or buckets for a list.
--batch-file PATH	None	CSV file describing multiple bucket requests.

S3 connection

Used by the s3 provider. When neither a profile nor explicit keys are set, the AWS SDK’s standard credential discovery applies. Use a profile or explicit keys, not both.

Flag	Default	Description
--endpoint URL	None	S3 endpoint URL for S3-compatible services.
--region NAME	us-east-1	Bucket region.
--profile NAME	None	AWS profile name for SDK configuration.
--access-key ID	None	Access key for the S3 API client. Needs --secret-key.
--secret-key SECRET	None	Secret key for the S3 API client. Needs --access-key.
--session-token TOKEN	None	Session token for temporary credentials. Needs both keys.
--insecure	None	Disable TLS certificate verification.

Bucket settings

Use either a bucket policy file or a template, not both.

Flag	Default	Description
--enable-versioning	None	Enable bucket versioning after creation.
--bucket-policy-file PATH	None	Path to a JSON bucket policy document.
--bucket-policy-template NAME	None	Built-in bucket policy template: deny-insecure-transport or public-read.

Scoped credentials

For the s3 provider these go through the IAM API. See scoped credentials.

Flag	Default	Description
--create-scoped-credentials	None	Create a scoped IAM-style user and access key for each bucket.
--credential-policy-template NAME	bucket-readwrite	Policy for the scoped user: bucket-readonly, bucket-readwrite or bucket-admin.
--iam-endpoint URL	None	IAM API endpoint, when it isn't AWS IAM.
--iam-user-name NAME	None	Explicit IAM user name, for a run with a single bucket.
--iam-user-prefix PREFIX	None	Prefix for automatically generated IAM user names.
--iam-path PATH	None	IAM path for generated users.

OVHcloud

Used with --provider ovh. When no OVHcloud authentication is set, go-ovh’s standard discovery applies, including ovh.conf.

Flag	Default	Description
--ovh-service-name PROJECT_ID	None	Public Cloud project service name, the project's long ID.
--ovh-api-endpoint URL	None	OVHcloud API endpoint name or URL.
--ovh-client-id ID	None	OAuth2 client ID.
--ovh-client-secret SECRET	None	OAuth2 client secret.
--ovh-access-token TOKEN	None	OVHcloud access token.
--ovh-application-key KEY	None	Application key, for classic API credentials.
--ovh-application-secret SECRET	None	Application secret, for classic API credentials.
--ovh-consumer-key KEY	None	Consumer key, for classic API credentials.
--ovh-s3-endpoint URL	None	Override the S3 endpoint URL OVHcloud returns.
--ovh-user-role ROLE	objectstore_operator	Public Cloud user role for created object storage users.
--ovh-storage-policy-role ROLE	readWrite	Access policy role: admin, deny, readOnly, readWrite or replication.
--ovh-encrypt-data	None	Enable server-side encryption with OVH-managed keys.
--ovh-tag KEY=VALUErepeatable	None	Tag to apply to OVHcloud containers. In the config, an ovh_tags object.
--ovh-rotate-credentials	None	Rotate each existing bucket's S3 credentials instead of creating containers.
--ovh-repair-policies	None	Reapply scoped S3 and container policies to existing bucket users without rotating credentials.

Lifecycle and output

--delete, --ovh-rotate-credentials and --ovh-repair-policies are separate modes; use one at a time.

Flag	Default	Description
--dry-run	None	Show the planned actions without making changes.
--delete	None	Delete each bucket instead of creating it. Config key delete_bucket.
--force	None	Let a delete remove bucket contents first. Without it, only empty buckets are deleted.
-o--output FORMAT	text	Output format: text or json. Failures are JSON too when this is json.
--timeout DURATION	10m0s	Overall operation timeout, such as 30s, 5m or 1h.
-h--help	None	Show the short reference. Flag only.
--help-full	None	Show every flag, template and CSV column. Flag only.
--version	None	Show version information. Flag only.