Skip to content
Hardhat 3

Using the Hardhat console

The built-in console task starts a REPL that can be used to experiment with your contracts and the Hardhat Runtime Environment (HRE).

Starting the console

Section titled “Starting the console”

To start a Hardhat console, run the following command:

Terminal window
npx hardhat console

The console task starts a Node.js REPL similar to the one you get when you run node in your terminal, but with some added features:

  • The HRE and some of its properties are globally available
  • Your project is built before the REPL starts
  • It maintains a separate command history for each project

Here’s an example where you deploy a contract and interact with it:

> const { viem } = await network.connect()
> const counter = await viem.deployContract("Counter")
> await counter.write.inc()
> await counter.read.x()
1n

To skip compilation before starting the console, pass the --no-compile flag:

Terminal window
npx hardhat console --no-compile

Running commands on startup

Section titled “Running commands on startup”

The console task accepts an optional list of positional arguments. Each argument you provide will be executed as a command immediately after the REPL starts, letting you run a series of commands automatically:

Terminal window
npx hardhat console "const { viem } = await network.connect();" />

Make sure to wrap each command in quotes to avoid issues with your shell interpreting special characters.

You can also define a custom task that runs console with some predefined commands. For example:

hardhat.config.ts
import hardhatToolboxViemPlugin from "@nomicfoundation/hardhat-toolbox-viem";
import { defineConfig, task } from "hardhat/config";


const myConsole = task(
  "my-console",
  "Starts a console with predefined commands",
)
  .setAction(() => import("./tasks/my-console.js"))
  .build();


export default defineConfig({
  plugins: [hardhatToolboxViemPlugin],
  solidity: "0.8.28",
  tasks: [myConsole],
});
tasks/my-console.ts
export default function myConsoleTask(_, hre) {
  return hre.tasks.getTask("console").run({
    commands: ["const { viem } = await network.connect();"],
  });
}