CLI Command Reference - Fibrous Documentation

Commands use this general pattern:

npx fibx@latest <command> [arguments] [options]

Commands that accept --chain default to base unless documented otherwise.

quote — Price Quotes (No Auth)

Get a swap price without a wallet, a session, or any setup. It is the fastest pricing entry point for trying FibX or answering a question before a user has logged in. Other public or local commands, including status, tx-status, config, policy, and aave markets, also work without an active session.

npx fibx@latest quote <amount> <from-token> <to-token> [--chain <chain>] [--slippage <number>] [--json]

Parameter	Type	Required	Description
`amount`	number	Yes	Amount of the input token
`from-token`	string	Yes	Input token symbol or supported contract address
`to-token`	string	Yes	Output token symbol or supported contract address
`chain`	string	No	`base`, `hyperevm`, or `monad`
`slippage`	number	No	Slippage tolerance in percent (default: `0.5`)

Examples

# Check a price on Base
npx fibx@latest quote 0.01 ETH USDC

# Compare a pair on Monad
npx fibx@latest quote 1 MON USDC --chain monad

# Machine-readable output for scripts
npx fibx@latest quote 0.1 ETH USDC --json

For routed swaps, the output shows the input and output amounts, exchange rate, slippage, router, and chain. A direct native/wrapped-native pair instead reports a 1:1 wrap or unwrap operation without slippage or router fields. To execute the same trade, use trade with the same arguments once authenticated.

auth — Authentication

Manage the wallet session. Authentication is required before commands that inspect or act on a wallet. Three signing paths are available; each of these commands replaces the active session. The comparison is on Signing Paths and the Local Policy.

auth setup

Choose how FibX should sign, with the trade-offs explained. Interactive: it asks one question and runs the matching flow below.

npx fibx@latest auth setup

auth connect (Your Own Wallet)

Pair a wallet you already have over WalletConnect. The CLI prints a QR code and a wc: URI and waits for the wallet app to approve. Every later transaction is approved in that wallet, on your phone; nothing is signed on this machine.

npx fibx@latest auth connect

# For a host that renders its own QR: prints { "uri": "wc:…" }
npx fibx@latest auth connect --json

auth import (Private Key)

Import an existing private key to create a local wallet session that runs unattended. The CLI opens an interactive prompt where you paste the key.

npx fibx@latest auth import

The key is encrypted at rest with AES-256-GCM and signs locally. No external server holds your private key with this method — and the local signing policy is the only thing bounding it, so set one with policy. Authentication via email OTP. This creates a server-managed wallet through Privy — useful when you do not have an existing private key and want FibX to act without you.

# Step 1: Send OTP to email
npx fibx@latest auth login <email>

# Step 2: Verify with the code received
npx fibx@latest auth verify <email> <code>

Parameter	Type	Required	Description
`email`	string	Yes	User’s email address
`code`	string	Yes	OTP code received via email

auth logout

End the active session. Also ends a WalletConnect pairing.

npx fibx@latest auth logout

policy — Signing Policy

Read and change the local signing policy: a JSON file the user owns, evaluated before every signature on all three signing paths. No session is needed.

npx fibx@latest policy show
npx fibx@latest policy set <rule> <value>
npx fibx@latest policy clear [rule] [-y]

Rule	Meaning	Example
`<chain>.maxValue`	Largest native value (ETH / HYPE / MON) in one transaction	`base.maxValue 0.05`
`allowedChains`	Chains anything may be signed on (comma-separated)	`allowedChains base,monad`
`<chain>.allowedDestinations`	Addresses anything may be sent to on that chain	`base.allowedDestinations 0xAbC…,0xDeF…`
`expiry`	When the whole policy stops applying (ISO-8601)	`expiry 2026-12-31T00:00:00Z`

set replaces the rule’s previous value. clear with no rule removes the whole policy and asks for confirmation; -y skips the question. A transaction outside the policy is refused before any signature is requested, with POLICY_BLOCKED and the rule named.

maxValue bounds the native value only. An ERC-20 transfer reaches the policy with value: 0, so the cap never sees the token amount; allowedDestinations is what bounds where tokens may go.

No file means everything is permitted. A file that exists but cannot be parsed means everything is refused until it is fixed or cleared — a corrupt policy does not fail open.

Examples

# Cap one transaction's native value on Base
npx fibx@latest policy set base.maxValue 0.05

# Only allow Base and Monad
npx fibx@latest policy set allowedChains base,monad

# Only allow sends to two addresses on Base
npx fibx@latest policy set base.allowedDestinations 0xAbC...,0xDeF...

# Remove the cap
npx fibx@latest policy clear base.maxValue

status — Session Status

Check whether a session is active, which signing path it uses, and the authenticated wallet address.

npx fibx@latest status [--chain <chain>] [--json]

address — Wallet Address

Print the active wallet address.

npx fibx@latest address [--json]

wallets — Wallet Details

Show the active wallet details for the current session.

npx fibx@latest wallets [--json]

portfolio — Cross-Chain Portfolio

View a consolidated portfolio across all supported chains with USD-valued token holdings and DeFi positions.

npx fibx@latest portfolio [--json]

Parameter	Type	Required	Description
`json`	flag	No	Output the portfolio as JSON

Examples

# Human-readable portfolio summary
npx fibx@latest portfolio

# Structured JSON for automation
npx fibx@latest portfolio --json

The portfolio view aggregates holdings across Base, HyperEVM, and Monad. It also includes Aave V3 collateral and debt positions when available.

balance — Check Balances

Fetch native and ERC-20 token balances for the authenticated wallet.

npx fibx@latest balance [--chain <chain>] [--json]

Parameter	Type	Required	Description
`chain`	string	No	`base`, `hyperevm`, or `monad`
`json`	flag	No	Output as JSON

Base
HyperEVM
Monad

npx fibx@latest balance

npx fibx@latest balance --chain hyperevm

npx fibx@latest balance --chain monad

send — Transfer Tokens

Send native tokens or ERC-20 tokens to a recipient address. FibX performs a command-specific preflight before submission.

npx fibx@latest send <amount> <recipient> [token] [--chain <chain>] [--simulate] [--json]

Parameter	Type	Required	Description
`amount`	number	Yes	Amount to send
`recipient`	string	Yes	Destination address (`0x...`)
`token`	string	No	Token symbol or supported contract address; omit for native token
`chain`	string	No	`base`, `hyperevm`, or `monad`
`simulate`	flag	No	Preview the transfer without submitting it
`json`	flag	No	Output as JSON

If token is omitted, the chain’s native token is used (ETH on Base, HYPE on HyperEVM, MON on Monad).

Examples

# Send native ETH on Base
npx fibx@latest send 0.01 0xRecipient

# Send ERC-20 on Base
npx fibx@latest send 100 0xRecipient USDC

# Send native MON on Monad
npx fibx@latest send 1 0xRecipient --chain monad

# Preview a native transfer
npx fibx@latest send 0.1 0xRecipient --simulate

trade: Swap Tokens

Exchange one token for another via Fibrous aggregation. The CLI finds a route, handles token approvals, estimates the main swap path, and submits it.

npx fibx@latest trade <amount> <from_token> <to_token> [--chain <chain>] [--slippage <n>] [--approve-max] [--simulate] [--json]

Parameter	Type	Required	Description
`amount`	number	Yes	Amount of the source token to swap
`from_token`	string	Yes	Source token symbol or supported contract address
`to_token`	string	Yes	Target token symbol or supported contract address
`chain`	string	No	`base`, `hyperevm`, or `monad`
`slippage`	number	No	Slippage tolerance in percent (default: `0.5`), 0.01–50
`approve-max`	flag	No	Use infinite approval instead of exact amount
`simulate`	flag	No	Return a no-broadcast preview of the main swap
`json`	flag	No	Output as JSON

The trade command automatically detects Wrap (Native → Wrapped) and Unwrap (Wrapped → Native) operations and executes them directly via contract calls, bypassing the aggregator routing to save gas.

If the source is an ERC-20 token with insufficient allowance, trade --simulate returns requiresApproval: true without submitting an approval. Because the swap cannot be estimated safely in that state, the preview omits the gas estimate.

A live routed ERC-20 trade may confirm an approval transaction before estimating and submitting the swap. If the later swap step fails, that approval remains on-chain. --simulate broadcasts neither transaction.

Examples

Base
HyperEVM
Monad
Custom Slippage
Swap Preview

npx fibx@latest trade 0.1 ETH USDC

npx fibx@latest trade 1 HYPE USDC --chain hyperevm

npx fibx@latest trade 1 MON USDC --chain monad

npx fibx@latest trade 0.1 ETH USDC --slippage 1.0

npx fibx@latest trade 0.1 ETH USDC --simulate

aave — Aave V3 (Base Only)

Manage Aave V3 lending positions on Base. Supply assets to earn yield, borrow against collateral, repay debt, or withdraw.

Aave V3 operations always target Base. The global --chain option does not change the Aave network, so omit it for aave commands.

npx fibx@latest aave <action> [amount] [token] [--simulate] [--json]

Parameter	Type	Required	Description
`action`	string	Yes	`status`, `markets`, `supply`, `borrow`, `repay`, `withdraw`
`amount`	string	Yes (except `status`, `markets`)	Amount or `max` for full repay/withdraw
`token`	string	Yes (except `status`, `markets`)	Token symbol or supported contract address
`simulate`	flag	No	Return a request-only, no-broadcast preview
`json`	flag	No	Output as JSON

Actions

Action	Description	Example
`status`	Health factor, collateral, debt, and available borrowing	`npx fibx@latest aave status`
`markets`	Browse reserves with APY and supply/borrow totals	`npx fibx@latest aave markets`
`supply`	Deposit assets; ETH input can auto-wrap to WETH	`npx fibx@latest aave supply 1 ETH`
`borrow`	Borrow against collateral; the ETH market returns WETH	`npx fibx@latest aave borrow 50 USDC`
`repay`	Repay debt; ETH input can auto-wrap to WETH	`npx fibx@latest aave repay max ETH`
`withdraw`	Withdraw assets; ETH input can auto-unwrap WETH to ETH	`npx fibx@latest aave withdraw max ETH`

ETH ↔ WETH Auto-Wrap

For the ETH market, supply and repay can wrap ETH to WETH, while withdraw can unwrap WETH to ETH. Borrowing the ETH market returns WETH; the borrowed asset is not auto-unwrapped.

npx fibx@latest aave supply 1 ETH         # Auto-wraps ETH → WETH and supplies
npx fibx@latest aave supply 100 USDC      # Supply ERC-20 directly
npx fibx@latest aave markets              # Browse reserves with APY and supply/borrow totals
npx fibx@latest aave borrow 50 USDC       # Borrow
npx fibx@latest aave repay 50 USDC        # Repay partial USDC debt
npx fibx@latest aave repay max ETH        # Auto-wraps ETH and repays full WETH debt
npx fibx@latest aave withdraw max ETH     # Withdraws WETH and auto-unwraps to ETH
npx fibx@latest aave supply 1 ETH --simulate # Preview the request only

An Aave --simulate result summarizes the normalized request without broadcasting it. It does not perform on-chain validation, simulate the contract call, or estimate gas.

A live supply or repay may submit wrap and approval transactions before the Aave call. An ETH withdraw submits the Aave withdrawal before a separate unwrap transaction; the reported txHash is the Aave withdrawal hash. If a later step fails, earlier transactions remain on-chain. In particular, aave withdraw max ETH unwraps the wallet’s entire WETH balance after the withdrawal, including WETH held before the command.

Health Factor

Before borrowing, always check aave status. The Health Factor indicates liquidation risk:

Above 1.5 — Lower liquidation risk, but not risk-free
Between 1.1 and 1.5 — Liquidation risk warning
Below 1.1 — High liquidation risk, proceed with extreme caution

max is supported only for repay and withdraw; supply max and borrow max are rejected. Use max when fully repaying debt or withdrawing a supplied position to avoid dust residuals.

config — RPC Configuration

View and modify local fibx CLI configuration. Used primarily to set custom RPC URLs when hitting rate limits on public endpoints.

npx fibx@latest config <subcommand> [chain] [url]

Subcommand	Description	Example
`set-rpc`	Set a custom RPC URL for a chain	`npx fibx@latest config set-rpc base https://mainnet.base.org`
`get-rpc`	View the current RPC URL for a chain	`npx fibx@latest config get-rpc base`
`reset-rpc`	Reset one chain or all chains to default	`npx fibx@latest config reset-rpc base`
`list`	List all custom configurations	`npx fibx@latest config list`

Parameter	Type	Required	Description
`chain`	string	Conditional	Required for `set-rpc` and `get-rpc`; optional for `reset-rpc`
`url`	string	Yes (`set-rpc`)	Full HTTP(S) RPC endpoint URL

Configuration is stored in the OS-specific FibX config directory and persists across sessions. Typical paths are ~/.config/fibx-nodejs/config.json on Linux and ~/Library/Preferences/fibx-nodejs/config.json on macOS.

Examples

# Handle rate limit on Base
npx fibx@latest config set-rpc base https://mainnet.base.org

# Check configured RPC
npx fibx@latest config get-rpc base

# Reset Base RPC to default
npx fibx@latest config reset-rpc base

# Reset all custom RPCs
npx fibx@latest config reset-rpc

# List all configurations
npx fibx@latest config list

tx-status — Transaction Status

Check the on-chain status of a transaction and retrieve the block explorer link.

npx fibx@latest tx-status <hash> [--chain <chain>] [--json]

Parameter	Type	Required	Description
`hash`	string	Yes	Transaction hash (`0x...`)
`chain`	string	No	Must match the chain of the original transaction
`json`	flag	No	Output as JSON

Always use the same --chain flag that was used for the original transaction. A Base transaction hash will not be found on Monad.

JSON Output

{
  "status": "success",
  "blockNumber": "12345",
  "gasUsed": "21000",
  "from": "0x...",
  "to": "0x...",
  "txHash": "0x...",
  "explorer": "https://basescan.org/tx/0x...",
  "chain": "base"
}

Error Reference

Common errors across all commands:

Error	Cause	Resolution
`Not authenticated`	No active session	Run `auth setup` (or `auth connect` / `auth login` / `auth import`) first
`POLICY_BLOCKED`	The local signing policy refused the transaction	The rule and limit are named; change them with `policy set` or `policy clear`
Rejected in wallet	The WalletConnect wallet declined the request	Nothing was sent; retry when ready
`Insufficient balance`	Not enough tokens for the operation	Check `balance` and adjust the amount
`Simulation failed`	An RPC estimate or contract preflight rejected the request	Verify parameters and token availability
`No route found`	No liquidity path exists for the token pair	Try a different pair or check the chain
`Slippage exceeded`	Price moved beyond tolerance	Retry or increase slippage with `--slippage`
`Session expired`	Privy session timed out (7 days)	Re-authenticate with `auth login`
`Invalid address`	Recipient address is malformed	Verify the address starts with `0x` and is valid
`Rate limit`	Too many requests in a short period	Retry shortly; set a custom RPC if 429 errors persist

​quote — Price Quotes (No Auth)

​Examples

​auth — Authentication

​auth setup

​auth connect (Your Own Wallet)

​auth import (Private Key)

​auth login / auth verify (Email OTP)

​auth logout

​policy — Signing Policy

​Examples

​status — Session Status

​address — Wallet Address

​wallets — Wallet Details

​portfolio — Cross-Chain Portfolio

​Examples

​balance — Check Balances

​send — Transfer Tokens

​Examples

​trade: Swap Tokens

​Examples

​aave — Aave V3 (Base Only)

​Actions

​ETH ↔ WETH Auto-Wrap

​Health Factor

​config — RPC Configuration

​Examples

​tx-status — Transaction Status

​JSON Output

​Error Reference

quote — Price Quotes (No Auth)

Examples

auth — Authentication

auth setup

auth connect (Your Own Wallet)

auth import (Private Key)

auth login / auth verify (Email OTP)

auth logout

policy — Signing Policy

Examples

status — Session Status

address — Wallet Address

wallets — Wallet Details

portfolio — Cross-Chain Portfolio

Examples

balance — Check Balances

send — Transfer Tokens

Examples

trade: Swap Tokens

Examples

aave — Aave V3 (Base Only)

Actions

ETH ↔ WETH Auto-Wrap

Health Factor

config — RPC Configuration

Examples

tx-status — Transaction Status

JSON Output

Error Reference