forge script


forge-script - Run a smart contract as a script, building transactions that can be sent onchain.


forge script [options] path [args…]


Run a smart contract as a script, building transactions that can be sent onchain.

Scripts can be used to apply state transitions on live contracts, or deploy and initialize a complex set of smart contracts using Solidity.


    Broadcasts the transactions.

    Open the script in the debugger. Takes precedence over broadcast.

--gas-estimate-multiplier multiplier
    Relative percentage by which to multiply all gas estimates. (i.e. set to 200 to double them)     Default: 130

    Output results in JSON format.
    Note: The output is under development and prone to change.

    Use legacy transactions instead of EIP1559 ones. This is auto-enabled for common networks without EIP1559.

    Resumes submitting transactions that failed or timed-out previously.

--sig signature
    The signature of the function you want to call in the contract, or raw calldata.
    Default: run()

    Skips on-chain simulation.

    Skip compilation of non-essential contract directories like test or script (usage --skip test).

    Remove interactive prompts which appear if the contract is near the EIP-170 size limit.

    Makes sure a transaction is sent, only after its previous one has been confirmed and succeeded.

--target-contract contract_name
    The name of the contract you want to run.

    Sets the priority gas price for EIP1559 transactions. Useful for when gas prices are volatile and you want to get your transaction included.

--with-gas-price price
    Sets the gas price for broadcasted legacy transactions, or the max fee for broadcasted EIP1559 transactions.
    Note: To set the gas price in the execution environment of the script use --gas-price instead (see below).

Etherscan Options

--chain chain_name
    The Etherscan chain.

--etherscan-api-key key
    Etherscan API key, or the key of an Etherscan configuration table.
    Environment: ETHERSCAN_API_KEY

Verification Options

    If it finds a matching broadcast log, it tries to verify every contract found in the receipts.

--verifier name
    The verification provider. Available options: etherscan, sourcify & blockscout. Default: etherscan. Note: make sure you add "/api?" to the end of the Blockscout homepage explorer URL.

--verifier-url url
    The optional verifier url for submitting the verification request.
    Environment: VERIFIER_URL

--delay delay
    Optional timeout to apply in between attempts in seconds. Defaults to 3.

--retries retries
    Number of attempts for retrying. Defaults to 15.

Cache Options

    Clear the cache and artifacts folder and recompile.

Linker Options

--libraries libraries
    Set pre-linked libraries.

    The parameter must be in the format <remapped path to lib>:<library name>:<address>, e.g. src/Contract.sol:Library:0x....

    Can also be set in your configuration file as libraries = ["<path>:<lib name>:<address>"].

Compiler Options

    Activate the Solidity optimizer.

--optimizer-runs runs
    The number of optimizer runs.

    Use the Yul intermediate representation compilation pipeline.

    How to treat revert and require reason strings.

--use solc_version
    Specify the solc version, or a path to a local solc, to build with.

    Valid values are in the format x.y.z, solc:x.y.z or path/to/solc.

    Do not access the network. Missing solc versions will not be installed.

    Do not auto-detect solc.

--ignored-error-codes error_codes
    Ignore solc warnings by error code. The parameter is a comma-separated list of error codes.

--extra-output selector
    Extra output to include in the contract's artifact.

    Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

    For a full description, see the Solidity docs.

--extra-output-files selector
    Extra output to write to separate files.

    Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

    For a full description, see the Solidity docs.

--evm-version version
    The target EVM version.

Project Options

    Generate build info files.

--build-info-path path
    Output path to directory that build info files will be written to.

--root path
    The project's root path. By default, this is the root directory of the current git repository, or the current working directory.

-C path
--contracts path
    The contracts source directory.
    Environment: DAPP_SRC

--lib-paths path
    The path to the library folder.

-R remappings
--remappings remappings
    The project's remappings.

    The parameter is a comma-separated list of remappings in the format <source>=<dest>.

--cache-path path
    The path to the compiler cache.

--config-path file
    Path to the config file.

    This is a convenience flag, and is the same as passing --contracts contracts --lib-paths node-modules.

-o path
--out path
    The project's artifacts directory.

    Suppress all output.

Build Options

    Print compiled contract names.

    Print compiled non-test contract sizes, exiting with code 1 if any of them are above the size limit.

Watch Options

-w [path...]
--watch [path...]
    Watch specific file(s) or folder(s).

    By default, the project's source directory is watched.

-d delay
--delay delay
    File update debounce delay.

    During the delay, incoming change events are accumulated and only once the delay has passed, is an action taken.
    Note that this does not mean a command will be started: if --no-restart is given and a command is already running, the outcome of the action will be to do nothing.

    Defaults to 50ms. Parses as decimal seconds by default, but using an integer with the ms suffix may be more convenient.

    When using --poll mode, you'll want a larger duration, or risk overloading disk I/O.

    Do not restart the command while it's running.

    Explicitly re-run the command on all files when a change is made.

Wallet Options - Raw

-i --interactives num
    Open an interactive prompt to enter your private key. Takes a value for the number of keys to enter.
    Default: 0

--mnemonic-indexes indexes
    Use the private key from the given mnemonic index. Used with --mnemonic-path.
    Default: 0

--mnemonic-paths paths
    Use the mnemonic file at the specified path(s).

--private-key raw_private_key
    Use the provided private key.

--private-keys raw_private_keys
    Use the provided private keys.

Wallet Options - Keystore

--keystores paths
    Use the keystores in the given folders or files.
    Environment: ETH_KEYSTORE

--account account-name
    Use a keystore from the default keystores folder (~/.foundry/keystores) by its filename.

--password passwords
    The keystore passwords. Used with --keystore.

Wallet Options - Hardware Wallet

    Use a Trezor hardware wallet.

    Use a Ledger hardware wallet.

--hd-paths paths
    The derivation paths to use with hardware wallets.

Wallet Options - Remote

-a addresses --froms addresses     Sign the transaction with the specified accounts on the RPC.     Environment: ETH_FROM

EVM Options

-f url
--rpc-url url
--fork-url url
    Fetch state over a remote endpoint instead of starting from an empty state.

    If you want to fetch state from a specific block number, see --fork-block-number.

--fork-block-number block
    Fetch state from a specific block number over a remote endpoint. See --fork-url.

--fork-retry-backoff <BACKOFF>
     Initial retry backoff on encountering errors.

    Explicitly disables the use of RPC caching.

    All storage slots are read entirely from the endpoint. See --fork-url.

    Verbosity of the EVM.

    Pass multiple times to increase the verbosity (e.g. -v, -vv, -vvv).

    Verbosity levels:
    - 2: Print logs for all tests
    - 3: Print execution traces for failing tests
    - 4: Print execution traces for all tests, and setup traces for failing tests
    - 5: Print execution and setup traces for all tests

--sender address
    The address which will be executing tests

--initial-balance balance
    The initial balance of deployed contracts

    Enables the FFI cheatcode

Executor Options

--base-fee <FEE>
--block-base-fee-per-gas <FEE>
    The base fee in a block (in wei).

--block-coinbase address
    The coinbase of the block.

--block-difficulty difficulty
    The block difficulty.

--block-gas-limit gas_limit
    The block gas limit.

--block-number block
    The block number.

--block-timestamp timestamp
    The timestamp of the block (in seconds).

--chain-id chain_id
    The chain ID.

--gas-limit gas_limit
    The block gas limit.

--gas-price gas_price
    The gas price (in wei).

--tx-origin address
    The transaction origin.

Common Options

    Prints help information.


  1. Run BroadcastTest as a script, broadcasting generated transactions on-chain

    forge script ./test/Broadcast.t.sol --tc BroadcastTest --sig "deploy()" \
        -vvv --fork-url $SEPOLIA_RPC_URL
  2. Deploy a contract on Polygon (see scripting tutorial for an example script). The verifier url is different for every network.

    forge script script/NFT.s.sol:MyScript --chain-id 137 --rpc-url $RPC_URL \
        --etherscan-api-key $POLYGONSCAN_API_KEY --verifier-url \
        --broadcast --verify -vvvv
  3. Resume a failed script. Using the above as an example, remove --broadcast add --resume

    forge script script/NFT.s.sol:MyScript --chain-id 137 --rpc-url $RPC_URL \
        --etherscan-api-key $POLYGONSCAN_API_KEY --verifier-url \
        --verify -vvvv --resume
  4. Verify contracts that were just deployed with a script

    forge script script/NFT.s.sol --rpc-url $RPC_URL --verify --resume