Introduction

The AWS CLI s3 cp command can upload a file to S3 and attach metadata in the same operation. That is useful when you want objects to carry extra information such as source, document type, or cache hints. The key detail is that S3 metadata is stored as object metadata, so changing it later usually means copying the object again with replacement metadata.

Upload a File with Custom Metadata

The basic pattern is:

aws s3 cp ./report.pdf s3://my-bucket/reports/report.pdf \
  --metadata source=portal,document-type=invoice

This uploads the file and stores the custom metadata as part of the object.

The metadata keys and values are strings. They are retrieved later through S3 APIs and appear as user-defined metadata on the object.

Add Content-Type and Other Object Headers

Metadata is often used together with object headers such as content type or cache control.

1aws s3 cp ./app.js s3://my-bucket/assets/app.js \
2  --content-type application/javascript \
3  --cache-control "public,max-age=31536000" \
4  --metadata build=20260307,source=ci

This is common for static-asset pipelines where both HTTP behavior and custom metadata matter.

Verify the Metadata

After upload, confirm what S3 stored:

aws s3api head-object \
  --bucket my-bucket \
  --key reports/report.pdf

Look for the Metadata field in the output. That is the authoritative check, not the upload command itself.

Updating Metadata on an Existing Object

If an object already exists and you want to replace its metadata, s3 cp between S3 locations can do it with metadata replacement.

aws s3 cp s3://my-bucket/reports/report.pdf s3://my-bucket/reports/report.pdf \
  --metadata-directive REPLACE \
  --metadata source=backfill,document-type=invoice

This is effectively a copy operation onto the same key. The object data stays at the same path, but metadata is rewritten.

Understand --metadata-directive

When copying S3 to S3:

• 'COPY keeps existing metadata.'
• 'REPLACE writes the metadata you specify now.'

If you forget REPLACE during a self-copy metadata update, the old metadata is typically preserved and your new values may not take effect as intended.

Use s3api put-object When You Need Lower-Level Control

aws s3 cp is convenient, but s3api exposes lower-level object operations. For simple uploads, cp is usually enough. For more explicit automation or generated request structures, s3api put-object may be easier to reason about.

Example:

1aws s3api put-object \
2  --bucket my-bucket \
3  --key reports/report.pdf \
4  --body ./report.pdf \
5  --metadata source=portal,document-type=invoice

That is functionally similar but more API-shaped.

Metadata Naming and Limits

S3 user-defined metadata is best kept simple:

• Use small string values.
• Keep key naming consistent.
• Do not treat metadata like a large document store.

If you need complex searchable fields, store them in a database or catalog instead of overloading S3 metadata.

Practical Automation Example

A small shell script can upload with metadata derived from the environment:

1#!/usr/bin/env bash
2set -euo pipefail
3
4FILE_PATH="$1"
5BUILD_ID="${BUILD_ID:-local}"
6TARGET_KEY="artifacts/$(basename "$FILE_PATH")"
7
8aws s3 cp "$FILE_PATH" "s3://my-bucket/$TARGET_KEY" \
9  --metadata build-id="$BUILD_ID",source=release-script

This is useful in CI where object provenance matters.

Common Pitfalls

• Assuming metadata can be edited in place without copying the object again.
• Forgetting --metadata-directive REPLACE on S3-to-S3 metadata updates.
• Mixing custom metadata with HTTP headers and expecting them to behave the same way.
• Storing too much business data in metadata fields.
• Skipping head-object verification after upload.

Summary

• 'aws s3 cp can upload a file and attach metadata in one command.'
• Use --metadata key=value pairs for user-defined metadata.
• Use head-object to verify what S3 actually stored.
• Updating metadata on an existing object usually requires a copy with REPLACE.
• Keep metadata small, consistent, and purposeful rather than treating it like a document store.