---
title: Reflect
description: Decode or validate binary payloads against ABI types with thru abi reflect
source_url:
  html: https://thru.org/docs/cli-reference/abi-reflect/
  md: https://thru.org/docs/cli-reference/abi-reflect.md
---

# Reflect

Use `thru abi reflect` when you have binary data plus ABI type definitions and need a JSON view of the decoded structure.

## Use This When

- you captured instruction, account, or event bytes and want to decode them
- you only need to validate that a buffer matches an ABI type
- you want byte offsets or extracted values for debugging tools

Choose another ABI command when:

- you want to inspect the ABI type graph itself: [Analyze](https://thru.org/docs/cli-reference/abi-analyze.md)
- you want generated client code: [Codegen](https://thru.org/docs/cli-reference/abi-codegen.md)
- you want a dependency manifest for runtime tooling: [Bundle](https://thru.org/docs/cli-reference/abi-bundle.md)

## Syntax

```bash
thru abi reflect \
  --abi-file <FILE>... \
  --type-name <TYPE> \
  --data-file <FILE> \
  [--include-dir <DIR>...] \
  [--pretty] \
  [--values-only | --validate-only | --include-byte-offsets] \
  [--show-params]
```

## Output Modes

Decode JSON

Default mode prints the full reflected structure with type information.

Values Only

Use `--values-only` when you only care about decoded values.

Validate Only

Use `--validate-only` to confirm the buffer matches the ABI without decoding it.

Byte Offsets

Use `--include-byte-offsets` when you need layout-aware debugging output.

| Flag | Output |
| - | - |
| none | Full reflected JSON with type information. |
| `--values-only` | JSON values only, without type metadata. |
| `--validate-only` | Validation success plus bytes consumed. No decoded JSON. |
| `--include-byte-offsets` | Reflected JSON annotated with byte offsets. |

`--values-only`, `--validate-only`, and `--include-byte-offsets` are mutually exclusive.

## Important Flags

| Flag | Use it for |
| - | - |
| `—abi-file <FILE>…` | Load one or more ABI YAML files. |
| `—include-dir <DIR>…` | Resolve imported ABI files. |
| `—type-name <TYPE>` | Choose the concrete type to decode. |
| `—data-file <FILE>` | Binary payload to parse. |
| `--show-params` | Print dynamic parameters inferred from the buffer before the main result. |
| `--pretty` | Pretty-print JSON output for human inspection. |

## Minimal Patterns

**Decode a payload:**

```bash
thru abi reflect \
  --abi-file ./program.abi.yaml \
  --type-name TransferArgs \
  --data-file ./payload.bin \
  --pretty
```

**Validate only:**

```bash
thru abi reflect \
  --abi-file ./program.abi.yaml \
  --type-name TransferArgs \
  --data-file ./payload.bin \
  --validate-only
```

**Include byte offsets:**

```bash
thru abi reflect \
  --abi-file ./program.abi.yaml \
  --type-name TransferArgs \
  --data-file ./payload.bin \
  --include-byte-offsets \
  --pretty
```

## Common Failures

- The command resolves types before it reflects data, so missing imports and invalid type names fail early.
- `--show-params` can be combined with any output mode, but it prints an extra prelude before the main result.
- `--validate-only` is the best choice when an agent only needs to answer “does this buffer match the ABI?” without spending context on the full decoded JSON.