CLI Reference

@earnforge/cli is a full-featured command-line interface wrapping @earnforge/sdk. Every command supports --json for machine-readable output.

Installation

npm i -g @earnforge/cli

npx @earnforge/cli list --asset USDC

pnpm add -g @earnforge/cli

Environment Variables

Variable	Required	Description
`LIFI_API_KEY`	For `quote` only	LI.FI Composer API key for deposit quotes

Commands

earnforge list

List vaults with optional filters.

earnforge list --asset USDC --chain 8453 --min-tvl 1000000 --sort apy --limit 10
earnforge list --strategy conservative --json

Flag	Type	Default	Description
`--chain <id>`	number	all	Filter by chain ID
`--asset <sym>`	string	all	Filter by asset symbol
`--min-apy <n>`	float	none	Minimum APY (as fraction, e.g. 0.05 = 5%)
`--min-tvl <n>`	float	none	Minimum TVL in USD
`--sort <field>`	string	`apy`	Sort by `apy` or `tvl`
`--limit <n>`	number	`20`	Max results
`--strategy <preset>`	string	none	Strategy preset filter
`--json`	boolean	`false`	Output as JSON

Example output:

  Slug                    Name                APY      TVL         Protocol   Chain
  ----                    ----                ---      ---         --------   -----
  morpho:8453:_:0xbeef...          USDC Base Vault     5.23%    $120.5M     aave    8453
  morpho:1:_:0xdead...             USDC Morpho         4.87%    $89.2M      morpho  1
  euler:42161:_:0xcafe...         USDC Arbitrum       4.12%    $45.0M      euler   42161

  Showing 3 vaults

earnforge top

Show top vaults by APY for a given asset.

earnforge top --asset USDC --limit 5
earnforge top --asset WETH --chain 1 --json

Flag	Type	Default	Description
`--asset <sym>`	string	required	Asset symbol (e.g. USDC, WETH)
`--chain <id>`	number	all	Filter by chain ID
`--limit <n>`	number	`10`	Max results
`--json`	boolean	`false`	Output as JSON

earnforge vault

Get detailed vault info by slug.

earnforge vault morpho:8453:_:0xbeef0e0834849acc03f0089f01f4f1eeb06873c9
earnforge vault morpho:8453:_:0xbeef0e0834849acc03f0089f01f4f1eeb06873c9 --json

Displays: name, protocol, chain, APY breakdown (total/base/reward), TVL, underlying tokens, tags, isTransactional, isRedeemable, deposit/redeem packs, and description (if available).

earnforge portfolio

View portfolio positions for a wallet.

earnforge portfolio 0xYourWalletAddress
earnforge portfolio 0xYourWalletAddress --json

Shows all active Earn positions with chain, protocol, asset, USD balance, and native balance.

earnforge quote

Build a deposit quote for a vault.

earnforge quote --vault morpho:8453:_:0xbeef... --amount 100 --wallet 0xYour...
earnforge quote --vault morpho:8453:_:0xbeef... --amount 100 --wallet 0xYour... --optimize-gas
earnforge quote --vault morpho:8453:_:0xbeef... --amount 100 --wallet 0xYour... --from-chain 1 --json

Flag	Type	Default	Description
`--vault <slug>`	string	required	Vault slug
`--amount <human>`	string	required	Human-readable deposit amount
`--wallet <addr>`	string	required	Wallet address
`--from-token <addr>`	string	auto	Override source token address
`--from-chain <id>`	number	vault chain	Override source chain for cross-chain
`--optimize-gas`	boolean	`false`	Compare routes from multiple chains
`--json`	boolean	`false`	Output as JSON

Example output:

Deposit Quote -- USDC Base Vault

  Amount:      100 (100000000 raw, 6 decimals)
  From:        USDC on chain 8453
  To:          USDC Base Vault on chain 8453
  Est. Output: 99850000
  Duration:    15s
  Gas Cost:    $0.02
  Fee Cost:    $0.10

Transaction ready to sign via quote.transactionRequest

With --optimize-gas:

Gas-optimized routes for USDC Base Vault

  Base (8453): gas=$0.02 fee=$0.10 total=$0.12 time=15s << cheapest
  Optimism (10): gas=$0.03 fee=$0.15 total=$0.18 time=30s
  Ethereum (1): gas=$2.50 fee=$0.10 total=$2.60 time=45s

earnforge doctor

Run 18-pitfall diagnostics on a vault or environment.

earnforge doctor --vault morpho:8453:_:0xbeef...
earnforge doctor --env
earnforge doctor --vault morpho:8453:_:0xbeef... --json

Flag	Type	Default	Description
`--vault <slug>`	string	none	Vault slug to check
`--env`	boolean	`false`	Run environment checks only
`--json`	boolean	`false`	Output as JSON

Example doctor output:

Doctor Report -- USDC Base Vault

  Check                           Status
  -----                           ------
  Base URL (earn.li.fi)           PASS
  No auth on Earn Data            PASS
  Composer API key present        PASS
  Vault is transactional          PASS
  Vault is redeemable             PASS
  Underlying tokens exist         PASS
  APY total is a number           PASS
  APY reward normalized           PASS
  TVL is parseable string         PASS
  apy1d null handled              PASS
  apy7d null handled              PASS
  Description optional handled    PASS
  Pagination works                PASS
  Rate limiter active             PASS
  Decimal conversion available    PASS
  Quote uses GET not POST         PASS
  toToken = vault.address         PASS
  Cache TTL configured            PASS

  18/18 checks passed

earnforge risk

Calculate risk score for a vault.

earnforge risk morpho:8453:_:0xbeef0e0834849acc03f0089f01f4f1eeb06873c9
earnforge risk morpho:8453:_:0xbeef0e0834849acc03f0089f01f4f1eeb06873c9 --json

Example output:

Risk Score: STEAKUSDC

┌───────────────────┬──────────────┐
│ Dimension         │ Score        │
├───────────────────┼──────────────┤
│ TVL Magnitude     │ 10/10        │
├───────────────────┼──────────────┤
│ APY Stability     │ 10/10        │
├───────────────────┼──────────────┤
│ Protocol Maturity │ 9/10         │
├───────────────────┼──────────────┤
│ Redeemability     │ 10/10        │
├───────────────────┼──────────────┤
│ Asset Type        │ 9/10         │
├───────────────────┼──────────────┤
│ Verification      │ 10/10        │
├───────────────────┼──────────────┤
│ Reward Dependency │ 10/10        │
├───────────────────┼──────────────┤
│ Composite         │ 9.7/10 (low) │
└───────────────────┴──────────────┘

A vault carrying risk also prints a Flags section naming why. The composite alone says something is wrong; the flags say what:

Risk Score: USP

┌───────────────────┬───────────────┐
│ Dimension         │ Score         │
├───────────────────┼───────────────┤
│ TVL Magnitude     │ 3/10          │
├───────────────────┼───────────────┤
│ APY Stability     │ 10/10         │
├───────────────────┼───────────────┤
│ Protocol Maturity │ 7/10          │
├───────────────────┼───────────────┤
│ Redeemability     │ 10/10         │
├───────────────────┼───────────────┤
│ Asset Type        │ 9/10          │
├───────────────────┼───────────────┤
│ Verification      │ 1/10          │
├───────────────────┼───────────────┤
│ Reward Dependency │ 2/10          │
├───────────────────┼───────────────┤
│ Composite         │ 5.5/10 (high) │
└───────────────────┴───────────────┘

Flags
  ! flagged by LI.FI verification: apy_outlier
  ! 87% of APY comes from token incentives
  ! analytics 2660 minutes stale

That vault is the highest advertised APY in the fleet. Requires @earnforge/cli 1.0.1 or later: 1.0.0 printed five dimensions and no flags.

See the full Risk Scoring Guide for how each dimension is computed.

earnforge suggest

Get portfolio allocation suggestions.

earnforge suggest --amount 10000 --asset USDC
earnforge suggest --amount 50000 --asset USDC --strategy diversified --max-chains 3
earnforge suggest --amount 10000 --asset WETH --json

Flag	Type	Default	Description
`--amount <human>`	float	required	Total USD amount to allocate
`--asset <sym>`	string	required	Asset symbol
`--max-chains <n>`	number	`5`	Max chains to spread across
`--strategy <preset>`	string	none	Strategy preset
`--json`	boolean	`false`	Output as JSON

Example output:

Allocation Suggestion -- $10,000.00 in USDC
  Expected APY: 4.92%

  Vault                  Chain    Protocol   APY     Risk     %       Amount
  -----                  -----    --------   ---     ----     -       ------
  USDC Base Vault        8453     aave    5.23%   8.9/10   35.2%   $3,520.00
  USDC Morpho ETH        1        morpho  4.87%   8.5/10   28.1%   $2,810.00
  USDC Euler ARB         42161    euler   4.12%   7.2/10   20.3%   $2,030.00
  USDC Pendle OP         10       pendle     4.65%   7.0/10   16.4%   $1,640.00

earnforge watch

Watch a vault for APY/TVL changes in real time.

earnforge watch --vault morpho:8453:_:0xbeef... --apy-drop 20 --tvl-drop 30
earnforge watch --vault morpho:8453:_:0xbeef... --json

Flag	Type	Default	Description
`--vault <slug>`	string	required	Vault slug to watch
`--apy-drop <pct>`	float	none	APY drop threshold (%)
`--tvl-drop <pct>`	float	none	TVL drop threshold (%)
`--json`	boolean	`false`	Output events as JSON

Press Ctrl+C to stop watching.

Example output:

Watching morpho:8453:_:0xbeef... (Ctrl+C to stop)...
[2026-04-11T14:30:00.000Z] TICK APY: 5.23% (prev: 5.23%) TVL: $120.5M (prev: $120.5M)
[2026-04-11T14:31:00.000Z] APY-DROP APY: 4.10% (prev: 5.23%) TVL: $120.5M (prev: $120.5M)

earnforge chains

List all supported chains.

earnforge chains
earnforge chains --json

Example output:

Supported Chains

  Chain ID   Name         Network
  --------   ----         -------
  1          Ethereum     ethereum
  10         Optimism     optimism
  56         BSC          bsc
  100        Gnosis       gnosis
  130        Unichain     unichain
  137        Polygon      polygon
  143        Monad        monad
  146        Sonic        sonic
  5000       Mantle       mantle
  8453       Base         base
  42161      Arbitrum     arbitrum
  42220      Celo         celo
  43114      Avalanche    avalanche
  59144      Linea        linea
  80094      Berachain    berachain
  747474     Katana       katana

earnforge protocols

List all supported protocols.

earnforge protocols
earnforge protocols --json

Example output:

Supported Protocols

  Protocol            URL
  --------            ---
  aave             https://aave.com
  morpho           https://morpho.org
  euler            https://euler.finance
  pendle              https://pendle.finance
  maple               https://maple.finance
  ethena         https://ethena.fi
  ether.fi-liquid     https://ether.fi
  etherfi-staking      https://ether.fi
  upshift             https://upshift.finance
  neverland           https://neverland.finance
  yo         https://yo.finance

earnforge simulate

Simulate a deposit against the chain head using Composer’s own simulator.

earnforge simulate --vault morpho:8453:_:0xbeef... --amount 1000 --wallet 0xYourAddress
earnforge simulate --vault morpho:8453:_:0xbeef... --amount 1000 --wallet 0xYourAddress --json

Flag	Type	Default	Description
`--vault <slug>`	string	required	Vault slug
`--amount <human>`	string	required	Deposit amount, human-readable
`--wallet <addr>`	string	required	Wallet address
`--from-token <addr>`	string	the vault asset	Token to spend
`--slippage-bps <n>`	number	none	Slippage tolerance in basis points
`--allow-revert`	boolean	`false`	Return calldata even if the simulation reverts, with diagnostics
`--json`	boolean	`false`	Output as JSON

This compiles through Composer and simulates against the chain head, so it observes allowances, balances and protocol state. Exits non-zero on a simulated revert.

Earlier versions issued a bare eth_call, which cannot see any of that and reported SUCCESS for transactions that would revert on submission.

earnforge preflight

Run pre-deposit checks on a vault and wallet before you sign anything.

earnforge preflight --vault morpho:8453:_:0xbeef... --wallet 0xYourAddress --amount 1000

Flag	Type	Default	Description
`--vault <slug>`	string	required	Vault slug
`--wallet <addr>`	string	required	Wallet address
`--amount <human>`	string	none	Deposit amount, human-readable
`--wallet-chain <id>`	number	none	Wallet’s current chain ID
`--cross-chain`	boolean	`false`	Flag cross-chain deposit intent
`--json`	boolean	`false`	Output as JSON

earnforge withdraw

Build a withdrawal/redeem quote.

earnforge withdraw --vault morpho:8453:_:0xbeef... --amount 100 --wallet 0xYourAddress

Flag	Type	Default	Description
`--vault <slug>`	string	required	Vault slug
`--amount <human>`	string	required	Vault shares to redeem
`--wallet <addr>`	string	required	Wallet address
`--to-token <addr>`	string	none	Override destination token
`--to-chain <id>`	number	none	Override destination chain
`--slippage <n>`	number	none	Slippage tolerance (`0.03` = 3%)
`--json`	boolean	`false`	Output as JSON

earnforge allowance

Check an ERC-20 allowance for a spender.

earnforge allowance --token 0x8335... --owner 0xYourAddress \
  --spender 0xbeef... --amount 1000000 --chain 8453

Flag	Type	Default	Description
`--token <addr>`	string	required	ERC-20 token address
`--owner <addr>`	string	required	Token owner (wallet) address
`--spender <addr>`	string	required	Spender: from `quote.estimate.approvalAddress`
`--amount <raw>`	string	required	Required amount, smallest unit
`--chain <id>`	number	required	Chain ID
`--rpc <url>`	string	public RPC	Custom RPC URL
`--json`	boolean	`false`	Output as JSON

earnforge approve

Build an ERC-20 approval transaction. Returns unsigned calldata; it never signs or broadcasts.

earnforge approve --token 0x8335... --spender 0xbeef... --chain 8453

Flag	Type	Default	Description
`--token <addr>`	string	required	ERC-20 token address
`--spender <addr>`	string	required	Spender: from `quote.estimate.approvalAddress`
`--chain <id>`	number	required	Chain ID
`--amount <raw>`	string	unlimited	Amount to approve
`--json`	boolean	`false`	Output as JSON

earnforge compare

Side-by-side comparison of two or more vaults.

earnforge compare morpho:8453:_:0xbeef... aave:1:_:0x9277...
earnforge compare morpho:8453:_:0xbeef... aave:1:_:0x9277... --json

Argument	Description
`<slugs...>`	Vault slugs to compare, space-separated

earnforge apy-history

Fetch 30-day APY history from DeFiLlama.

earnforge apy-history morpho:8453:_:0xbeef0e0834849acc03f0089f01f4f1eeb06873c9

Argument	Description
`<slug>`	Vault slug

The Earn API exposes only current and trailing APY, so history comes from DeFiLlama via a protocol-slug mapping.

earnforge init

Scaffold a new Next.js + wagmi + @earnforge/react project.

earnforge init my-yield-app

Argument	Description
`<name>`	Project name

The scaffold filters verification-flagged vaults with the reason inline, shows risk alongside APY, and keeps the API key in a Server Component: a scaffolder’s output becomes the pattern every new project copies.

JSON Output

Every command supports --json to output structured JSON instead of formatted tables. This is designed for piping into other tools, scripts, or CI pipelines.

earnforge top --asset USDC --limit 3 --json | jq '.[0].apy'
earnforge doctor --vault morpho:8453:_:0xbeef... --json | jq '.checks | map(select(.status == "FAIL"))'