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

anchor idl init [PROGRAM_ID] --filepath <PATH> [OPTIONS]

Arguments

program_id · pubkey

Program ID to initialize IDL for (auto-discovered from IDL if not provided)

Options

--filepath · string · required

Path to the IDL JSON file

--priority-fee · number

Priority fee in micro-lamports per compute unit

--non-canonical · flag · default: "false"

Create non-canonical metadata account (third-party metadata)

Example

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

anchor idl upgrade [PROGRAM_ID] --filepath <PATH> [OPTIONS]

Arguments

program_id · pubkey

Program ID to upgrade IDL for (auto-discovered from IDL if not provided)

Options

--filepath · string · required

Path to the new IDL JSON file

--priority-fee · number

Priority fee in micro-lamports per compute unit

Example

anchor idl upgrade --filepath target/idl/my_program.json

---

anchor idl build

Generate the IDL for a program using the compilation method.

Syntax

anchor idl build [OPTIONS] [-- <CARGO_ARGS>...]

Alias

anchor idl b

Options

--program-name · string

Program name to build the IDL for (current directory’s program if not specified)

--out · string

Output file for the IDL (stdout if not specified)

--out-ts · string

Output file for the TypeScript IDL

--no-docs · flag · default: "false"

Suppress doc strings in output

--skip-lint · flag · default: "false"

Do not check for safety comments

cargo_args · string

Arguments to pass to the underlying cargo test command

Examples

# 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

anchor idl fetch <PROGRAM_ID> [OPTIONS]

Arguments

program_id · pubkey · required

Program ID to fetch IDL for

Options

--out · string

Output file for the IDL (stdout if not specified)

--non-canonical · flag · default: "false"

Fetch non-canonical metadata account (third-party metadata)

Examples

# Fetch and display to stdout
anchor idl fetch Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS

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

Output:

{
  "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

anchor idl convert <PATH> [OPTIONS]

Arguments

path · string · required

Path to the legacy IDL file

Options

--out · string

Output file for the converted IDL (stdout if not specified)

--program-id · pubkey

Program ID to set in the IDL (auto-discovered from IDL if not provided)

Example

anchor idl convert legacy_idl.json --out new_idl.json

---

anchor idl type

Generate TypeScript type definitions from an IDL.

Syntax

anchor idl type <PATH> [OPTIONS]

Arguments

path · string · required

Path to the IDL file

Options

--out · string

Output file for the TypeScript types (stdout if not specified)

Example

anchor idl type target/idl/my_program.json --out types/my_program.ts

---

anchor idl close

Close a metadata account and recover rent.

Syntax

anchor idl close <PROGRAM_ID> [OPTIONS]

Arguments

program_id · pubkey · required

The program ID

Options

--seed · string · default: "idl"

The seed used for the metadata account

--priority-fee · number

Priority fees in micro-lamports per compute unit

Example

anchor idl close Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS

---

anchor idl create-buffer

Create a buffer account for metadata.

Syntax

anchor idl create-buffer --filepath <PATH> [OPTIONS]

Options

--filepath · string · required

Path to the metadata file

--priority-fee · number

Priority fees in micro-lamports per compute unit

Example

anchor idl create-buffer --filepath target/idl/my_program.json

---

anchor idl set-buffer-authority

Set a new authority on a buffer account.

Syntax

anchor idl set-buffer-authority <BUFFER> --new-authority <PUBKEY> [OPTIONS]

Arguments

buffer · pubkey · required

The buffer account address

Options

--new-authority · pubkey · required

The new authority

--priority-fee · number

Priority fees in micro-lamports per compute unit

Example

anchor idl set-buffer-authority BUF111111111111111111111111111111111111111 --new-authority 3Z9vL1zjN6qyAFHhHQdWYRTFAcy69pJydkZmSFBKHg1R

---

anchor idl write-buffer

Write metadata using a buffer account.

Syntax

anchor idl write-buffer <PROGRAM_ID> --buffer <PUBKEY> [OPTIONS]

Arguments

program_id · pubkey · required

The program ID

Options

--buffer · pubkey · required

The buffer account address

--seed · string · default: "idl"

The seed to use for the metadata account

--close-buffer · flag · default: "false"

Close the buffer after writing

--priority-fee · number

Priority fees in micro-lamports per compute unit

Example

anchor idl write-buffer Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS --buffer BUF111111111111111111111111111111111111111 --close-buffer

---

IDL Structure

A modern Anchor IDL includes:

{
  "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

IDLs are automatically uploaded during anchor deploy unless --no-idl is specified.

Use anchor idl fetch to retrieve IDLs from deployed programs for client development.

The --non-canonical flag is for third-party metadata accounts. Most users should use the canonical IDL account.