anchor idl - Anchor

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.

CLI Commands

Rust API

TypeScript API

​Overview

​Subcommands

​anchor idl init

​Syntax

​Arguments

​Options

​Example

​anchor idl upgrade

​Syntax

​Arguments

​Options

​Example

​anchor idl build

​Syntax

​Alias

​Options

​Examples

​anchor idl fetch

​Syntax

​Arguments

​Options

​Examples

​anchor idl convert

​Syntax

​Arguments

​Options

​Example

​anchor idl type

​Syntax

​Arguments

​Options

​Example

​anchor idl close

​Syntax

​Arguments

​Options

​Example

​anchor idl create-buffer

​Syntax

​Options

​Example

​anchor idl set-buffer-authority

​Syntax

​Arguments

​Options

​Example

​anchor idl write-buffer

​Syntax

​Arguments

​Options

​Example

​IDL Structure

​Notes

Build docs developers (and LLMs) love

Overview

Subcommands

anchor idl init

Syntax

Arguments

Options

Example

anchor idl upgrade

Syntax

Arguments

Options

Example

anchor idl build

Syntax

Alias

Options

Examples

anchor idl fetch

Syntax

Arguments

Options

Examples

anchor idl convert

Syntax

Arguments

Options

Example

anchor idl type

Syntax

Arguments

Options

Example

anchor idl close

Syntax

Arguments

Options

Example

anchor idl create-buffer

Syntax

Options

Example

anchor idl set-buffer-authority

Syntax

Arguments

Options

Example

anchor idl write-buffer

Syntax

Arguments

Options

Example

IDL Structure

Notes