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

# anchor idl

> Interface Definition Language (IDL) management commands

## Overview

The `anchor idl` command provides subcommands for managing Interface Definition Language (IDL) files, including building, uploading, fetching, and converting IDLs.

## Subcommands

* `init` - Initialize a program's IDL account on-chain
* `upgrade` - Upgrade the IDL to a new file
* `build` - Generate the IDL for a program
* `fetch` - Fetch an IDL from a cluster
* `convert` - Convert legacy IDLs to the new IDL spec
* `type` - Generate TypeScript types from an IDL
* `close` - Close a metadata account and recover rent
* `create-buffer` - Create a buffer account for metadata
* `set-buffer-authority` - Set a new authority on a buffer account
* `write-buffer` - Write metadata using a buffer account

***

## anchor idl init

Initialize a program's IDL account on-chain. Can only be run once per program.

### Syntax

```bash theme={null}
anchor idl init [PROGRAM_ID] --filepath <PATH> [OPTIONS]
```

### Arguments

<ParamField path="program_id" type="pubkey">
  Program ID to initialize IDL for (auto-discovered from IDL if not provided)
</ParamField>

### Options

<ParamField path="--filepath" type="string" required>
  Path to the IDL JSON file
</ParamField>

<ParamField path="--priority-fee" type="number">
  Priority fee in micro-lamports per compute unit
</ParamField>

<ParamField path="--non-canonical" type="flag" default="false">
  Create non-canonical metadata account (third-party metadata)
</ParamField>

### Example

```bash theme={null}
anchor idl init --filepath target/idl/my_program.json
```

***

## anchor idl upgrade

Upgrade the IDL to a new file. This is an alias for writing and then setting the IDL buffer account.

### Syntax

```bash theme={null}
anchor idl upgrade [PROGRAM_ID] --filepath <PATH> [OPTIONS]
```

### Arguments

<ParamField path="program_id" type="pubkey">
  Program ID to upgrade IDL for (auto-discovered from IDL if not provided)
</ParamField>

### Options

<ParamField path="--filepath" type="string" required>
  Path to the new IDL JSON file
</ParamField>

<ParamField path="--priority-fee" type="number">
  Priority fee in micro-lamports per compute unit
</ParamField>

### Example

```bash theme={null}
anchor idl upgrade --filepath target/idl/my_program.json
```

***

## anchor idl build

Generate the IDL for a program using the compilation method.

### Syntax

```bash theme={null}
anchor idl build [OPTIONS] [-- <CARGO_ARGS>...]
```

### Alias

```bash theme={null}
anchor idl b
```

### Options

<ParamField path="--program-name" type="string">
  Program name to build the IDL for (current directory's program if not specified)
</ParamField>

<ParamField path="--out" type="string">
  Output file for the IDL (stdout if not specified)
</ParamField>

<ParamField path="--out-ts" type="string">
  Output file for the TypeScript IDL
</ParamField>

<ParamField path="--no-docs" type="flag" default="false">
  Suppress doc strings in output
</ParamField>

<ParamField path="--skip-lint" type="flag" default="false">
  Do not check for safety comments
</ParamField>

<ParamField path="cargo_args" type="string">
  Arguments to pass to the underlying `cargo test` command
</ParamField>

### Examples

```bash theme={null}
# Build IDL for current program
anchor idl build

# Build with output file
anchor idl build --out my_program.json

# Build TypeScript types
anchor idl build --out-ts my_program.ts

# Build specific program
anchor idl build --program-name my_program
```

***

## anchor idl fetch

Fetch an IDL for a program from a cluster.

### Syntax

```bash theme={null}
anchor idl fetch <PROGRAM_ID> [OPTIONS]
```

### Arguments

<ParamField path="program_id" type="pubkey" required>
  Program ID to fetch IDL for
</ParamField>

### Options

<ParamField path="--out" type="string">
  Output file for the IDL (stdout if not specified)
</ParamField>

<ParamField path="--non-canonical" type="flag" default="false">
  Fetch non-canonical metadata account (third-party metadata)
</ParamField>

### Examples

```bash theme={null}
# Fetch and display to stdout
anchor idl fetch Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS

# Fetch and save to file
anchor idl fetch Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS --out program.json
```

**Output:**

```json theme={null}
{
  "address": "Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS",
  "metadata": {
    "name": "my_program",
    "version": "0.1.0",
    "spec": "0.1.0"
  },
  "instructions": [...],
  "accounts": [...],
  "types": [...]
}
```

***

## anchor idl convert

Convert legacy IDLs (pre Anchor 0.30) to the new IDL spec.

### Syntax

```bash theme={null}
anchor idl convert <PATH> [OPTIONS]
```

### Arguments

<ParamField path="path" type="string" required>
  Path to the legacy IDL file
</ParamField>

### Options

<ParamField path="--out" type="string">
  Output file for the converted IDL (stdout if not specified)
</ParamField>

<ParamField path="--program-id" type="pubkey">
  Program ID to set in the IDL (auto-discovered from IDL if not provided)
</ParamField>

### Example

```bash theme={null}
anchor idl convert legacy_idl.json --out new_idl.json
```

***

## anchor idl type

Generate TypeScript type definitions from an IDL.

### Syntax

```bash theme={null}
anchor idl type <PATH> [OPTIONS]
```

### Arguments

<ParamField path="path" type="string" required>
  Path to the IDL file
</ParamField>

### Options

<ParamField path="--out" type="string">
  Output file for the TypeScript types (stdout if not specified)
</ParamField>

### Example

```bash theme={null}
anchor idl type target/idl/my_program.json --out types/my_program.ts
```

***

## anchor idl close

Close a metadata account and recover rent.

### Syntax

```bash theme={null}
anchor idl close <PROGRAM_ID> [OPTIONS]
```

### Arguments

<ParamField path="program_id" type="pubkey" required>
  The program ID
</ParamField>

### Options

<ParamField path="--seed" type="string" default="idl">
  The seed used for the metadata account
</ParamField>

<ParamField path="--priority-fee" type="number">
  Priority fees in micro-lamports per compute unit
</ParamField>

### Example

```bash theme={null}
anchor idl close Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS
```

***

## anchor idl create-buffer

Create a buffer account for metadata.

### Syntax

```bash theme={null}
anchor idl create-buffer --filepath <PATH> [OPTIONS]
```

### Options

<ParamField path="--filepath" type="string" required>
  Path to the metadata file
</ParamField>

<ParamField path="--priority-fee" type="number">
  Priority fees in micro-lamports per compute unit
</ParamField>

### Example

```bash theme={null}
anchor idl create-buffer --filepath target/idl/my_program.json
```

***

## anchor idl set-buffer-authority

Set a new authority on a buffer account.

### Syntax

```bash theme={null}
anchor idl set-buffer-authority <BUFFER> --new-authority <PUBKEY> [OPTIONS]
```

### Arguments

<ParamField path="buffer" type="pubkey" required>
  The buffer account address
</ParamField>

### Options

<ParamField path="--new-authority" type="pubkey" required>
  The new authority
</ParamField>

<ParamField path="--priority-fee" type="number">
  Priority fees in micro-lamports per compute unit
</ParamField>

### Example

```bash theme={null}
anchor idl set-buffer-authority BUF111111111111111111111111111111111111111 --new-authority 3Z9vL1zjN6qyAFHhHQdWYRTFAcy69pJydkZmSFBKHg1R
```

***

## anchor idl write-buffer

Write metadata using a buffer account.

### Syntax

```bash theme={null}
anchor idl write-buffer <PROGRAM_ID> --buffer <PUBKEY> [OPTIONS]
```

### Arguments

<ParamField path="program_id" type="pubkey" required>
  The program ID
</ParamField>

### Options

<ParamField path="--buffer" type="pubkey" required>
  The buffer account address
</ParamField>

<ParamField path="--seed" type="string" default="idl">
  The seed to use for the metadata account
</ParamField>

<ParamField path="--close-buffer" type="flag" default="false">
  Close the buffer after writing
</ParamField>

<ParamField path="--priority-fee" type="number">
  Priority fees in micro-lamports per compute unit
</ParamField>

### Example

```bash theme={null}
anchor idl write-buffer Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS --buffer BUF111111111111111111111111111111111111111 --close-buffer
```

***

## IDL Structure

A modern Anchor IDL includes:

```json theme={null}
{
  "address": "ProgramPublicKey",
  "metadata": {
    "name": "program_name",
    "version": "0.1.0",
    "spec": "0.1.0"
  },
  "instructions": [
    {
      "name": "initialize",
      "discriminator": [175, 175, 109, 31, 13, 152, 155, 237],
      "accounts": [...],
      "args": [...]
    }
  ],
  "accounts": [...],
  "types": [...],
  "errors": [...]
}
```

## Notes

<Info>
  IDLs are automatically uploaded during `anchor deploy` unless `--no-idl` is specified.
</Info>

<Tip>
  Use `anchor idl fetch` to retrieve IDLs from deployed programs for client development.
</Tip>

<Note>
  The `--non-canonical` flag is for third-party metadata accounts. Most users should use the canonical IDL account.
</Note>