CLI Reference
contract-dev watches contracts and wallets, defines metrics, builds tables, answers questions about the workspace, and manages reports and alerts from the terminal.
Install
Install the @contract-dev/cli npm package globally (or use npx):
npm install -g @contract-dev/cliSign in
contract-dev loginThis opens the browser with a one-time code; approving it saves credentials to ~/.contract.dev/credentials.json.
Commands
Account:
login/whoami/logout— connect the CLI to your contract.dev account, show which account and workspace it acts as, revoke the key.workspace— the workspace the CLI acts on, its brief on the protocol and what it holds; write the brief; switch workspace.status— the workspace at a glance: contracts, transactions, metrics, monitors, open alerts.
Watch contracts:
watch/watch wallet/rename/unwatch/contracts/factory— the contracts and wallets the workspace watches, an unverified contract’s ABI, and the contracts a factory deployed.
Groups:
group— a group’s members, the rules that keep it filled, its name pattern, columns and monitors.
Tables:
table— state tables of the things inside contracts (loans, withdrawal requests), and activity tables of events and the workspace’s data.
Metrics:
metrics/metric— state and activity metrics on a contract, wallet, group or table; export.
Ask and explore:
find/describe/query/events/history/holders/who/read— questions over the workspace.tx/address/block/wallet/source— any transaction, address, block or verified source on a supported chain.
Notifications:
notify/channels— reports on a schedule, and alerts when something happens or a condition is met; the destinations they send to.alerts— what opened; acknowledge it.
Agents:
tool/skills— the tools an agent calls, and the agent skill for Claude Code, Codex, Cursor and other coding agents.
Nouns work too: contracts list|add|rename|remove, wallets list|add|rename|remove, alerts list.
Output and global flags
| Flag | Description |
|---|---|
--json | Print the command’s result as JSON instead of text. An error prints { "error": "…" }, with a "code" when the refusal carries one, and exits with code 1. |
--version | Print the CLI version. |
help | contract-dev help lists every command. contract-dev <command> help, -h or --help prints one command’s usage. |
--chain <id|name> | Wherever a chain is named, a name works as well as an id: ethereum, base, arbitrum, optimism, bnb, polygon, hyperevm, monad, avalanche, plasma, arc, robinhood, unichain, megaeth, linea, fraxtal, blast, sei, celo, sonic, stable, mantle, gnosis, worldchain, berachain, abstract, katana, ink, scroll, morph, soneium, zksync, flare, tempo, boba, rootstock, opbnb, mode, citrea, zetachain, sepolia. Any other chain, such as a testnet other than Sepolia, by its numeric id. |
watch, watch wallet and block require --chain. An address needs it unless the workspace watches that address on one chain. tx and wallet without it look on every chain; source without it uses a watched contract’s chain or looks the address up; factory without it reads Ethereum.
First commands
# Watch a contract
contract-dev watch 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --chain ethereum --name "USDC"
# Track its total supply
contract-dev metric define "USDC supply" --on USDC --call "totalSupply()" --decimals 6
# Connect Telegram, then alert when the supply falls below 50B
contract-dev channels add telegram
contract-dev notify add alert "USDC supply low" --on metric:"USDC supply" --when "value < 50000000000" --to telegram
# The workspace at a glance
contract-dev status
# Its brief on the protocol, and what it holds
contract-dev workspace