> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensor9.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS CLI Guide

> Prove an AWS API workflow through Cloud Adapter from the command line.

The AWS CLI is the fastest way to prove the full request path: AWS command, Cloud Adapter endpoint, service adapter, and native target service. It is also a useful diagnostic control because it removes your application code from the test.

This walkthrough uses S3. The same pattern works for another AWS service when that service page documents the operation and target environment you need.

## Before you begin

You need:

* an installed AWS-origin Cloud Adapter endpoint;
* an origin-side test identity accepted by that endpoint;
* a configured S3 service adapter and a target bucket;
* AWS CLI v2;
* a unique prefix that is safe to create and delete.

Read [S3 service coverage](/cloud-adapter/service-catalog/aws/databases-storage/s3) before testing. Coverage is directional and operation-specific.

## Choose the endpoint scope

### Set S3 for the process

AWS CLI v2 supports the AWS-standard, service-specific endpoint variable:

```bash theme={null}
export AWS_ENDPOINT_URL_S3="https://adapter.example.test"
aws s3api head-bucket --bucket adapter-smoke-test
```

This applies to every S3 command in the process without redirecting STS, DynamoDB, or another AWS service. The official pattern is `AWS_ENDPOINT_URL_<SERVICE>`; for S3 it is `AWS_ENDPOINT_URL_S3`.

### Set one command at a time

Use `--endpoint-url` when the endpoint should be visible on each command or when one process talks to both AWS and Cloud Adapter. Keep the URL in a Tensor9-specific variable:

```bash theme={null}
export T9_CLOUD_ADAPTER_ENDPOINT="https://adapter.example.test"
export AWS_PROFILE="adapter-test"
export AWS_REGION="us-east-1"
export AWS_REQUEST_CHECKSUM_CALCULATION="WHEN_REQUIRED"
export TEST_BUCKET="adapter-smoke-test"
export TEST_KEY="quickstart/$(date +%s)-hello.txt"
```

Confirm the active profile without printing secrets:

```bash theme={null}
aws configure list --profile "$AWS_PROFILE"
```

`AWS_REQUEST_CHECKSUM_CALCULATION=WHEN_REQUIRED` keeps the first smoke test on the required S3 checksum path. If your application uses optional flexible checksums, validate those algorithms separately against the selected target profile.

An explicit `--endpoint-url` takes precedence over `AWS_ENDPOINT_URL_S3`. The remaining commands use the explicit form so each network destination is visible at the call site.

## Run a read-only request first

Start with the smallest covered read. Passing `--endpoint-url` on every command makes accidental calls to AWS much less likely.

```bash theme={null}
aws s3api head-bucket \
  --bucket "$TEST_BUCKET" \
  --endpoint-url "$T9_CLOUD_ADAPTER_ENDPOINT" \
  --profile "$AWS_PROFILE" \
  --region "$AWS_REGION"
```

If the target uses a bucket name that differs from the origin name, use the origin-facing name from the service adapter configuration. Cloud Adapter owns the name translation.

## Exercise a complete object lifecycle

Create a small local payload, upload it, read it back, compare it, and delete only the object created by this test.

```bash theme={null}
printf 'hello through Cloud Adapter\n' > /tmp/cloud-adapter-smoke.txt

aws s3api put-object \
  --bucket "$TEST_BUCKET" \
  --key "$TEST_KEY" \
  --body /tmp/cloud-adapter-smoke.txt \
  --content-type text/plain \
  --endpoint-url "$T9_CLOUD_ADAPTER_ENDPOINT" \
  --profile "$AWS_PROFILE" \
  --region "$AWS_REGION"

aws s3api head-object \
  --bucket "$TEST_BUCKET" \
  --key "$TEST_KEY" \
  --endpoint-url "$T9_CLOUD_ADAPTER_ENDPOINT" \
  --profile "$AWS_PROFILE" \
  --region "$AWS_REGION"

aws s3api get-object \
  --bucket "$TEST_BUCKET" \
  --key "$TEST_KEY" \
  --endpoint-url "$T9_CLOUD_ADAPTER_ENDPOINT" \
  --profile "$AWS_PROFILE" \
  --region "$AWS_REGION" \
  /tmp/cloud-adapter-smoke.downloaded.txt

cmp /tmp/cloud-adapter-smoke.txt /tmp/cloud-adapter-smoke.downloaded.txt
```

Verify the corresponding object with the target cloud's console or CLI. The AWS-shaped success response and target resource should agree.

## Test the translated error path

Request a key that does not exist:

```bash theme={null}
aws s3api get-object \
  --bucket "$TEST_BUCKET" \
  --key "quickstart/definitely-not-present" \
  --endpoint-url "$T9_CLOUD_ADAPTER_ENDPOINT" \
  --profile "$AWS_PROFILE" \
  --region "$AWS_REGION" \
  /tmp/cloud-adapter-missing.txt
```

Record the command timestamp, AWS error code, and message. A translated not-found response proves more than an empty list because it exercises the service adapter's error mapping. S3 can return permission denied instead when the caller lacks permission to establish that the object is missing. The normal CLI output does not expose arbitrary response headers; use the [Python SDK guide](/cloud-adapter/guides/aws-python-sdk) when you need structured, redacted header capture.

## Clean up

Delete only the unique object you created:

```bash theme={null}
aws s3api delete-object \
  --bucket "$TEST_BUCKET" \
  --key "$TEST_KEY" \
  --endpoint-url "$T9_CLOUD_ADAPTER_ENDPOINT" \
  --profile "$AWS_PROFILE" \
  --region "$AWS_REGION"
```

Confirm that `get-object` can no longer read the current object. Versioning or soft delete can retain prior versions, delete markers, or recovery state; use a disposable unversioned target for this walkthrough or remove the created version explicitly. Remove the local temporary files separately.

## Common problems

| Symptom                                  | Check                                                                                                                 |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| DNS or connection failure                | The application-to-adapter network path, TLS name, and listener address.                                              |
| Signature or credential error            | Origin-side identity, signing region, local clock, and whether the endpoint accepts the selected authentication mode. |
| Target permission denied                 | The adapter's backend identity, not the AWS CLI profile.                                                              |
| Redirect or virtual-host error           | Use the service adapter's documented S3 addressing mode. Path-style requests are easiest for a custom endpoint.       |
| Timeout after a write                    | Inspect target state before retrying. A missing success response does not prove the backend write failed.             |
| Command exists but operation is rejected | Check the operation table and target-specific limitations on the S3 service page.                                     |

Use `--debug` only in an isolated environment. Its output can include headers, canonical requests, endpoints, and payload details that should not enter shared logs.

## Expand the test deliberately

After the basic lifecycle passes, add only the features your application uses, such as conditional reads, metadata, pagination, multipart upload, or versioning. Test each against the target-specific behavior in the service catalog before moving application traffic.

See [Debugging Your Adapters](/cloud-adapter/debugging/overview), [Testing Your Adapters](/cloud-adapter/local-testing/testing-your-adapters), and [Operations](/cloud-adapter/operations/overview).