Tools Ethereum

tools-ethereum CLI

Use ecli to query blockchain data and execute transactions on any EVM network.

Quick Start

# Option 1: Use npx (no install required)
npx -y tools-ethereum --rpc-url $RPC_URL get_balance --address 0x... 

# Option 2: Install globally
npm install -g tools-ethereum # or use pnpm/volta/...
ecli --rpc-url $RPC_URL get_balance --address 0x...

Configuration

you can either provided the env via your shell

# Set RPC endpoint (required for all commands)
export ECLI_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY

# For transactions, also set private key
export ECLI_PRIVATE_KEY=0x...

# Query example
ecli --rpc-url $RPC_URL get_balance --address 0x742d35Cc6634C0532925a3b844Bc9e7595f5a321

or by using .env / .env.local file that the cli read automatically

All commands output JSON. Parse with jq or process programmatically.

Commands Overview

Reading Blockchain Data

Get Balance

ecli --rpc-url $RPC_URL get_balance --address 0x...
# Output: { "address": "0x...", "balance": "1000000000000000000", "balanceInEther": 1.0 }

Get Block Info

# By number
ecli --rpc-url $RPC_URL get_block --block-number 18000000 

# By hash  
ecli --rpc-url $RPC_URL get_block --block-hash 0x... 

# Latest block
ecli --rpc-url $RPC_URL get_latest_block 

# Include full transaction list
ecli --rpc-url $RPC_URL get_block --block-number latest --include-transactions 

Get Transaction Details

ecli --rpc-url $RPC_URL get_transaction --tx-hash 0x... 
# Returns: hash, from, to, value, gas, gasPrice, blockNumber, nonce, input

Check if Address is Contract

ecli --rpc-url $RPC_URL get_code --address 0x... 
# Returns bytecode. If "0x", it's an EOA (not a contract)

Read Storage Slot

ecli --rpc-url $RPC_URL get_storage_at --address 0x... --slot 0x0 

Calling Smart Contracts

Read Contract State (No Gas Required)

Use human-readable ABI format for the --abi parameter.

# Call with no arguments
ecli --rpc-url $RPC_URL call_contract \
  --address 0x... \
  --abi "function totalSupply() returns (uint256)" \
  

# Call with arguments (comma-separated)
ecli --rpc-url $RPC_URL call_contract \
  --address 0x... \
  --abi "function balanceOf(address) returns (uint256)" \
  --args 0x742d35Cc6634C0532925a3b844Bc9e7595f5a321 \
  

# Call with JSON array args
ecli --rpc-url $RPC_URL call_contract \
  --address 0x... \
  --abi "function allowance(address,address) returns (uint256)" \
  --args '["0xOwner...","0xSpender..."]' \
  

Common ERC20 calls:

# Token name
ecli --rpc-url $RPC_URL call_contract --address $TOKEN --abi "function name() returns (string)" 

# Token symbol
ecli --rpc-url $RPC_URL call_contract --address $TOKEN --abi "function symbol() returns (string)" 

# Decimals
ecli --rpc-url $RPC_URL call_contract --address $TOKEN --abi "function decimals() returns (uint8)" 

# Balance
ecli --rpc-url $RPC_URL call_contract --address $TOKEN --abi "function balanceOf(address) returns (uint256)" --args $HOLDER 

Encode/Decode Calldata

# Encode function call to calldata
ecli --rpc-url $RPC_URL encode_calldata \
  --abi "function transfer(address,uint256)" \
  --args "0xRecipient...,1000000000000000000" \
  
# Output: { "calldata": "0xa9059cbb..." }

# Decode calldata back to function + args
ecli --rpc-url $RPC_URL decode_calldata \
  --calldata 0xa9059cbb... \
  --abi "function transfer(address,uint256) returns (bool)" \
  

Querying Event Logs

Get Contract Events

ecli --rpc-url $RPC_URL get_contract_logs \
  --contract-address 0x... \
  --from-block 18000000 \
  --to-block 18001000 \
  --event-abis "event Transfer(address indexed from, address indexed to, uint256 value)" \
  

Get Logs from Transaction

ecli --rpc-url $RPC_URL get_transaction_logs \
  --tx-hash 0x... \
  --event-abis "event Transfer(address indexed from, address indexed to, uint256 value)" \
  

Sending Transactions

Requires: ECLI_PRIVATE_KEY or PRIVATE_KEY environment variable (hex string starting with 0x).

Send ETH

ecli --rpc-url $RPC_URL send_transaction \
  --to 0xRecipient... \
  --value "1000000000000000000" \
  
# value is in wei (1 ETH = 1000000000000000000)

Call Contract Function

# Using ABI + args
ecli --rpc-url $RPC_URL send_transaction \
  --to 0xContract... \
  --abi "function transfer(address,uint256)" \
  --args "0xRecipient...,1000000" \
  

# Using raw calldata
ecli --rpc-url $RPC_URL send_transaction \
  --to 0xContract... \
  --data 0xa9059cbb... \
  

Gas Configuration

ecli --rpc-url $RPC_URL send_transaction \
  --to 0x... \
  --value "1000000000000000000" \
  --gas "21000" \
  --max-fee-per-gas "50000000000" \
  --max-priority-fee-per-gas "2000000000" \
  

Wait for Confirmation

# Send and capture hash
result=$(ecli --rpc-url $RPC_URL send_transaction --to $TO --value "1000000000000000000" )
txHash=$(echo $result | jq -r '.transactionHash')

# Wait for confirmation
ecli --rpc-url $RPC_URL wait_for_transaction_confirmation --hash $txHash 

Gas Estimation

Estimate before sending to avoid failures.

# Simple transfer
ecli --rpc-url $RPC_URL estimate_gas --to 0x... --value "1000000000000000000" 

# Contract call
ecli --rpc-url $RPC_URL estimate_gas \
  --to 0xContract... \
  --abi "function transfer(address,uint256)" \
  --args "0xRecipient...,1000000" \
  
# Output: { "gasUsed": "65000", "gasEstimateInGwei": 0.000065 }

ABI Format Reference

The CLI uses human-readable Solidity ABI format:

function name() returns (uint256)
function balanceOf(address owner) view returns (uint256)
function transfer(address to, uint256 amount) returns (bool)
function approve(address spender, uint256 value) returns (bool)
event Transfer(address indexed from, address indexed to, uint256 value)
event Approval(address indexed owner, address indexed spender, uint256 value)

Types: address, uint256, int256, bool, bytes, bytes32, string, arrays (address[])

Common Patterns

ERC20 Token Transfer

# Check balance first
balance=$(ecli --rpc-url $RPC_URL call_contract --address $TOKEN --abi "function balanceOf(address) returns (uint256)" --args $SENDER  | jq -r '.result')

# Send transfer
ecli --rpc-url $RPC_URL send_transaction \
  --to $TOKEN \
  --abi "function transfer(address,uint256) returns (bool)" \
  --args "$RECIPIENT,$AMOUNT" \
  

ERC20 Approve + TransferFrom

# Approve spender
ecli --rpc-url $RPC_URL send_transaction \
  --to $TOKEN \
  --abi "function approve(address,uint256) returns (bool)" \
  --args "$SPENDER,$AMOUNT" \
  

Estimate Then Send

gas=$(ecli --rpc-url $RPC_URL estimate_gas --to $CONTRACT --abi "function mint()"  | jq -r '.gasUsed')
# Add 20% buffer
ecli --rpc-url $RPC_URL send_transaction --to $CONTRACT --abi "function mint()" --gas $((gas * 120 / 100)) 

Environment Variables

The --rpc-url flag overrides environment variables.

Error Handling

All commands return JSON. Errors include an error field:

{ "error": "Transaction not found", "stack": "..." }

Exit codes: 0 = success, 1 = error.

Multi-Network Usage

# Ethereum Mainnet
ecli --rpc-url $RPC_URL get_chain_id --rpc-url https://eth-mainnet.g.alchemy.com/v2/KEY

# Polygon
ecli --rpc-url $RPC_URL get_gas_price --rpc-url https://polygon-rpc.com

# Arbitrum
ecli --rpc-url $RPC_URL get_block_number --rpc-url https://arb1.arbitrum.io/rpc

# Local (Anvil/Hardhat)
ecli --rpc-url $RPC_URL get_balance --address 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --rpc-url http://localhost:8545

Converted and distributed by TomeVault — claim your Tome and manage your conversions.