Getting Started ​

Overview ​

Wagmi CLI is a command line interface for managing ABIs (from Etherscan/block explorers, Foundry/Hardhat projects, etc.), generating code (e.g. React Hooks), and much more. It makes working with Ethereum easier by automating manual work so you can build faster. You can learn more about the rationale behind the project in the Why Wagmi CLI section.

Manual Installation ​

To manually add Wagmi CLI to your project, install the required packages.

pnpm add -D @wagmi/cli

pnpm add -D @wagmi/cli

npm install --save-dev @wagmi/cli

npm install --save-dev @wagmi/cli

yarn add -D @wagmi/cli

yarn add -D @wagmi/cli

bun add -D @wagmi/cli

bun add -D @wagmi/cli

Create Config File ​

Run the init command to generate a configuration file: either wagmi.config.ts if TypeScript is detected, otherwise wagmi.config.js. You can also create the configuration file manually. See Configuring CLI for more info.

pnpm wagmi init

pnpm wagmi init

npx wagmi init

npx wagmi init

yarn wagmi init

yarn wagmi init

bun wagmi init

bun wagmi init

The generated configuration file will look something like this:

import { defineConfig } from '@wagmi/cli'

export default defineConfig({
  out: 'src/generated.ts',
  contracts: [],
  plugins: [],
})

import { defineConfig } from '@wagmi/cli'

export default defineConfig({
  out: 'src/generated.ts',
  contracts: [],
  plugins: [],
})

Add Contracts And Plugins ​

Once the configuration file is set up, you can add contracts and plugins to it. These contracts and plugins are used to manage ABIs (fetch from block explorers, resolve from the file system, etc.), generate code (React hooks, etc.), and much more!

For example, we can add the ERC-20 contract from Viem, and the etherscan and react plugins.

import { defineConfig } from '@wagmi/cli'
import { etherscan, react } from '@wagmi/cli/plugins'
import { erc20Abi } from 'viem'
import { mainnet, sepolia } from 'wagmi/chains'
 
export default defineConfig({
  out: 'src/generated.ts',
  contracts: [
    {
      name: 'erc20',
      abi: erc20Abi,
    },
  ],
  plugins: [
    etherscan({
      apiKey: process.env.ETHERSCAN_API_KEY!,
      chainId: mainnet.id,
      contracts: [
        {
          name: 'EnsRegistry',
          address: {
            [mainnet.id]: '0x314159265dd8dbb310642f98f50c066173c1259b',
            [sepolia.id]: '0x112234455c3a32fd11230c42e7bccd4a84e02010',
          },
        },
      ],
    }),
    react(),
  ],
})

import { defineConfig } from '@wagmi/cli'
import { etherscan, react } from '@wagmi/cli/plugins'
import { erc20Abi } from 'viem'
import { mainnet, sepolia } from 'wagmi/chains'
 
export default defineConfig({
  out: 'src/generated.ts',
  contracts: [
    {
      name: 'erc20',
      abi: erc20Abi,
    },
  ],
  plugins: [
    etherscan({
      apiKey: process.env.ETHERSCAN_API_KEY!,
      chainId: mainnet.id,
      contracts: [
        {
          name: 'EnsRegistry',
          address: {
            [mainnet.id]: '0x314159265dd8dbb310642f98f50c066173c1259b',
            [sepolia.id]: '0x112234455c3a32fd11230c42e7bccd4a84e02010',
          },
        },
      ],
    }),
    react(),
  ],
})

Run Code Generation ​

Now that we added a few contracts and plugins to the configuration file, we can run the generate command to resolve ABIs and generate code to the out file.

pnpm wagmi generate

pnpm wagmi generate

npx wagmi generate

npx wagmi generate

yarn wagmi generate

yarn wagmi generate

bun wagmi generate

bun wagmi generate

In this example, the generate command will do the following:

• Validate the etherscan and react plugins
• Fetch and cache the ENS Registry ABI from the Mainnet Etherscan API
• Pull in the erc20Abi using the name 'ERC20'
• Generate React Hooks for both ABIs
• Save ABIs, ENS Registry deployment addresses, and React Hooks to the out file

Use Generated Code ​

Once out is created, you can start using the generated code in your project.

import { useReadErc20, useReadErc20BalanceOf } from './generated'

// Use the generated ERC-20 read hook
const { data } = useReadErc20({
  address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  functionName: 'balanceOf',
  args: ['0xA0Cf798816D4b9b9866b5330EEa46a18382f251e'],
})

// Use the generated ERC-20 "balanceOf" hook
const { data } = useReadErc20BalanceOf({
  address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  args: ['0xA0Cf798816D4b9b9866b5330EEa46a18382f251e'],
})

import { useReadErc20, useReadErc20BalanceOf } from './generated'

// Use the generated ERC-20 read hook
const { data } = useReadErc20({
  address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  functionName: 'balanceOf',
  args: ['0xA0Cf798816D4b9b9866b5330EEa46a18382f251e'],
})

// Use the generated ERC-20 "balanceOf" hook
const { data } = useReadErc20BalanceOf({
  address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  args: ['0xA0Cf798816D4b9b9866b5330EEa46a18382f251e'],
})

Next Steps ​

For more information on what to do next, check out the following topics.

• Configuring CLI Learn how to configure the CLI to work best for your project.
• Commands Learn more about the CLI commands and how to use them.
• Plugins Browse the collection of plugins and set them up with your config.