> ## 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.

# Using tensor9 explain

> Inspect a directed service profile, then collect request evidence from a deployed adapter.

> [!NOTE]
>
> Before running a `tensor9` command, [install the CLI, set `T9_API_KEY`, and verify your customer account](https://docs.tensor9.com/cloud-adapter-early-access/getting-started/install-and-authenticate). Online commands are authenticated and their adapter detail is limited to mappings your account is entitled to use.

`tensor9 explain` is the short form of `tensor9 adapt svc explain`. It authenticates to Tensor9 and returns a bounded view of the contract for one entitled origin-to-target mapping. Profile inspection is non-executing: it does not start an adapter, contact an origin or target cloud API or describe what happened to a particular request.

For request-specific evidence, send an Explain control through a deployed adapter and read the returned report. Keep profile inspection and request evidence separate: the profile says what a mapping declares, while a report says what one instrumented request recorded.

## Command help and report retrieval

Read the customer command's profile-inspection flags:

```sh theme={null}
tensor9 explain -help
```

Use [signed SDK report retrieval](https://docs.tensor9.com/cloud-adapter-early-access/debugging/explain-sdk.md#retrieve-without-replaying) for the receipt ID, published `t9` endpoint, IAM owner credentials, formats and revision requirements. `tensor9 explain` inspects a directed service profile; it does not retrieve a deployed request report. Profile inspection continues to use the Tensor9 account credentials described below.

## Discover an entitled direction

Start with the origin identifier, backend choices and compatibility detail in the public service catalog. Ask Tensor9 which exact target identifiers your account is entitled to run with that origin:

```sh theme={null}
tensor9 adapt svc list \
  -origin aws::1.0.0::s3 \
  -fmt Human
```

This authenticated command returns only the directed mappings for the supplied origin that are available to your account. It does not enumerate other origins or export the adapter corpus. Use one returned target identifier in the profile command below. If the expected direction is absent, confirm the origin identifier and request the entitlement from Tensor9.

## Inspect a service profile

Specify the exact directed service identifiers:

```sh theme={null}
tensor9 explain \
  -origin aws::1.0.0::s3 \
  -target google::1.0.0::gcs \
  -operation PutObject \
  -fmt Human
```

This command contacts Tensor9 to authorize and render an entitled profile. The written compatibility detail is also public. The command does not launch an adapter or contact AWS or Google Cloud; it selects the S3-to-GCS profile and filters it to `PutObject`.

Render the same profile for an evidence-oriented agent:

```sh theme={null}
tensor9 explain \
  -origin aws::1.0.0::s3 \
  -target google::1.0.0::gcs \
  -operation PutObject \
  -fmt Agent
```

Or inspect the structured DynamoDB-to-Cosmos profile:

```sh theme={null}
tensor9 explain \
  -origin aws::1.0.0::dynamodb::table \
  -target azure::1.0.0::cosmosdb::provisioned \
  -fmt Json
```

Profile output answers what the selected profile declares. It does not identify the configuration or version of a running adapter. The profile facet `::table` is a profile selector, not necessarily the runtime request origin name.

### Profile flags

| Flag | Use |
| - | - |
| `-origin` | Exact origin service profile identifier |
| `-target` | Exact target service profile identifier |
| `-operation` | Optional comma-separated origin operation names |
| `-fmt` | `Human` (default), `Agent`, or `Json` |

## Explain a request through a deployed adapter

Use the application client that reproduces the behavior. Configure that client to use the Cloud Adapter endpoint, add the control before request signing, and send one bounded request with a unique test identity.

Choose the mode explicitly:

```json theme={null}
{"version":1,"mode":"Explain","fmt":"Json"}
```

`Explain` records the supported decision path without performing the target service operation. When the test is intended to execute the operation, use:

```json theme={null}
{"version":1,"mode":"ExecuteAndExplain","fmt":"Json"}
```

> [!WARNING]
>
> `ExecuteAndExplain` performs the service operation. The shorthand `x-t9-explain: true` also selects `ExecuteAndExplain`; it is not a preview control.

Capture the native response and diagnostic headers before retrying. In particular, retain the report ID, effective mode, report revision, request identifiers and any retry metadata supplied by the origin SDK. Read the report by its ID; do not replay a mutating request merely to obtain another explanation.

Use [Explaining SDK Requests](https://docs.tensor9.com/cloud-adapter-early-access/debugging/explain-sdk.md) for endpoint configuration and request interception, and [Diagnostic Response Headers](https://docs.tensor9.com/cloud-adapter-early-access/debugging/response-headers.md) for the complete control, receipt, read and acknowledgment contract.

### Keep the deployment context with the report

A request report is meaningful only with the environment that produced it. Record:

* the origin service and operation;
* the selected target profile;
* the Cloud Adapter and application versions;
* the configuration revision and tuning inputs;
* the exact synthetic resource identity;
* the request time window and origin request identifiers; and
* an independent target-state observation when the operation could write.

Do not include credentials, signed URLs, customer payloads or unrestricted logs in an evidence bundle. A sanitized report can still contain customer resource names and should be handled as customer data.

## Choose the output format

The profile command and request reports support three audience-oriented renderings:

* `Human` is a readable decision path with stable IDs.
* `Agent` is compact labeled text for a bounded investigation.
* `Json` is a versioned structured document for tools.

Changing a rendering format does not change request mode or execute the operation again. On profile inspection, `-fmt` selects the authorized profile rendering. On a request, the Explain control selects the report rendering.

See [Reading an Explanation](https://docs.tensor9.com/cloud-adapter-early-access/debugging/reading-explanations.md) before automating conclusions from JSON. Unknown fact versions and declared limitations must remain visible.

## Interpret profile, request and cleanup separately

There are four independent outcomes:

1. **The profile result:** What behavior does the selected directed profile declare?
2. **The origin operation outcome:** Was this request previewed, refused, attempted, accepted or completed?
3. **The target observation:** What did the target service expose for the exact resource identity?
4. **The cleanup outcome:** Were resources created for the test removed and was that removal observed?

A successful profile lookup does not establish runtime behavior. A failed report read can accompany a successful target mutation, and a successful client response does not establish that later asynchronous work finished. Record each outcome explicitly.

## Use an existing SDK when that is the real case

To diagnose the request your SDK constructs, use a signed per-request control at the application's configured Cloud Adapter endpoint. [Explaining SDK Requests](https://docs.tensor9.com/cloud-adapter-early-access/debugging/explain-sdk.md) shows the Java SDK 2.x pattern and report receipt handling.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.