First Request

This tutorial takes 30 seconds. You will create an S3 bucket, upload a file, and read it back — first with curl, then with the AWS CLI.

Prerequisites

CloudMock must be running on localhost:4566. If it is not, see Installation.

Set credentials

CloudMock’s default root credentials are test / test. Export them so every command in this tutorial authenticates correctly:

export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export AWS_DEFAULT_REGION=us-east-1
export AWS_ENDPOINT_URL=http://localhost:4566

Option A: curl

Create a bucket

curl -X PUT http://localhost:4566/my-bucket

Expected output:

<?xml version="1.0" encoding="UTF-8"?>
<CreateBucketResult>
  <Location>/my-bucket</Location>
</CreateBucketResult>

Upload a file

echo "Hello, CloudMock!" | curl -X PUT --data-binary @- \
  http://localhost:4566/my-bucket/hello.txt

Expected output: HTTP 200 with an empty body and an ETag header.

List objects

curl http://localhost:4566/my-bucket?list-type=2

Expected output:

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
  <Name>my-bucket</Name>
  <Contents>
    <Key>hello.txt</Key>
    <Size>18</Size>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
</ListBucketResult>

Read the file back

curl http://localhost:4566/my-bucket/hello.txt

Expected output:

Hello, CloudMock!

Option B: AWS CLI

The AWS CLI is the standard way to interact with AWS services. If you have it installed, it works with CloudMock out of the box once AWS_ENDPOINT_URL is set.

Create a bucket

aws s3 mb s3://my-bucket

Expected output:

make_bucket: my-bucket

Upload a file

echo "Hello, CloudMock!" > hello.txt
aws s3 cp hello.txt s3://my-bucket/hello.txt

Expected output:

upload: ./hello.txt to s3://my-bucket/hello.txt

List objects

aws s3 ls s3://my-bucket

Expected output:

2026-03-31 00:00:00         18 hello.txt

Read the file back

aws s3 cp s3://my-bucket/hello.txt -

Expected output:

Hello, CloudMock!

What just happened

You pointed standard AWS tools at localhost:4566 and used them exactly as you would against real AWS. CloudMock handled the S3 API calls — creating the bucket in memory, storing the object, and returning it on request.

No AWS account. No internet. No cost.

Want a full example?

Check out the todo demo project — a working app that uses S3, DynamoDB, SQS, and SNS together, with a web UI. Available in Node.js, Python, and Go.

Next step

You have made your first request. Now configure your SDK to use CloudMock in your application code.