---
title: "a4 idl — IDL Explorer"
editUrl: true
head: []
template: "doc"
sidebar: {"order":2,"hidden":false,"attrs":{}}
pagefind: true
draft: false
---

Explore and analyze Solana IDL (Interface Definition Language) files directly from the command line.

The `a4 idl` suite helps you understand a program's structure, account layouts, and relationships before you start building your stack.

---

## Global Behavior

These rules apply to all `a4 idl` subcommands:

- **Path argument**: Every subcommand takes `<path>` as its first positional argument (the path to the IDL JSON file).
- **JSON output**: Most commands support the `--json` flag for machine-readable output.
- **Fuzzy matching**: Lookups for instructions, accounts, and types are case-insensitive. If you make a typo, the CLI suggests the closest match.
- **Error handling**: File-not-found or invalid names exit with code 1 and a clear message.

---

## Quick Reference

| Command                                  | Description                              |
| ---------------------------------------- | ---------------------------------------- |
| [`summary`](#a4-idl-summary)             | Quick overview of the IDL structure      |
| [`instructions`](#a4-idl-instructions)   | List all instructions                    |
| [`instruction`](#a4-idl-instruction)     | Detail view of a specific instruction    |
| [`accounts`](#a4-idl-accounts)           | List all account types                   |
| [`account`](#a4-idl-account)             | Detail view of a specific account        |
| [`types`](#a4-idl-types)                 | List all custom types                    |
| [`type`](#a4-idl-type)                   | Detail view of a specific custom type    |
| [`errors`](#a4-idl-errors)               | List all program errors                  |
| [`events`](#a4-idl-events)               | List all program events                  |
| [`constants`](#a4-idl-constants)         | List all defined constants               |
| [`search`](#a4-idl-search)               | Fuzzy search across the entire IDL       |
| [`discriminator`](#a4-idl-discriminator) | Compute Anchor discriminators            |
| [`relations`](#a4-idl-relations)         | Categorize accounts by their role        |
| [`account-usage`](#a4-idl-account-usage) | Find all instructions using an account   |
| [`links`](#a4-idl-links)                 | Find instructions linking two accounts   |
| [`pda-graph`](#a4-idl-pda-graph)         | Visualize PDA derivation paths           |
| [`type-graph`](#a4-idl-type-graph)       | Visualize field-to-account relationships |
| [`connect`](#a4-idl-connect)             | Analyze how to connect new accounts      |

---

## Data Commands

### a4 idl summary

Show a high-level overview of the program.

```bash
# Get a quick summary
a4 idl summary meteora_dlmm.json
# Output: Name: meteora_dlmm, Format: modern, Instructions: 74, Constants: 30
```

Shows program name, IDL format (modern or legacy), program address, version, and counts for all sections.

### a4 idl instructions

List all instructions defined in the IDL.

```bash
# List all instructions
a4 idl instructions ore.json

# Count instructions via JSON
a4 idl instructions ore.json --json | jq length
# Output: 19
```

**Options:**

| Flag     | Description                       |
| -------- | --------------------------------- |
| `--json` | Output as JSON (machine-readable) |

### a4 idl instruction

Show detailed information about a specific instruction, including its discriminator, accounts, and arguments.

```bash
# Detail view for an instruction
a4 idl instruction ore.json deposit

# Fuzzy matching on typos
a4 idl instruction ore.json depositt
# Error: instruction 'depositt' not found, did you mean: deposit?
```

**Options:**

| Flag     | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

### a4 idl accounts

List all account structures defined in the IDL.

```bash
# List all accounts
a4 idl accounts meteora_dlmm.json
```

**Options:**

| Flag     | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

### a4 idl account

Show the detailed field layout of a specific account type.

```bash
# View account fields and types
a4 idl account meteora_dlmm.json lb_pair
```

**Options:**

| Flag     | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

### a4 idl types

List all custom types and enums.

```bash
# List all custom types
a4 idl types ore.json
```

**Options:**

| Flag     | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

### a4 idl type

Show the full definition of a custom type or enum.

```bash
# View type details
a4 idl type ore.json Config
```

**Options:**

| Flag     | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

### a4 idl errors

List all custom program errors with their codes and messages.

```bash
# List all errors
a4 idl errors meteora_dlmm.json
```

**Options:**

| Flag     | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

### a4 idl events

List all events emitted by the program.

```bash
# List all events
a4 idl events meteora_dlmm.json
```

**Options:**

| Flag     | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

### a4 idl constants

List all constants defined in the program.

```bash
# List all constants
a4 idl constants ore.json
```

**Options:**

| Flag     | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

### a4 idl search

Perform a fuzzy search across instructions, accounts, types, errors, events, and constants.

```bash
# Search for anything related to "swap"
a4 idl search meteora_dlmm.json swap

# Use JSON to see where matches were found
a4 idl search meteora_dlmm.json swap --json | jq '.[].section' | sort -u
# Output: "error", "event", "instruction", "type"
```

**Options:**

| Flag     | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

### a4 idl discriminator

Compute the Anchor discriminator for an instruction or account.

```bash
# Compute instruction discriminator (global namespace)
a4 idl discriminator pump.json buy
# Output: Name: buy, Namespace: global, Discriminator: [66, 06, 3d, 12, 01, da, eb, ea]

# Compute account discriminator (account namespace)
a4 idl discriminator pump.json LastIdlBlock
```

**Options:**

| Flag     | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

---

## Relationship Commands

### a4 idl relations

Analyze and categorize all accounts in the IDL.

```bash
# See how accounts are categorized
a4 idl relations meteora_dlmm.json

# Find core entity accounts
a4 idl relations meteora_dlmm.json --json | jq '.[] | select(.category == "Entity") | .account_name'
# Output includes: "lb_pair"
```

Accounts are classified into:

- **Entity**: Core data accounts that appear across many instructions.
- **Infrastructure**: System programs or token programs.
- **Role**: Authorities, signers, or administrative accounts.
- **Other**: Miscellaneous accounts.

**Options:**

| Flag     | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

### a4 idl account-usage

Find every instruction that uses a specific account.

```bash
# See where 'lb_pair' is used
a4 idl account-usage meteora_dlmm.json lb_pair

# Count usages
a4 idl account-usage meteora_dlmm.json lb_pair --json | jq length
# Output: 59
```

Instructions are grouped by the role the account plays: Writable, Signer, or Readonly.

**Options:**

| Flag     | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

### a4 idl links

Find instructions that involve a specific pair of accounts. This is useful for discovering how two entities interact.

```bash
# Find instructions linking 'round' and 'entropyVar'
a4 idl links ore.json round entropyVar

# Count shared instructions
a4 idl links ore.json round entropyVar --json | jq length
# Output: 2
```

**Options:**

| Flag     | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

### a4 idl pda-graph

Extract and visualize the PDA (Program Derived Address) derivation graph.

```bash
# Extract PDA graph
a4 idl pda-graph idl.json
```

Shows seeds (constants, accounts, or arguments) used to derive each PDA account.

**Options:**

| Flag     | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

### a4 idl type-graph

Analyze field types to find implicit references to account types.

```bash
# Extract type reference graph
a4 idl type-graph idl.json
```

Useful for identifying when a field named `lb_pair` (type `Pubkey`) refers to an account of type `LbPair`.

**Options:**

| Flag     | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

---

## Connection Command

### a4 idl connect

Analyze how a new account can be connected to existing accounts in the program.

```bash
# Analyze connection between reward_vault and lb_pair
a4 idl connect meteora_dlmm.json reward_vault --existing lb_pair

# With Arete-specific suggestions
a4 idl connect meteora_dlmm.json reward_vault --existing lb_pair --suggest-a4
# Shows: register_from suggestions

# Partial success handling
a4 idl connect ore.json entropyVar --existing round,bogus_account
# Warning: account 'bogus_account' not found in IDL, skipping
# (then shows connections to round)
```

**Options:**

| Flag                 | Description                                                       |
| -------------------- | ----------------------------------------------------------------- |
| `--existing <names>` | Comma-separated list of existing account names                    |
| `--json`             | Output as JSON                                                    |
| `--suggest-a4`       | Show Arete integration suggestions (`register_from`, `aggregate`) |

:::note[Arete Suggestions]
The `--suggest-a4` flag is specifically for Arete stack builders. It suggests the most appropriate projection patterns based on the detected relationship.
:::