tools-ethereum

name	tools-ethereum
description	Query and interact with Ethereum and EVM-compatible blockchains using the ecli CLI. Get balances, read blocks and transactions, call smart contract functions, send transactions, encode/decode calldata, and query event logs.
compatibility	Requires Node.js and npm. Network access needed for RPC calls.

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

Command	Purpose
get_balance	ETH balance for address
get_block_number	Latest block number
get_block	Block by number or hash
get_latest_block	Latest block details
get_transaction	Transaction by hash
get_transaction_count	Nonce for address
get_gas_price	Current gas price
get_fee_history	Historical fee data
get_chain_id	Network chain ID
get_code	Contract bytecode
get_storage_at	Raw storage slot
call_contract	Read contract (view/pure)
encode_calldata	Encode function call
decode_calldata	Decode calldata
get_contract_logs	Query events
get_transaction_logs	Logs from tx
estimate_gas	Estimate gas cost
send_transaction	Send tx (requires key)
wait_for_transaction_confirmation	Wait for receipt
sign_message	Sign message (requires key)

---

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

Variable	Description
ECLI_RPC_URL	Primary RPC endpoint
RPC_URL	Fallback RPC endpoint
ECLI_PRIVATE_KEY	Primary private key (0x-prefixed)
PRIVATE_KEY	Fallback private key

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