sol-console

An interactive workbench for any Solidity smart contract, allowing you to test, debug, and transact from your terminal.

Launching the Console

There are two primary ways to start a session:

1. From a Local Solidity File

Use this method to compile and either deploy a fresh instance of a local contract or attach to an existing one.


# Compile and deploy your local contract to a testnet
sol-console --contract-path ./contracts/MyToken.sol --rpc-url http://localhost:8545

# Attach to an already deployed contract
sol-console --contract-path ./contracts/MyToken.sol --address 0x123... --rpc-url <URL>

2. From a Verified Etherscan Contract (Pro Feature)

This is the fastest way to interact with any deployed and verified contract on a public network.


# Connect to the BAYC contract on Ethereum Mainnet
sol-console --from-etherscan 0xBC4... --rpc-url YOUR_MAINNET_RPC_URL

Local Development Environments (Pro)

For advanced testing, Pro users can spin up a local Anvil node directly from the console.

Standalone Node

The --standalone flag starts a fresh, local Anvil node. This is perfect for clean-room testing and development without needing any external network.

sol-console --contract-path ./c/MyContract.sol --standalone

Mainnet Forking

The --fork-url flag starts a local Anvil node that is a fork of a live network. This is the ultimate tool for realistic testing, allowing you to interact with live mainnet protocols from your local machine without spending real gas.

sol-console --from-etherscan 0x1f98... --fork-url $MAINNET_RPC

You can also use --fork-block-number to fork from a specific point in history.

Interacting with Contracts

Once inside the console, your contract is available as the contract variable. To see a list of all available functions, type contract.help().

Read calls (view/pure) print the return value, while write calls send a transaction and print the receipt.


# Read call
contract> contract.balanceOf("vitalik.eth")
<- 55000...

# Write call
contract> contract.transfer("0xAb58...", 1000)
✅ Transaction Confirmed...

Test Generation (Pro)

Pro users can record their console session and automatically generate a Foundry test script.

  1. Start a session and begin recording with record start.
  2. Make function calls as you normally would.
  3. Use assert.eq(contract.call(), expected_value) to add assertions to your test. The tool will verify the assertion live and record it if it passes.
  4. Run record stop --as=foundry to save the generated test file.

contract> record start
> Recording started.

contract> contract.mint(account(1), 100)
✅ Transaction Confirmed...

contract> assert.eq(contract.balanceOf(account(1)), 100)
✅ Assertion recorded.

contract> record stop --as=foundry
> Test file generated at test/MyContract.t.sol

Managing Accounts

When using --standalone or --fork-url, 20 pre-funded test accounts are available.

  • Use use(1) to switch your active signing wallet to account #1.
  • Use account(1) inside a function call to pass the address of account #1 as an argument.