@lifi/cli 0.1.1-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LI.FI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# LI.FI CLI
+
+> **Note:** This CLI provides **read-only** tools — it does not sign or broadcast transactions. Quote responses include unsigned `transactionRequest` objects that must be signed and submitted externally using your own wallet.
+
+A TypeScript CLI that wraps the [LI.FI REST API](https://li.quest) to give developers, integrators, and internal teams a scriptable, human-readable interface to cross-chain swap infrastructure.
+
+## Quickstart
+
+```bash
+git clone https://github.com/lifinance/lifi-cli.git
+cd lifi-cli
+npm install && npm run build
+node dist/lifi.cjs chains
+```
+
+Once published to npm:
+
+```bash
+npm install -g @lifi/cli
+lifi chains
+```
+
+No API key required — works immediately with public rate limits. Add a key for higher throughput.
+
+## Commands
+
+### Token Information
+
+```bash
+lifi tokens --chain 1                    # List tokens on Ethereum
+lifi tokens --chain 1 --min-price 100    # Filter by min USD price
+lifi token 1 USDC                        # Get specific token detail
+lifi token 1 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48   # By address
+```
+
+### Chain Information
+
+```bash
+lifi chains                    # List all supported chains
+lifi chains --type EVM         # Filter by chain type
+lifi chain 42161               # Get chain detail by ID
+lifi chain arbitrum            # Get chain detail by name (case-insensitive)
+```
+
+### Quote & Swap
+
+```bash
+# With flags
+lifi quote \
+  --from ethereum --to arbitrum \
+  --from-token USDC --to-token USDC \
+  --amount 1000000000 \
+  --from-address 0xd8dA...
+
+# Interactive mode (prompts for missing flags)
+lifi quote
+```
+
+### Routes
+
+```bash
+lifi routes \
+  --from 1 --to 42161 \
+  --from-token USDC --to-token USDC \
+  --amount 1000000000 \
+  --order CHEAPEST
+```
+
+### Transaction Status
+
+```bash
+lifi status 0xabc123...                  # One-shot status check
+lifi status 0xabc123... --watch          # Poll until complete/failed
+lifi status 0xabc123... --bridge hop     # Speed up lookup with bridge hint
+```
+
+### Connections
+
+```bash
+lifi connections                               # All connections
+lifi connections --from-chain 1 --to-chain 42161  # Specific pair
+```
+
+### Tools (Bridges & DEXes)
+
+```bash
+lifi tools                     # List all bridges and DEXes
+lifi tools --chain 1           # Filter by chain
+```
+
+### Gas
+
+```bash
+lifi gas                       # Gas prices for all chains
+lifi gas 1                     # Detailed gas suggestion for Ethereum
+```
+
+### API Key Management
+
+```bash
+lifi auth show                 # Display masked key
+lifi auth test                 # Validate key against the API
+```
+
+### Health Check
+
+```bash
+lifi health                    # Check API connectivity and latency
+```
+
+## Output Modes
+
+| Mode | Trigger | Behaviour |
+|------|---------|-----------|
+| Human | Default (TTY detected) | Coloured tables, formatted amounts |
+| Machine | `--json` flag or non-TTY pipe | Raw JSON, stable schema, no colour |
+
+```bash
+# Pipe-friendly — auto-detects non-TTY
+lifi chains | jq '.chains[].name'
+
+# Force JSON in terminal
+lifi chains --json
+
+# Disable colour
+lifi chains --no-color
+
+# Verbose errors with stack traces
+lifi quote --from 1 --to 42161 --verbose
+```
+
+## Configuration
+
+All configuration is via environment variables. No config files needed.
+
+```bash
+# LI.FI API key (higher rate limits)
+export LIFI_API_KEY=your_key_here
+```
+
+Without `LIFI_API_KEY`, the CLI uses public rate limits (200 req/2hr). With a key, you get 200 req/min.
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Invalid arguments / usage |
+| 3 | Authentication error |
+| 4 | API error (rate limit, server error) |
+| 5 | Network error (unreachable) |
+
+## Common Chain IDs
+
+| Chain | ID | Native Token |
+|-------|-----|--------------|
+| Ethereum | 1 | ETH |
+| Polygon | 137 | MATIC |
+| Arbitrum | 42161 | ETH |
+| Optimism | 10 | ETH |
+| BSC | 56 | BNB |
+| Avalanche | 43114 | AVAX |
+| Base | 8453 | ETH |
+
+## Example Workflow: Cross-Chain Swap
+
+```bash
+# 1. Find chain IDs
+lifi chains --type EVM
+
+# 2. Look up token addresses
+lifi token 1 USDC
+
+# 3. Get best quote
+lifi quote --from 1 --to 8453 --from-token USDC --to-token USDC --amount 1000000000 --from-address 0xYOUR_ADDRESS
+
+# 4. (External) Approve tokens and sign transactionRequest with your wallet
+
+# 5. Track progress
+lifi status 0xTX_HASH --watch
+```
+
+## Installation
+
+### npm (primary)
+
+```bash
+npm install -g @lifi/cli
+```
+
+### npx (no install)
+
+```bash
+npx @lifi/cli chains
+```
+
+## Development
+
+```bash
+git clone https://github.com/lifinance/lifi-cli.git
+cd lifi-cli
+npm install
+npm run build
+node dist/lifi.cjs --help
+```
+
+### Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm run build` | Build with tsup |
+| `npm run dev` | Watch mode |
+| `npm test` | Run tests (vitest) |
+| `npm run typecheck` | Type check (tsc --noEmit) |
+
+## License
+
+MIT

package/dist/lifi.js

@@ -0,0 +1,622 @@
+#!/usr/bin/env node
+import { Command, Option } from "commander";
+import Table from "cli-table3";
+import axios from "axios";
+import ora from "ora";
+import { input } from "@inquirer/prompts";
+//#region src/core/constants.ts
+const API_BASE_URL = "https://li.quest/v1";
+const INTEGRATOR_ID = "lifi-cli";
+const AUTH_HEADER = "X-LiFi-Api-Key";
+let ExitCode = /* @__PURE__ */ function(ExitCode) {
+	ExitCode[ExitCode["Success"] = 0] = "Success";
+	ExitCode[ExitCode["General"] = 1] = "General";
+	ExitCode[ExitCode["InvalidArgs"] = 2] = "InvalidArgs";
+	ExitCode[ExitCode["AuthError"] = 3] = "AuthError";
+	ExitCode[ExitCode["ApiError"] = 4] = "ApiError";
+	ExitCode[ExitCode["NetworkError"] = 5] = "NetworkError";
+	return ExitCode;
+}({});
+//#endregion
+//#region src/core/config.ts
+function getApiKey() {
+	return process.env["LIFI_API_KEY"] || void 0;
+}
+function maskKey(key) {
+	if (!key) return "";
+	if (key.length <= 6) return "***";
+	return `${key.slice(0, 3)}...${key.slice(-3)}`;
+}
+//#endregion
+//#region src/core/errors.ts
+var CliError = class extends Error {
+	exitCode;
+	hint;
+	constructor(message, exitCode = ExitCode.General, hint) {
+		super(message);
+		this.name = "CliError";
+		this.exitCode = exitCode;
+		this.hint = hint;
+	}
+};
+function formatError(error) {
+	if (error instanceof CliError) {
+		const lines = [`\u2717 Error: ${error.message}`];
+		if (error.hint) lines.push("", `  ${error.hint}`);
+		return lines.join("\n");
+	}
+	if (error instanceof Error) return `\u2717 Error: ${error.message}`;
+	return "✗ Error: An unexpected error occurred";
+}
+function mapAxiosError(error) {
+	const response = error.response;
+	if (response) {
+		const msg = response.data?.message || `HTTP ${response.status}`;
+		if (response.status === 401 || response.status === 403) return new CliError(msg, ExitCode.AuthError, "Check your API key with: lifi auth test");
+		if (response.status === 429) return new CliError(msg, ExitCode.ApiError, "Rate limited. Set an API key with: lifi auth set <key>");
+		if (response.status >= 400) return new CliError(msg, ExitCode.ApiError);
+	}
+	if (error.code === "ECONNREFUSED" || error.code === "ECONNABORTED" || error.code === "ETIMEDOUT") return new CliError(error.message || "Network error", ExitCode.NetworkError, "Check your internet connection and try again.");
+	return new CliError(error.message || "An unexpected error occurred", ExitCode.General);
+}
+function handleError(error) {
+	const verbose = process.env["LIFI_VERBOSE"] === "1";
+	if (error instanceof CliError) {
+		console.error(formatError(error));
+		if (verbose && error.stack) console.error(`\n${error.stack}`);
+		process.exit(error.exitCode);
+	}
+	console.error(formatError(error));
+	if (verbose && error instanceof Error && error.stack) console.error(`\n${error.stack}`);
+	process.exit(ExitCode.General);
+}
+//#endregion
+//#region src/core/formatter.ts
+function formatAmount(amount, decimals) {
+	if (amount === "0") return "0";
+	const padded = amount.padStart(decimals + 1, "0");
+	const intPart = padded.slice(0, padded.length - decimals) || "0";
+	const fracPart = padded.slice(padded.length - decimals).replace(/0+$/, "");
+	if (!fracPart) return intPart;
+	return `${intPart}.${fracPart}`;
+}
+function formatTable(headers, rows) {
+	const table = new Table({ head: headers });
+	for (const row of rows) table.push(row);
+	return table.toString();
+}
+function isJsonMode(options) {
+	if (options.json === true) return true;
+	return !process.stdout.isTTY;
+}
+function jsonOutput(data) {
+	return JSON.stringify(data, null, 2);
+}
+//#endregion
+//#region src/core/http-client.ts
+function createApiClient() {
+	const client = axios.create({
+		baseURL: API_BASE_URL,
+		timeout: 3e4
+	});
+	client.interceptors.request.use((config) => {
+		const apiKey = getApiKey();
+		if (apiKey) config.headers[AUTH_HEADER] = apiKey;
+		config.params = config.params || {};
+		config.params.integrator = INTEGRATOR_ID;
+		return config;
+	});
+	client.interceptors.response.use((response) => response, (error) => {
+		throw mapAxiosError(error);
+	});
+	return client;
+}
+const api = createApiClient();
+//#endregion
+//#region src/core/interactive.ts
+async function withSpinner(message, fn) {
+	const spinner = ora(message).start();
+	try {
+		const result = await fn();
+		spinner.succeed();
+		return result;
+	} catch (error) {
+		spinner.fail();
+		throw error;
+	}
+}
+//#endregion
+//#region src/commands/auth.ts
+function registerAuthCommand(program) {
+	const auth = program.command("auth").description("Manage API key (set via LIFI_API_KEY env var)");
+	auth.command("show").description("Display current API key (masked) and its source").action(async (_options, command) => {
+		const opts = command.optsWithGlobals();
+		try {
+			const key = getApiKey();
+			if (!key) {
+				console.log("No API key configured.");
+				console.log("Set one with: export LIFI_API_KEY=<your-key>");
+				return;
+			}
+			if (isJsonMode(opts)) console.log(jsonOutput({ key: maskKey(key) }));
+			else {
+				console.log(`API Key: ${maskKey(key)}`);
+				console.log("Source:  LIFI_API_KEY env var");
+			}
+		} catch (error) {
+			handleError(error);
+		}
+	});
+	auth.command("test").description("Validate API key against the LI.FI API").action(async (_options, command) => {
+		const opts = command.optsWithGlobals();
+		try {
+			const { data } = await withSpinner("Testing API key...", () => api.get("/keys/test"));
+			if (isJsonMode(opts)) console.log(jsonOutput(data));
+			else console.log("API key is valid.");
+		} catch (error) {
+			handleError(error);
+		}
+	});
+}
+//#endregion
+//#region src/commands/chains.ts
+function registerChainsCommand(program) {
+	program.command("chains").description("List all supported blockchain networks").addOption(new Option("--type <type>", "Filter by chain type").choices(["EVM", "SVM"])).addHelpText("after", `
+Examples:
+  $ lifi chains                    # All chains
+  $ lifi chains --type EVM         # Only EVM chains
+  $ lifi chains --json | jq '.chains[] | {id, name}'`).action(async (options, command) => {
+		const opts = command.optsWithGlobals();
+		try {
+			const { data } = await withSpinner("Fetching chains...", () => api.get("/chains"));
+			let chains = data.chains;
+			if (options.type) {
+				const type = options.type;
+				chains = chains.filter((c) => c.chainType === type);
+			}
+			if (isJsonMode(opts)) console.log(jsonOutput({ chains }));
+			else {
+				const rows = chains.map((c) => [
+					String(c.id),
+					c.name,
+					c.chainType,
+					c.nativeToken.symbol
+				]);
+				console.log(formatTable([
+					"ID",
+					"Name",
+					"Type",
+					"Native Token"
+				], rows));
+				console.log("\n  Next: lifi chain <id>  or  lifi tokens --chain <id>");
+			}
+		} catch (error) {
+			handleError(error);
+		}
+	});
+	program.command("chain <idOrName>").description("Look up a single chain by numeric ID or name (case-insensitive)").addHelpText("after", `
+Examples:
+  $ lifi chain 42161             # By ID
+  $ lifi chain arbitrum          # By name
+  $ lifi chain ethereum --json   # JSON output`).action(async (idOrName, _options, command) => {
+		const opts = command.optsWithGlobals();
+		try {
+			const { data } = await withSpinner("Fetching chains...", () => api.get("/chains"));
+			const allChains = data.chains;
+			const chain = /^\d+$/.test(idOrName) ? allChains.find((c) => c.id === Number(idOrName)) : allChains.find((c) => c.name.toLowerCase() === idOrName.toLowerCase());
+			if (!chain) {
+				handleError(new CliError(`Chain "${idOrName}" not found`, ExitCode.InvalidArgs, "Run: lifi chains  to see all available chains"));
+				return;
+			}
+			if (isJsonMode(opts)) console.log(jsonOutput(chain));
+			else {
+				const rows = [
+					["ID", String(chain.id)],
+					["Name", chain.name],
+					["Key", chain.key],
+					["Type", chain.chainType],
+					["Native Token", chain.nativeToken.symbol],
+					["Mainnet", chain.mainnet ? "Yes" : "No"]
+				];
+				console.log(formatTable(["Field", "Value"], rows));
+			}
+		} catch (error) {
+			handleError(error);
+		}
+	});
+}
+//#endregion
+//#region src/commands/connections.ts
+function registerConnectionsCommand(program) {
+	program.command("connections").description("Check which token transfer routes exist between chains").option("--from-chain <chainId>", "Source chain ID (e.g. 1)").option("--to-chain <chainId>", "Destination chain ID (e.g. 42161)").option("--from-token <token>", "Source token address (e.g. 0xa0b8...)").option("--to-token <token>", "Destination token address").addHelpText("after", `
+Examples:
+  $ lifi connections --from-chain 1 --to-chain 42161
+  $ lifi connections --from-chain 1 --to-chain 8453 --from-token USDC --json`).action(async (options, command) => {
+		const opts = command.optsWithGlobals();
+		try {
+			const params = {};
+			if (options["fromChain"]) params["fromChain"] = options["fromChain"];
+			if (options["toChain"]) params["toChain"] = options["toChain"];
+			if (options["fromToken"]) params["fromToken"] = options["fromToken"];
+			if (options["toToken"]) params["toToken"] = options["toToken"];
+			const { data } = await withSpinner("Fetching connections...", () => api.get("/connections", { params }));
+			if (isJsonMode(opts)) console.log(jsonOutput(data));
+			else {
+				const connections = data.connections ?? [];
+				if (connections.length === 0) {
+					console.log("No connections found for the given filters.");
+					return;
+				}
+				const rows = connections.slice(0, 50).map((c) => [
+					String(c.fromChainId),
+					String(c.toChainId),
+					c.fromToken?.symbol ?? "-",
+					c.toToken?.symbol ?? "-"
+				]);
+				console.log(formatTable([
+					"From Chain",
+					"To Chain",
+					"From Token",
+					"To Token"
+				], rows));
+				if (connections.length > 50) console.log(`\n  Showing 50 of ${connections.length} connections. Use --json for full list.`);
+			}
+		} catch (error) {
+			handleError(error);
+		}
+	});
+}
+//#endregion
+//#region src/commands/gas.ts
+function registerGasCommand(program) {
+	program.command("gas [chain]").description("Get gas prices for all chains, or detailed suggestion for one chain").addHelpText("after", `
+Examples:
+  $ lifi gas                       # All chains gas prices
+  $ lifi gas 1                     # Ethereum gas suggestion (recommended cost in USD)
+  $ lifi gas ethereum --json`).action(async (chain, _options, command) => {
+		const opts = command.optsWithGlobals();
+		try {
+			if (chain) {
+				const { data } = await withSpinner(`Fetching gas for chain ${chain}...`, () => api.get(`/gas/suggestion/${chain}`));
+				if (isJsonMode(opts)) console.log(jsonOutput(data));
+				else {
+					const rec = data.recommended;
+					const rows = [
+						["Token", rec.token?.symbol || "N/A"],
+						["Recommended cost", rec.amountUsd ? `$${rec.amountUsd}` : "N/A"],
+						["Available", data.available ? "Yes" : "No"]
+					];
+					console.log(formatTable(["Field", "Value"], rows));
+				}
+			} else {
+				const { data } = await withSpinner("Fetching gas prices...", () => api.get("/gas/prices"));
+				if (isJsonMode(opts)) console.log(jsonOutput(data));
+				else {
+					const rows = Object.keys(data).slice(0, 30).map((id) => {
+						const g = data[id];
+						return [
+							id,
+							String(g?.standard ?? "-"),
+							String(g?.fast ?? "-"),
+							String(g?.fastest ?? "-")
+						];
+					});
+					console.log(formatTable([
+						"Chain ID",
+						"Standard (gwei)",
+						"Fast",
+						"Fastest"
+					], rows));
+					if (Object.keys(data).length > 30) console.log(`\n  Showing 30 of ${Object.keys(data).length} chains. Use --json for full list.`);
+				}
+			}
+		} catch (error) {
+			handleError(error);
+		}
+	});
+}
+//#endregion
+//#region src/commands/health.ts
+function registerHealthCommand(program) {
+	program.command("health").description("Check LI.FI API connectivity, latency, and available chains").action(async (_options, command) => {
+		const opts = command.optsWithGlobals();
+		try {
+			const start = Date.now();
+			const { data } = await withSpinner("Checking API health...", () => api.get("/chains"));
+			const latency = Date.now() - start;
+			const chains = data.chains || data;
+			const result = {
+				status: "ok",
+				latencyMs: latency,
+				chainsAvailable: Array.isArray(chains) ? chains.length : 0
+			};
+			if (isJsonMode(opts)) console.log(jsonOutput(result));
+			else console.log(`LI.FI API: ok (${latency}ms, ${result.chainsAvailable} chains available)`);
+		} catch (error) {
+			handleError(error);
+		}
+	});
+}
+//#endregion
+//#region src/commands/quote.ts
+async function promptIfMissing(value, label) {
+	if (value) return value;
+	if (process.env["LIFI_NO_INPUT"] === "1") throw new CliError(`Missing required option: ${label}`, ExitCode.InvalidArgs, "Pass all required flags when using --no-input");
+	return input({ message: `${label}:` });
+}
+function registerQuoteCommand(program) {
+	program.command("quote").description("Get the best route for a cross-chain or same-chain swap").option("--from <chain>", "Source chain name or ID (e.g. ethereum, 1)").option("--to <chain>", "Destination chain name or ID (e.g. arbitrum, 42161)").option("--from-token <token>", "Token to send — symbol or address (e.g. USDC, 0xa0b8...)").option("--to-token <token>", "Token to receive — symbol or address").option("--amount <amount>", "Amount in smallest unit (e.g. 1000000 for 1 USDC)").option("--from-address <address>", "Sender wallet address (0x...)").option("--slippage <slippage>", "Max slippage as decimal (e.g. 0.03 for 3%)", "0.03").addOption(new Option("--order <order>", "Route preference").choices([
+		"CHEAPEST",
+		"FASTEST",
+		"SAFEST",
+		"RECOMMENDED"
+	])).option("--allow-bridges <keys>", "Only use these bridges (comma-separated keys from lifi tools)").option("--allow-exchanges <keys>", "Only use these exchanges (comma-separated keys from lifi tools)").addHelpText("after", `
+Examples:
+  $ lifi quote --from ethereum --to arbitrum --from-token USDC --to-token USDC --amount 1000000 --from-address 0xd8dA...
+  $ lifi quote                          # Interactive mode — prompts for each field
+  $ lifi quote --from 1 --to 8453 --from-token USDC --to-token USDC --amount 1000000000 --json`).action(async (options, command) => {
+		const opts = command.optsWithGlobals();
+		try {
+			const params = {
+				fromChain: await promptIfMissing(options.from, "--from (source chain)"),
+				toChain: await promptIfMissing(options.to, "--to (destination chain)"),
+				fromToken: await promptIfMissing(options.fromToken, "--from-token"),
+				toToken: await promptIfMissing(options.toToken, "--to-token"),
+				fromAmount: await promptIfMissing(options.amount, "--amount"),
+				fromAddress: await promptIfMissing(options.fromAddress, "--from-address"),
+				slippage: options.slippage
+			};
+			if (options["order"]) params["order"] = options["order"];
+			if (options["allowBridges"]) params["allowBridges"] = options["allowBridges"];
+			if (options["allowExchanges"]) params["allowExchanges"] = options["allowExchanges"];
+			const { data } = await withSpinner("Fetching quote...", () => api.get("/quote", { params }));
+			if (isJsonMode(opts)) console.log(jsonOutput(data));
+			else {
+				const estimate = data.estimate;
+				const rows = [
+					["You receive", `${formatAmount(estimate?.toAmount ?? "0", estimate?.toAmountDecimals ?? 18)} ${data.action?.toToken?.symbol ?? ""}`],
+					["Bridge", data.toolDetails?.name ?? data.tool ?? "N/A"],
+					["Est. time", estimate?.executionDuration ? `~${Math.round(estimate.executionDuration / 60)} min` : "N/A"],
+					["Gas cost", estimate?.gasCosts?.[0]?.amountUSD ? `~$${estimate.gasCosts[0].amountUSD}` : "N/A"],
+					["Slippage", `${Number(options["slippage"]) * 100}%`]
+				];
+				console.log(formatTable(["", ""], rows));
+				console.log("\n  Sign the transactionRequest with your wallet to execute.");
+				console.log("  Then track with: lifi status <txHash> --watch");
+				console.log("  Use --json to get the full transactionRequest object.");
+			}
+		} catch (error) {
+			handleError(error);
+		}
+	});
+}
+//#endregion
+//#region src/commands/routes.ts
+function registerRoutesCommand(program) {
+	program.command("routes").description("Get multiple route options for comparison (unlike quote, returns several alternatives)").option("--from <chain>", "Source chain name or ID (e.g. ethereum, 1)").option("--to <chain>", "Destination chain name or ID (e.g. arbitrum, 42161)").option("--from-token <token>", "Token to send — symbol or address (e.g. USDC)").option("--to-token <token>", "Token to receive — symbol or address").option("--amount <amount>", "Amount in smallest unit (e.g. 1000000 for 1 USDC)").option("--from-address <address>", "Sender wallet address (0x...)").addOption(new Option("--order <order>", "Sort preference").choices([
+		"CHEAPEST",
+		"FASTEST",
+		"SAFEST",
+		"RECOMMENDED"
+	])).addHelpText("after", `
+Examples:
+  $ lifi routes --from 1 --to 42161 --from-token USDC --to-token USDC --amount 1000000000 --json
+  $ lifi routes --from ethereum --to base --from-token USDC --to-token USDC --amount 1000000 --order CHEAPEST`).action(async (options, command) => {
+		const opts = command.optsWithGlobals();
+		try {
+			const body = {
+				fromChainId: options.from,
+				toChainId: options.to,
+				fromTokenAddress: options.fromToken,
+				toTokenAddress: options.toToken,
+				fromAmount: options.amount,
+				fromAddress: options.fromAddress || "0x0000000000000000000000000000000000000000",
+				options: options.order ? { order: options.order } : void 0
+			};
+			const { data } = await withSpinner("Fetching routes...", () => api.post("/advanced/routes", body));
+			if (isJsonMode(opts)) console.log(jsonOutput(data));
+			else {
+				const rows = (data.routes ?? []).map((r, i) => [
+					String(i + 1),
+					r.steps.map((s) => s.tool).join(" → "),
+					r.toAmountUSD ? `$${r.toAmountUSD}` : "N/A",
+					r.gasCostUSD ? `$${r.gasCostUSD}` : "N/A"
+				]);
+				console.log(formatTable([
+					"#",
+					"Steps",
+					"You Receive (USD)",
+					"Gas Cost"
+				], rows));
+			}
+		} catch (error) {
+			handleError(error);
+		}
+	});
+}
+//#endregion
+//#region src/types/index.ts
+const TERMINAL_STATUSES = new Set([
+	"DONE",
+	"FAILED",
+	"CANCELLED",
+	"NOT_FOUND",
+	"INVALID"
+]);
+//#endregion
+//#region src/commands/status.ts
+const MAX_POLL_ATTEMPTS = 60;
+function registerStatusCommand(program) {
+	program.command("status <txHash>").description("Check cross-chain transfer status by transaction hash").option("--bridge <bridge>", "Bridge key hint to speed up lookup (e.g. stargate, hop, across)").option("--from-chain <chainId>", "Source chain ID (e.g. 1)").option("--to-chain <chainId>", "Destination chain ID (e.g. 42161)").option("--watch", "Poll every 5s until DONE or FAILED (max 5 min)").addHelpText("after", `
+Examples:
+  $ lifi status 0xabc123def456...
+  $ lifi status 0xabc123... --watch
+  $ lifi status 0xabc123... --bridge stargate --from-chain 1 --to-chain 42161`).action(async (txHash, options, command) => {
+		const opts = command.optsWithGlobals();
+		try {
+			const params = { txHash };
+			if (options["bridge"]) params["bridge"] = options["bridge"];
+			if (options["fromChain"]) params["fromChain"] = options["fromChain"];
+			if (options["toChain"]) params["toChain"] = options["toChain"];
+			const fetchStatus = () => api.get("/status", { params });
+			if (options.watch) {
+				let lastData = null;
+				let status = "PENDING";
+				for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt++) {
+					const data = (await withSpinner(`Status: ${status} (${attempt + 1}/${MAX_POLL_ATTEMPTS})`, fetchStatus)).data;
+					status = data.status ?? "UNKNOWN";
+					lastData = data;
+					if (!isJsonMode(opts)) console.log(`Status: ${status} | Substatus: ${data.substatus ?? "N/A"}`);
+					if (TERMINAL_STATUSES.has(status)) break;
+					await new Promise((r) => setTimeout(r, 5e3));
+				}
+				if (isJsonMode(opts)) console.log(jsonOutput(lastData));
+				if (!TERMINAL_STATUSES.has(status)) throw new CliError(`Polling timed out after ${MAX_POLL_ATTEMPTS * 5}s — last status: ${status}`, ExitCode.General, `Try again with: lifi status ${txHash} --watch`);
+			} else {
+				const { data } = await withSpinner("Checking status...", fetchStatus);
+				if (isJsonMode(opts)) console.log(jsonOutput(data));
+				else {
+					const rows = [
+						["Status", data.status ?? "N/A"],
+						["Substatus", data.substatus ?? "N/A"],
+						["Bridge", data.tool ?? "N/A"]
+					];
+					console.log(formatTable(["Field", "Value"], rows));
+				}
+			}
+		} catch (error) {
+			handleError(error);
+		}
+	});
+}
+//#endregion
+//#region src/commands/tokens.ts
+function registerTokensCommand(program) {
+	program.command("tokens").description("List supported tokens across chains").option("--chain <chainId>", "Filter by chain ID (e.g. 1 for Ethereum, 137 for Polygon)").option("--min-price <price>", "Only show tokens with USD price >= this value").addHelpText("after", `
+Examples:
+  $ lifi tokens --chain 1                     # All Ethereum tokens
+  $ lifi tokens --chain 1 --min-price 100     # Tokens worth $100+
+  $ lifi tokens --chain 1 --json | jq '.tokens["1"][] | .symbol'`).action(async (options, command) => {
+		const opts = command.optsWithGlobals();
+		try {
+			const params = {};
+			if (options["chain"]) params["chains"] = options["chain"];
+			const { data } = await withSpinner("Fetching tokens...", () => api.get("/tokens", { params }));
+			if (options["minPrice"]) {
+				const minPrice = Number(options["minPrice"]);
+				const tokens = data.tokens;
+				for (const chainId of Object.keys(tokens)) {
+					const chainTokens = tokens[chainId];
+					if (chainTokens) tokens[chainId] = chainTokens.filter((t) => Number(t.priceUSD ?? 0) >= minPrice);
+				}
+			}
+			if (isJsonMode(opts)) console.log(jsonOutput(data));
+			else {
+				const tokens = data.tokens;
+				const allTokens = [];
+				for (const chainId of Object.keys(tokens)) {
+					const chainTokens = tokens[chainId];
+					if (chainTokens) allTokens.push(...chainTokens);
+				}
+				const rows = allTokens.slice(0, 50).map((t) => [
+					t.symbol,
+					t.name,
+					`${t.address.slice(0, 10)}...`,
+					String(t.decimals),
+					String(t.chainId)
+				]);
+				console.log(formatTable([
+					"Symbol",
+					"Name",
+					"Address",
+					"Decimals",
+					"Chain"
+				], rows));
+				if (allTokens.length > 50) console.log(`\n  Showing 50 of ${allTokens.length} tokens. Use --json for full list.`);
+				console.log("\n  Next: lifi token <chain> <symbol>  or  lifi quote --from-token <symbol>");
+			}
+		} catch (error) {
+			handleError(error);
+		}
+	});
+	program.command("token <chain> <symbol>").description("Get details for a specific token by chain and symbol or address").addHelpText("after", `
+Examples:
+  $ lifi token 1 USDC                                              # By symbol
+  $ lifi token ethereum USDC                                       # By chain name
+  $ lifi token 1 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48       # By address`).action(async (chain, symbol, _options, command) => {
+		const opts = command.optsWithGlobals();
+		try {
+			const { data } = await withSpinner("Fetching token...", () => api.get("/token", { params: {
+				chain,
+				token: symbol
+			} }));
+			if (isJsonMode(opts)) console.log(jsonOutput(data));
+			else {
+				const rows = [
+					["Symbol", data.symbol],
+					["Name", data.name],
+					["Address", data.address],
+					["Decimals", String(data.decimals)],
+					["Chain ID", String(data.chainId)],
+					["Price (USD)", data.priceUSD ?? "N/A"]
+				];
+				console.log(formatTable(["Field", "Value"], rows));
+			}
+		} catch (error) {
+			handleError(error);
+		}
+	});
+}
+//#endregion
+//#region src/commands/tools.ts
+function registerToolsCommand(program) {
+	program.command("tools").description("List available bridges and DEX aggregators — use keys in quote --allow-bridges/--allow-exchanges").option("--chain <chainId>", "Filter by chain ID (e.g. 1)").addHelpText("after", `
+Examples:
+  $ lifi tools
+  $ lifi tools --json | jq '.bridges[] | .key'`).action(async (options, command) => {
+		const opts = command.optsWithGlobals();
+		try {
+			const params = {};
+			if (options["chain"]) params["chains"] = options["chain"];
+			const { data } = await withSpinner("Fetching tools...", () => api.get("/tools", { params }));
+			if (isJsonMode(opts)) console.log(jsonOutput(data));
+			else {
+				console.log("\nBridges:");
+				const bridgeRows = data.bridges.map((b) => [b.key, b.name]);
+				console.log(formatTable(["Key", "Name"], bridgeRows));
+				console.log("\nExchanges:");
+				const exchangeRows = data.exchanges.map((e) => [e.key, e.name]);
+				console.log(formatTable(["Key", "Name"], exchangeRows));
+				console.log("\n  Use keys with: lifi quote --allow-bridges <key> --allow-exchanges <key>");
+			}
+		} catch (error) {
+			handleError(error);
+		}
+	});
+}
+//#endregion
+//#region src/bin/lifi.ts
+function createProgram() {
+	const program = new Command();
+	program.name("lifi").description("CLI for the LI.FI cross-chain bridge & DEX aggregation API").version("0.1.0").option("--json", "Output raw JSON instead of formatted tables").option("--no-color", "Disable colored output").option("--no-input", "Disable interactive prompts (for scripting)").option("--verbose", "Show verbose output including full API responses").addHelpText("after", "\nDocs: https://docs.li.fi/api-reference/introduction\nRepo: https://github.com/lifinance/lifi-cli");
+	program.hook("preAction", (thisCommand) => {
+		const opts = thisCommand.opts();
+		if (opts["color"] === false) process.env["NO_COLOR"] = "1";
+		if (opts["verbose"]) process.env["LIFI_VERBOSE"] = "1";
+		if (opts["input"] === false) process.env["LIFI_NO_INPUT"] = "1";
+	});
+	registerAuthCommand(program);
+	registerChainsCommand(program);
+	registerTokensCommand(program);
+	registerQuoteCommand(program);
+	registerRoutesCommand(program);
+	registerStatusCommand(program);
+	registerConnectionsCommand(program);
+	registerToolsCommand(program);
+	registerGasCommand(program);
+	registerHealthCommand(program);
+	return program;
+}
+if (process.env["VITEST"] === void 0) createProgram().parseAsync(process.argv).catch(handleError);
+//#endregion
+export { createProgram };

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@lifi/cli",
+  "version": "0.1.1-alpha.1",
+  "description": "CLI for the LI.FI cross-chain bridge & DEX aggregation API",
+  "homepage": "https://github.com/lifinance/lifi-cli",
+  "bugs": {
+    "url": "https://github.com/lifinance/lifi-cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lifinance/lifi-cli.git"
+  },
+  "license": "MIT",
+  "author": "LI.FI <github@li.finance>",
+  "keywords": [
+    "lifi",
+    "lifinance",
+    "cli",
+    "bridge",
+    "dex",
+    "cross-chain",
+    "aggregator",
+    "swap"
+  ],
+  "type": "module",
+  "bin": {
+    "lifi": "./dist/lifi.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.0.0",
+    "axios": "^1.7.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^12.1.0",
+    "ora": "^8.1.0"
+  },
+  "lint-staged": {
+    "src/**/*.{ts,tsx}": [
+      "biome check --no-errors-on-unmatched"
+    ]
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.11",
+    "@types/node": "^22.0.0",
+    "commit-and-tag-version": "^12.5.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "tsdown": "^0.21.8",
+    "typescript": "~5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "start": "node dist/lifi.js",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "format": "biome format --write src/",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist",
+    "release": "commit-and-tag-version -a -s",
+    "release:alpha": "commit-and-tag-version -a -s --prerelease alpha",
+    "release:beta": "commit-and-tag-version -a -s --prerelease beta"
+  }
+}