Using AWS CLI with OtterStorage

OtterStorage is S3 API-compatible, so you can manage your buckets and objects with the official aws tool without installing anything proprietary. You only need to point the client at our endpoint and use your bucket's access keys. In this guide you'll configure a dedicated profile and walk through the most common commands with real examples.

Prerequisites

• Your bucket's credentials: access key and secret key (generated per bucket from the console).
• The OtterStorage S3 endpoint: https://es-mad-1.s3.otterstorage.io
• A region. In the examples we use eu-mad.

If you don't have keys yet, see the documentation to create a bucket and issue your credentials.

Install AWS CLI v2

We recommend AWS CLI version 2, which includes performance improvements and full support for multipart transfers. Install it for your operating system:

Linux (x86_64):

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

macOS:

curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"
sudo installer -pkg AWSCLIV2.pkg -target /

Windows: download and install the official MSI package, or use the winget package manager:

winget install -e --id Amazon.AWSCLI

Verify the installation. It should show a version starting with aws-cli/2:

aws --version

Configure an "otter" profile

Instead of modifying your default profile, create a named profile called otter. This way you can keep your AWS and OtterStorage credentials side by side without conflicts:

aws configure --profile otter

Answer the prompts with your details:

AWS Access Key ID [None]: TU_ACCESS_KEY
AWS Secret Access Key [None]: TU_SECRET_KEY
Default region name [None]: eu-mad
Default output format [None]: json

This writes the keys to ~/.aws/credentials and the region to ~/.aws/config, both under the [profile otter] section.

Point to the OtterStorage endpoint

By default the client points to AWS servers, so you need to redirect it to OtterStorage. There are two ways to do this.

Option A: pass --endpoint-url on each command

Useful for one-off tests. Add the flag to any command:

aws --profile otter --endpoint-url https://es-mad-1.s3.otterstorage.io s3 ls

Option B: set endpoint_url in ~/.aws/config (recommended)

AWS CLI v2 supports defining the endpoint in the configuration file, so you don't have to repeat the flag. Edit ~/.aws/config and set the profile section like this:

[profile otter]
region = eu-mad
output = json
endpoint_url = https://es-mad-1.s3.otterstorage.io

From now on you only need to specify the profile:

aws --profile otter s3 ls

If you'd rather not type --profile on every call, export the environment variable in your session:

export AWS_PROFILE=otter

In the rest of the guide we assume the endpoint is already configured in the profile; add --endpoint-url https://es-mad-1.s3.otterstorage.io manually if you use Option A.

High-level commands: aws s3

The aws s3 interface offers convenient commands for everyday work. Remember that at OtterStorage we don't charge for requests or deletes, so you can list and clean up objects without worrying about the cost of operations.

List the contents of a bucket (ls)

# List the contents of a bucket
aws --profile otter s3 ls s3://mi-primer-bucket

# List recursively with sizes
aws --profile otter s3 ls s3://mi-primer-bucket --recursive --human-readable --summarize

Upload and download objects (cp)

# Upload a file
aws --profile otter s3 cp ./informe.pdf s3://mi-primer-bucket/docs/informe.pdf

# Download a file
aws --profile otter s3 cp s3://mi-primer-bucket/docs/informe.pdf ./informe.pdf

# Upload an entire folder
aws --profile otter s3 cp ./assets s3://mi-primer-bucket/assets --recursive

Synchronize directories (sync)

sync copies only new or modified files, ideal for backups and deployments:

# Upload local changes to the bucket
aws --profile otter s3 sync ./sitio s3://mi-primer-bucket/sitio

# Sync, deleting in the destination what no longer exists in the source
aws --profile otter s3 sync ./sitio s3://mi-primer-bucket/sitio --delete

Since we don't bill for requests or deletes, running sync --delete periodically adds no per-operation cost.

Low-level operations: aws s3api

When you need fine-grained control (metadata, versioning, object-lock), use aws s3api, which exposes the S3 API calls one by one.

Upload an object with put-object

aws --profile otter s3api put-object \
  --bucket mi-bucket-api \
  --key docs/manual.pdf \
  --body ./manual.pdf \
  --content-type application/pdf

List objects with list-objects-v2

# List by prefix, limiting to 100 keys
aws --profile otter s3api list-objects-v2 \
  --bucket mi-bucket-api \
  --prefix docs/ \
  --max-keys 100

Multipart upload

For large files, AWS CLI splits the upload into parts and transfers them in parallel. With the high-level commands (cp and sync) this is automatic: when a file exceeds the configured threshold, the client performs a multipart upload without you having to do anything.

You can adjust the threshold and the size of each part in your configuration:

aws configure set s3.multipart_threshold 64MB --profile otter
aws configure set s3.multipart_chunksize 32MB --profile otter

After these adjustments, a normal upload will take advantage of multipart transparently:

aws --profile otter s3 cp ./video-4k.mov s3://mi-primer-bucket/media/video-4k.mov

If a multipart upload is interrupted, incomplete parts remain stored. You can list and abort them with s3api; since we don't charge for requests or deletes, this cleanup has no operation cost:

# See pending multipart uploads
aws --profile otter s3api list-multipart-uploads --bucket mi-primer-bucket

# Abort a specific upload
aws --profile otter s3api abort-multipart-upload \
  --bucket mi-primer-bucket \
  --key media/video-4k.mov \
  --upload-id EL_UPLOAD_ID

Presigned URLs (presign)

A presigned URL lets you share a private object for a limited time without exposing your keys. Generate it with s3 presign:

# URL valid for 3600 seconds (1 hour, the default)
aws --profile otter s3 presign s3://mi-primer-bucket/docs/informe.pdf

# URL valid for 7 days (604800 seconds, the usual maximum)
aws --profile otter s3 presign s3://mi-primer-bucket/docs/informe.pdf --expires-in 604800

The command returns a full URL that anyone can open in a browser until it expires.

Object versioning

Versioning keeps previous copies of each object, protecting you against accidental overwrites and deletes. Enable it with s3api:

# Enable versioning
aws --profile otter s3api put-bucket-versioning \
  --bucket mi-bucket-api \
  --versioning-configuration Status=Enabled

# Check the status
aws --profile otter s3api get-bucket-versioning --bucket mi-bucket-api

# List all versions of the objects
aws --profile otter s3api list-object-versions --bucket mi-bucket-api

Object Lock

Object Lock applies a WORM retention model (write once, read many) that prevents an object from being deleted or modified before a given date. It is enabled when you create the bucket from the console (it also enables versioning) and cannot be enabled on a bucket that already exists. Once created, you apply per-object retention from the CLI.

Apply a retention when uploading or on an existing object. In COMPLIANCE mode, not even the owner can delete it before the specified date:

aws --profile otter s3api put-object \
  --bucket bucket-worm \
  --key contratos/2026.pdf \
  --body ./2026.pdf \
  --object-lock-mode COMPLIANCE \
  --object-lock-retain-until-date 2027-06-11T00:00:00Z

Check the current retention of an object:

aws --profile otter s3api get-object-retention \
  --bucket bucket-worm \
  --key contratos/2026.pdf

Summary

• Install AWS CLI v2 and create an otter profile with aws configure --profile otter.
• Set endpoint_url = https://es-mad-1.s3.otterstorage.io in ~/.aws/config so you don't repeat --endpoint-url.
• Use aws s3 (mb, cp, sync, ls) for everyday work and aws s3api for fine-grained control.
• Multipart is automatic for large files; presigned URLs share objects temporarily and securely.
• Enable versioning and Object Lock via s3api to protect your data. And remember: we don't charge for requests or deletes.

Need more detail on buckets, keys, or regions? Go back to the documentation.