CLI
Watch contracts, track metrics, manage monitors and destinations, acknowledge alerts; create and reset Stagenets, push contracts to them, generate funded wallets, override balances and state, and pin state to the live chain.
Commands
Account:
login/whoami/logout— connect the CLI to your contract.dev account.workspace— show or switch the workspace the CLI acts on.status— the workspace at a glance.
Watch contracts:
watch/rename/unwatch— the contracts your workspace watches.
Metrics:
track/metrics/untrack— record a balance, supply, call result, TVL or method telemetry over time, and export its history.
Monitoring:
monitor/monitors/channels— alert when a metric crosses a line; tune the default monitors; manage destinations.incidents— what fired, and acknowledge it.
Stagenets:
stagenets/stagenet use/create/delete/reset— create stagenets, pick the one commands target, reset its state.push-contracts— push compiled contracts from your Hardhat/Foundry project.generate-wallet— generate funded wallets.balance/erc20-balance— set native and ERC20 balances.state— set code, nonce and storage; resync a contract to the live chain.impersonate— send transactions from any address.follow/unfollow— pin state to the live chain.function-override— force contract functions to return fixed values.
Every command also reads as a noun: contracts list, contracts add <address>, metrics track …, monitor list, incidents list, stagenet list.
Install
Install the contract.dev npm package globally (or use npx):
npm install -g contract.devSign in
contract.dev loginThis opens the browser with a one-time code; approving it saves credentials to ~/.contract.dev/credentials.json.
Target a stagenet
Watch, metric and monitor commands act on your workspace and need nothing more. Stagenet commands additionally need a stagenet to talk to:
# List the active workspace's stagenets
contract.dev stagenets
contract.dev stagenet use my-stagenetOr override per command with --stagenet <name>, or --rpc-url <url> (which needs no login at all).
Output
Every command prints usage with help (contract.dev track help).
| Flag | |
|---|---|
--json | Print the command’s result as JSON instead of text. Works on every command. Errors print { "error": "…" } with exit code 1. |
--version | Print the CLI version. |
--chain <id|name> | Wherever a chain is named, a name works as well as an id: ethereum, arbitrum, avalanche, sepolia, base, optimism, polygon, bnb, monad. |
Requests time out after 30 seconds. Stagenet commands allow two minutes.
Run your first commands
# Watch a contract in your workspace
contract.dev watch 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --name "USDC"
# Track its total supply and alert above a threshold
contract.dev track 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 total-supply --label "USDC supply"
contract.dev monitor add "USDC supply" --above 60000000000 --to telegram
# The workspace at a glance
contract.dev status
# Create a stagenet and push your Hardhat/Foundry project's compiled contracts to it
contract.dev stagenet create eth-staging --chain ethereum
contract.dev push-contracts
# Generate a funded wallet on your stagenet
contract.dev generate-wallet