Introduction

There is no exact head command in the AWS CLI that shows the first lines of an S3 object's content the way Unix head works on a local file. That causes confusion because S3 does have head-object, but that command returns metadata, not file contents. If you want to preview the beginning of an object, the practical solution is to stream the object to standard output and pipe it into head, or fetch only the first byte range for large files.

head-object Is Metadata Only

This command is valid:

aws s3api head-object --bucket my-bucket --key logs/app.log

But it gives you information such as size, ETag, content type, and last modified time. It does not print the beginning of the file itself.

That is useful for inspection, but it is not the equivalent of head on a text file.

Stream The Object And Pipe To head

For ordinary text files, the easiest way to preview content is to copy the object to standard output and let the shell handle the first lines.

aws s3 cp s3://my-bucket/logs/app.log - | head

The - tells the AWS CLI to write the object to stdout instead of saving it to a local file. Then head prints the first ten lines, just like it would for any other stream.

If you want a specific number of lines:

aws s3 cp s3://my-bucket/logs/app.log - | head -n 20

This is the closest practical match to a native S3 head-for-content workflow.

Use Byte Ranges For Large Objects

If the object is large, it can be wasteful to stream the entire file just to look at the first few lines. In that case, use s3api get-object with a byte range.

1aws s3api get-object \
2  --bucket my-bucket \
3  --key logs/app.log \
4  --range bytes=0-2047 \
5  /dev/stdout | head

This fetches only the first 2048 bytes. It is more efficient, especially for big logs or CSV files.

You may need to increase the byte range if your first few lines are long. The range is byte-based, not line-based.

Compressed Files Need One More Step

If the object is compressed, previewing raw bytes will not help. Stream the object and decompress it before piping to head.

aws s3 cp s3://my-bucket/logs/app.log.gz - | gunzip -c | head

That pattern is common for archived logs, because many S3 buckets store text in gzip format to save space.

When Metadata Is All You Need

Sometimes you do not actually need the first lines. You only need to confirm that the object exists, how large it is, or whether it changed.

In that case, head-object is still the right command:

aws s3api head-object --bucket my-bucket --key logs/app.log \
  --query '{size: ContentLength, type: ContentType, modified: LastModified}'

That gives a clean metadata summary without downloading the content stream.

Common Pitfalls

The biggest mistake is assuming aws s3api head-object will show file contents. It never does. It is a metadata lookup only.

Another issue is forgetting that aws s3 cp ... - | head may still start streaming the whole file unless you interrupt the pipeline or use a range request. For very large objects, a byte range is usually the better choice.

Compressed and binary files are another source of confusion. head works nicely for plain text, but it is not meaningful for raw binary data and needs decompression for gzip content.

Finally, make sure the identity running the command has s3:GetObject permission. A missing permission problem can look like a command mistake when it is really an IAM problem.

Summary

• There is no native AWS CLI command that shows S3 content exactly like Unix head.
• 'head-object returns metadata only, not file contents.'
• For text previews, stream with aws s3 cp s3://... - | head.
• For large objects, use s3api get-object --range to fetch only the opening bytes.
• Decompress compressed objects before piping them to head if you want readable output.