perp-cli 0.9.8 → 0.12.0

package/dist/commands/alerts.js

@@ -269,7 +269,9 @@ export function registerAlertCommands(program, isJson) {
                 "--cooldown", String(cooldownMin),
             ].join(" ");
             // Pass through env vars for keys
-            const envKeys = ["LIGHTER_PRIVATE_KEY", "LIGHTER_API_KEY", "LIGHTER_ACCOUNT_INDEX", "HL_PRIVATE_KEY", "PACIFICA_PRIVATE_KEY", "PRIVATE_KEY"];
+            // L2 agent key + indices now live in ~/.perp keystore + settings.agents (SSOT Rule #3),
+            // not env. Only Tier 3 master PKs need passthrough.
+            const envKeys = ["LIGHTER_PRIVATE_KEY", "HL_PRIVATE_KEY", "PACIFICA_PRIVATE_KEY", "PRIVATE_KEY"];
             const envStr = envKeys.filter(k => process.env[k]).map(k => `${k}='${process.env[k]}'`).join(" ");
             const cmd = `${envStr} ${nodeCmd} ${cliPath} ${args}`;
             execSync(`tmux new-session -d -s ${session} '${cmd.replace(/'/g, "'\\''")}'`);

package/dist/commands/arb/index.js

@@ -1,5 +1,5 @@
 import chalk from "chalk";
-import { makeTable, formatUsd, formatPnl, printJson, jsonOk } from "../../utils.js";
+import { makeTable, formatUsd, formatPnl, printJson, jsonOk, logSettledRejections } from "../../utils.js";
 import { SPOT_PERP_TOKEN_MAP } from "../../exchanges/index.js";
 import { readExecutionLog, logExecution } from "../../execution-log.js";
 import { toHourlyRate, computeAnnualSpread } from "../../funding.js";
@@ -26,13 +26,22 @@ function formatDuration(ms) {
 }
 async function fetchFundingRatesMap() {
     const rateMap = new Map();
-    const [pacAssets, hlAssets, ltDetails, ltFunding, asterPremiums] = await Promise.all([
+    // SSOT rule #2: each DEX is independent. allSettled keeps the comparison
+    // alive when one DEX errors out, while rejection reasons get logged to
+    // stderr (explicit failure, never silent .catch(() => [])).
+    const settled = await Promise.allSettled([
         fetchPacificaPrices(),
         fetchHyperliquidMeta(),
         fetchLighterOrderBookDetails(),
         fetchLighterFundingRates(),
-        fetch("https://fapi.asterdex.com/fapi/v1/premiumIndex").then(r => r.json()).catch(() => []),
+        fetch("https://fapi.asterdex.com/fapi/v1/premiumIndex").then(r => r.json()),
     ]);
+    logSettledRejections(settled, ["pacifica", "hyperliquid", "lighter:orderbook", "lighter:funding", "aster:premiumIndex"], "arb");
+    const pacAssets = settled[0].status === "fulfilled" ? settled[0].value : [];
+    const hlAssets = settled[1].status === "fulfilled" ? settled[1].value : [];
+    const ltDetails = settled[2].status === "fulfilled" ? settled[2].value : [];
+    const ltFunding = settled[3].status === "fulfilled" ? settled[3].value : [];
+    const asterPremiums = settled[4].status === "fulfilled" ? settled[4].value : [];
     const addRate = (sym, exchange, rate, markPrice) => {
         if (!sym)
             return;
@@ -45,19 +54,40 @@ async function fetchFundingRatesMap() {
     for (const h of hlAssets)
         addRate(h.symbol, "hyperliquid", h.funding, h.markPx);
     // Lighter: join details + funding by marketId
+    // SSOT rule #2: skip rows whose mark price cannot be resolved (no 0 fallback).
+    // Prefer fr.markPrice; fall back to orderBook last-trade as documented
+    // price-source preference (NOT error fallback).
     const ltPriceMap = new Map(ltDetails.map(d => [d.marketId, d.lastTradePrice]));
     const ltSymMap = new Map(ltDetails.map(d => [d.marketId, d.symbol]));
     for (const fr of ltFunding) {
         const sym = fr.symbol || ltSymMap.get(fr.marketId) || "";
-        const mp = fr.markPrice || ltPriceMap.get(fr.marketId) || 0;
+        if (!sym)
+            continue;
+        const directMark = fr.markPrice;
+        const fallbackMark = ltPriceMap.get(fr.marketId);
+        let mp;
+        if (directMark !== null && Number.isFinite(directMark) && directMark > 0) {
+            mp = directMark;
+        }
+        else if (fallbackMark !== undefined && Number.isFinite(fallbackMark) && fallbackMark > 0) {
+            mp = fallbackMark;
+        }
+        if (mp === undefined || !Number.isFinite(fr.rate))
+            continue;
         addRate(sym, "lighter", fr.rate, mp);
     }
     // Aster: premiumIndex
-    for (const p of asterPremiums ?? []) {
+    // SSOT rule #2: skip rows missing markPrice / lastFundingRate instead of
+    // 0-coercing — a 0 markPrice would corrupt downstream sizing.
+    for (const p of asterPremiums) {
         const rawSym = String(p.symbol ?? "");
         if (!rawSym.endsWith("USDT"))
             continue;
-        addRate(rawSym.replace(/USDT$/, ""), "aster", Number(p.lastFundingRate ?? 0), Number(p.markPrice ?? 0));
+        const fundingRate = Number(p.lastFundingRate);
+        const markPrice = Number(p.markPrice);
+        if (!Number.isFinite(fundingRate) || !Number.isFinite(markPrice) || markPrice <= 0)
+            continue;
+        addRate(rawSym.replace(/USDT$/, ""), "aster", fundingRate, markPrice);
     }
     return rateMap;
 }
@@ -1428,7 +1458,7 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
             console.log(chalk.yellow("\n  [DRY RUN] No transfers executed.\n"));
         }
         else {
-            console.log(chalk.yellow("\n  To execute, use: perp rebalance execute --auto-bridge\n"));
+            console.log(chalk.yellow("\n  To execute, use: perp funds rebalance execute --auto-bridge\n"));
         }
     });
     // ── printFundingEarned helper (used by arb status --funding) ──

package/dist/commands/arb-auto.js

@@ -1,5 +1,5 @@
 import chalk from "chalk";
-import { formatUsd, printJson, jsonOk, makeTable } from "../utils.js";
+import { formatUsd, printJson, jsonOk, makeTable, logSettledRejections } from "../utils.js";
 import { computeExecutableSize } from "../liquidity.js";
 import { computeMatchedSize, computeSpotPerpMatchedSize } from "../arb/index.js";
 import { computeAnnualSpread, toHourlyRate } from "../funding.js";
@@ -105,17 +105,30 @@ export function isSpreadReversed(longExchange, shortExchange, snapshot) {
     return longHourly > shortHourly;
 }
 async function fetchFundingSpreads() {
-    const [pacRes, hlRes, ltDetailsRes, ltFundingRes, astPremiums] = await Promise.all([
+    // SSOT rule #2: each DEX fetch is independent. allSettled lets us keep the
+    // multi-DEX comparison alive when one DEX errors out, while the rejection
+    // reasons get logged to stderr (explicit failure, never silent).
+    const settled = await Promise.allSettled([
         fetchPacificaPricesRaw(),
         fetchHyperliquidMetaRaw(),
         fetchLighterOrderBookDetailsRaw(),
         fetchLighterFundingRatesRaw(),
-        fetch("https://fapi.asterdex.com/fapi/v1/premiumIndex").then(r => r.json()).catch(() => []),
+        fetch("https://fapi.asterdex.com/fapi/v1/premiumIndex").then(r => r.json()),
     ]);
+    logSettledRejections(settled, ["pacifica", "hyperliquid", "lighter:orderbook", "lighter:funding", "aster:premiumIndex"], "arb-auto");
+    const pacRes = settled[0].status === "fulfilled" ? settled[0].value : null;
+    const hlRes = settled[1].status === "fulfilled" ? settled[1].value : null;
+    const ltDetailsRes = settled[2].status === "fulfilled" ? settled[2].value : null;
+    const ltFundingRes = settled[3].status === "fulfilled" ? settled[3].value : null;
+    const astPremiums = settled[4].status === "fulfilled" ? settled[4].value : [];
     const { rates: pacRates, prices: pacPrices } = parsePacificaRaw(pacRes);
     const { rates: hlRates, prices: hlPrices } = parseHyperliquidMetaRaw(hlRes);
     const { rates: ltRates, prices: ltPrices } = parseLighterRaw(ltDetailsRes, ltFundingRes);
-    // Aster: parse premiumIndex
+    // Aster: parse premiumIndex.
+    // SSOT rule #2: never silently coerce missing markPrice/lastFundingRate to 0
+    // — a 0 markPrice corrupts every downstream sizing calculation, and a 0
+    // funding rate flips the symbol off the arb radar without explanation.
+    // Skip the symbol entirely if either field is missing or non-finite.
     const astRates = new Map();
     const astPrices = new Map();
     for (const p of astPremiums ?? []) {
@@ -123,8 +136,15 @@ async function fetchFundingSpreads() {
         if (!rawSym.endsWith("USDT"))
             continue;
         const sym = rawSym.replace(/USDT$/, "");
-        astRates.set(sym, Number(p.lastFundingRate ?? 0));
-        astPrices.set(sym, Number(p.markPrice ?? 0));
+        const fundingRate = Number(p.lastFundingRate);
+        const markPrice = Number(p.markPrice);
+        if (!Number.isFinite(fundingRate) || !Number.isFinite(markPrice) || markPrice <= 0) {
+            // Aster premiumIndex omitted or returned non-numeric values for this
+            // symbol; skip rather than poison downstream math with a 0.
+            continue;
+        }
+        astRates.set(sym, fundingRate);
+        astPrices.set(sym, markPrice);
     }
     const snapshots = [];
     const allSymbols = new Set([...pacRates.keys(), ...hlRates.keys(), ...ltRates.keys(), ...astRates.keys()]);
@@ -246,8 +266,8 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
             console.log(chalk.green(`\n  Funding arb bot started in background.`));
             console.log(`  ID: ${chalk.white.bold(job.id)}`);
             console.log(`  Min spread: ${opts.minSpread}% | Size: $${opts.size}`);
-            console.log(`  Logs: ${chalk.gray(`perp jobs logs ${job.id}`)}`);
-            console.log(`  Stop: ${chalk.gray(`perp jobs stop ${job.id}`)}\n`);
+            console.log(`  Logs: ${chalk.gray(`perp background logs ${job.id}`)}`);
+            console.log(`  Stop: ${chalk.gray(`perp background stop ${job.id}`)}\n`);
             return;
         }
         const minSpread = parseFloat(opts.minSpread);
@@ -1470,10 +1490,23 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         const shortOk = shortResult.status === "fulfilled";
         if (longOk && shortOk) {
             // 6. Verify both positions actually exist (some exchanges return success but silently reject)
-            const [longPositions, shortPositions] = await Promise.all([
-                longAdapter.getPositions().catch(() => []),
-                shortAdapter.getPositions().catch(() => []),
+            // SSOT rule #2: distinguish "API error" from "no position opened".
+            // Previously `.catch(() => [])` collapsed both into the same code path,
+            // so a transient verify-side network blip would be misclassified as a
+            // silent exchange reject and trigger an unnecessary rollback.
+            const [longSettled, shortSettled] = await Promise.allSettled([
+                longAdapter.getPositions(),
+                shortAdapter.getPositions(),
             ]);
+            if (longSettled.status === "rejected" || shortSettled.status === "rejected") {
+                const longErr = longSettled.status === "rejected" ? (longSettled.reason instanceof Error ? longSettled.reason.message : String(longSettled.reason)) : "ok";
+                const shortErr = shortSettled.status === "rejected" ? (shortSettled.reason instanceof Error ? shortSettled.reason.message : String(shortSettled.reason)) : "ok";
+                throw new Error(`arb-auto: cannot verify post-fill positions for ${sym} ` +
+                    `(long ${longExch}: ${longErr}; short ${shortExch}: ${shortErr}). ` +
+                    `Refusing to silently misclassify API failure as a silent reject.`);
+            }
+            const longPositions = longSettled.value;
+            const shortPositions = shortSettled.value;
             const longPos = longPositions.find(p => p.symbol.toUpperCase().startsWith(sym));
             const shortPos = shortPositions.find(p => p.symbol.toUpperCase().startsWith(sym));
             if (!longPos && !shortPos) {

package/dist/commands/arb.js

@@ -1,4 +1,4 @@
-import { makeTable, formatUsd, formatPercent, formatPnl, printJson, jsonOk, withJsonErrors } from "../utils.js";
+import { makeTable, formatUsd, formatPercent, formatPnl, printJson, jsonOk, withJsonErrors, logSettledRejections } from "../utils.js";
 import chalk from "chalk";
 import { annualizeRate, toHourlyRate, estimateHourlyFunding, annualizeHourlyRate } from "../funding.js";
 import { fetchAllFundingRates, fetchSymbolFundingRates, TOP_SYMBOLS, } from "../funding-rates.js";
@@ -25,47 +25,76 @@ async function fetchHyperliquidRates() {
     }));
 }
 async function fetchAsterRates() {
+    // SSOT rule #2: do NOT silently coerce missing markPrice / lastFundingRate
+    // to 0 — that would corrupt comparisons against other DEXs. Skip symbols
+    // whose Aster row is malformed instead. The outer try/catch is intentional:
+    // if the entire endpoint fails, the arb command can still compare the
+    // remaining DEXs (graceful degradation is an explicit caller-facing
+    // behavior, not a silent data substitution).
     try {
         const premiums = await fetch("https://fapi.asterdex.com/fapi/v1/premiumIndex").then(r => r.json());
-        return (premiums ?? [])
-            .filter(p => String(p.symbol ?? "").endsWith("USDT"))
-            .map(p => ({
-            exchange: "aster",
-            symbol: String(p.symbol ?? "").replace(/USDT$/, ""),
-            fundingRate: Number(p.lastFundingRate ?? 0),
-            markPrice: Number(p.markPrice ?? 0),
-            nextFunding: Number(p.nextFundingTime ?? 0),
-        }));
+        const out = [];
+        for (const p of premiums ?? []) {
+            const rawSym = String(p.symbol ?? "");
+            if (!rawSym.endsWith("USDT"))
+                continue;
+            const fundingRate = Number(p.lastFundingRate);
+            const markPrice = Number(p.markPrice);
+            const nextFunding = Number(p.nextFundingTime);
+            if (!Number.isFinite(fundingRate) || !Number.isFinite(markPrice) || markPrice <= 0) {
+                continue;
+            }
+            out.push({
+                exchange: "aster",
+                symbol: rawSym.replace(/USDT$/, ""),
+                fundingRate,
+                markPrice,
+                nextFunding: Number.isFinite(nextFunding) ? nextFunding : 0,
+            });
+        }
+        return out;
     }
     catch {
         return [];
     }
 }
 async function fetchLighterRates() {
-    try {
-        const [details, funding] = await Promise.all([
-            fetchLighterOrderBookDetails(),
-            fetchLighterFundingRates(),
-        ]);
-        const priceMap = new Map(details.map(d => [d.marketId, d.lastTradePrice]));
-        const symMap = new Map(details.map(d => [d.marketId, d.symbol]));
-        const rates = [];
-        for (const fr of funding) {
-            const symbol = fr.symbol || symMap.get(fr.marketId);
-            if (!symbol)
-                continue;
-            rates.push({
-                exchange: "lighter",
-                symbol,
-                fundingRate: fr.rate,
-                markPrice: fr.markPrice || priceMap.get(fr.marketId) || 0,
-            });
+    // SSOT rule #2: error must propagate. Caller (handleBasisScan) uses
+    // Promise.allSettled to keep multi-DEX comparison alive when one DEX is
+    // down, with explicit stderr logging.
+    const [details, funding] = await Promise.all([
+        fetchLighterOrderBookDetails(),
+        fetchLighterFundingRates(),
+    ]);
+    const priceMap = new Map(details.map(d => [d.marketId, d.lastTradePrice]));
+    const symMap = new Map(details.map(d => [d.marketId, d.symbol]));
+    const rates = [];
+    for (const fr of funding) {
+        const symbol = fr.symbol || symMap.get(fr.marketId);
+        if (!symbol)
+            continue;
+        // Prefer fr.markPrice; fall back to orderBook last-trade as documented
+        // price-source preference (NOT error fallback). Skip if neither resolves
+        // — never publish a 0 markPrice downstream.
+        const directMark = fr.markPrice;
+        const fallbackMark = priceMap.get(fr.marketId);
+        let markPrice;
+        if (directMark !== null && Number.isFinite(directMark) && directMark > 0) {
+            markPrice = directMark;
         }
-        return rates;
-    }
-    catch {
-        return [];
+        else if (fallbackMark !== undefined && Number.isFinite(fallbackMark) && fallbackMark > 0) {
+            markPrice = fallbackMark;
+        }
+        if (markPrice === undefined || !Number.isFinite(fr.rate))
+            continue;
+        rates.push({
+            exchange: "lighter",
+            symbol,
+            fundingRate: fr.rate,
+            markPrice,
+        });
     }
+    return rates;
 }
 // annualize moved to ../funding.ts — use annualizeRate() / computeAnnualSpread()
 export function registerArbCommands(program, isJson, getAdapterForExchange) {
@@ -74,11 +103,18 @@ export function registerArbCommands(program, isJson, getAdapterForExchange) {
     // → consolidated into 'arb scan' (in arb-auto.ts) with routing options
 }
 export async function fetchAllPrices() {
-    const [pacRes, hlRes, ltRes] = await Promise.all([
+    // SSOT rule #2: each DEX is independent. allSettled keeps the comparison
+    // alive when one DEX errors out, while rejection reasons get logged to
+    // stderr (explicit failure, never silent).
+    const settled = await Promise.allSettled([
         fetchPacificaPricesRaw(),
         fetchHyperliquidAllMidsRaw(),
         fetchLighterOrderBookDetailsRaw(),
     ]);
+    logSettledRejections(settled, ["pacifica", "hyperliquid", "lighter:orderbook"], "arb");
+    const pacRes = settled[0].status === "fulfilled" ? settled[0].value : null;
+    const hlRes = settled[1].status === "fulfilled" ? settled[1].value : null;
+    const ltRes = settled[2].status === "fulfilled" ? settled[2].value : null;
     const { prices: pacPrices } = parsePacificaRaw(pacRes);
     const hlPrices = new Map();
     if (hlRes && typeof hlRes === "object" && !Array.isArray(hlRes)) {
@@ -320,7 +356,20 @@ export async function handleRates(isJson, opts) {
 export async function handleBasisScan(isJson, opts) {
     if (!isJson())
         console.log(chalk.cyan("  Fetching prices for basis calculation...\n"));
-    const [pacRates, hlRates, ltRates, astRates] = await Promise.all([fetchPacificaRates(), fetchHyperliquidRates(), fetchLighterRates(), fetchAsterRates()]);
+    // SSOT rule #2: each DEX is independent. allSettled keeps the comparison
+    // alive when one DEX errors out, while rejection reasons get logged to
+    // stderr (explicit failure, never silent [] downgrade).
+    const settled = await Promise.allSettled([
+        fetchPacificaRates(),
+        fetchHyperliquidRates(),
+        fetchLighterRates(),
+        fetchAsterRates(),
+    ]);
+    logSettledRejections(settled, ["pacifica", "hyperliquid", "lighter", "aster"], "basis-scan");
+    const pacRates = settled[0].status === "fulfilled" ? settled[0].value : [];
+    const hlRates = settled[1].status === "fulfilled" ? settled[1].value : [];
+    const ltRates = settled[2].status === "fulfilled" ? settled[2].value : [];
+    const astRates = settled[3].status === "fulfilled" ? settled[3].value : [];
     const exchangePrices = new Map();
     const filterSymbol = opts.symbol?.toUpperCase();
     for (const r of [...pacRates, ...hlRates, ...ltRates, ...astRates]) {

package/dist/commands/bot.d.ts

@@ -1,3 +1,3 @@
 import { Command } from "commander";
 import type { ExchangeAdapter } from "../exchanges/index.js";
-export declare function registerBotCommands(program: Command, getAdapter: () => Promise<ExchangeAdapter>, getAdapterFor: (exchange: string) => Promise<ExchangeAdapter>, isJson: () => boolean): void;
+export declare function registerStrategyCommands(program: Command, getAdapter: () => Promise<ExchangeAdapter>, getAdapterFor: (exchange: string) => Promise<ExchangeAdapter>, isJson: () => boolean): void;

package/dist/commands/bot.js

@@ -3,8 +3,9 @@ import { printJson, jsonOk, jsonError } from "../utils.js";
 import { loadBotConfig, parseStrategy, quickGridConfig, quickDCAConfig, runBot, PRESETS, getPreset, getPresetsByStrategy } from "../bot/index.js";
 import { updateJobState } from "../jobs.js";
 import { runTWAP, runFundingArb, runGrid, runDCA, runTrailingStop } from "../strategies/index.js";
-export function registerBotCommands(program, getAdapter, getAdapterFor, isJson) {
-    const bot = program.command("bot").description("Automated trading bots with condition monitoring & risk management");
+import { registerStrategyPlanCommands } from "./plan.js";
+export function registerStrategyCommands(program, getAdapter, getAdapterFor, isJson) {
+    const bot = program.command("strategy").description("Trading strategies — long-running bot algorithms + one-shot scripted plans");
     // ── bot start <config> ──
     bot
         .command("start <config>")
@@ -165,7 +166,7 @@ export function registerBotCommands(program, getAdapter, getAdapterFor, isJson)
         const config = {
             name: `arb-funding-${Date.now().toString(36)}`,
             exchange: primaryAdapter.name,
-            symbol: "ETH", // multi-symbol scanning
+            symbol: "ALL", // multi-symbol scanning
             strategy: {
                 type: "funding-arb",
                 min_spread: parseFloat(opts.minSpread),
@@ -243,7 +244,7 @@ export function registerBotCommands(program, getAdapter, getAdapterFor, isJson)
         const config = {
             name: `delta-neutral-${Date.now().toString(36)}`,
             exchange: primaryAdapter.name,
-            symbol: "ETH",
+            symbol: "ALL",
             strategy: {
                 type: "spot-perp-arb",
                 exchanges: exchangeNames,
@@ -312,9 +313,9 @@ export function registerBotCommands(program, getAdapter, getAdapterFor, isJson)
             }
             console.log();
         }
-        console.log(chalk.gray(`  Usage: perp bot preset <name> <symbol>`));
-        console.log(chalk.gray(`         perp bot preset grid-standard ETH`));
-        console.log(chalk.gray(`         perp bot preset arb-conservative --background\n`));
+        console.log(chalk.gray(`  Usage: perp strategy preset <name> <symbol>`));
+        console.log(chalk.gray(`         perp strategy preset grid-standard ETH`));
+        console.log(chalk.gray(`         perp strategy preset arb-conservative --background\n`));
     });
     // ── bot preset <name> <symbol> ──
     bot
@@ -327,7 +328,7 @@ export function registerBotCommands(program, getAdapter, getAdapterFor, isJson)
         const preset = getPreset(name);
         if (!preset) {
             console.error(chalk.red(`\n  Unknown preset: "${name}"`));
-            console.error(chalk.gray(`  Run 'perp bot preset-list' to see available presets.\n`));
+            console.error(chalk.gray(`  Run 'perp strategy preset-list' to see available presets.\n`));
             return;
         }
         const sym = symbol?.toUpperCase() ?? "ETH";
@@ -401,6 +402,7 @@ export function registerBotCommands(program, getAdapter, getAdapterFor, isJson)
     // ── bot list-strategies ──
     bot
         .command("list-strategies")
+        .alias("list")
         .description("List all available trading strategies")
         .action(async () => {
         await import("../bot/engine.js");
@@ -510,7 +512,7 @@ export function registerBotCommands(program, getAdapter, getAdapterFor, isJson)
     // ── bot run <strategy> <symbol> ──
     bot
         .command("run [strategy] [symbol]")
-        .description("Run a strategy (use 'perp bot list-strategies' to see all). Symbol optional for multi-symbol strategies.")
+        .description("Run a strategy (use 'perp strategy list-strategies' to see all). Symbol optional for multi-symbol strategies.")
         .option("--config <path>", "YAML/JSON config file")
         .option("--headless", "Run without TUI dashboard")
         .option("--param <key=value>", "Strategy parameter (repeatable)", (val, acc) => [...acc, val], [])
@@ -531,7 +533,7 @@ export function registerBotCommands(program, getAdapter, getAdapterFor, isJson)
             console.log(chalk.cyan.bold("\n  Available Strategies:\n"));
             for (const s of available)
                 console.log(`    ${chalk.green(s)}`);
-            console.log(chalk.gray(`\n  Usage: perp bot run <strategy> [symbol]\n`));
+            console.log(chalk.gray(`\n  Usage: perp strategy run <strategy> [symbol]\n`));
             return;
         }
         const sym = symbol?.toUpperCase() || "ALL";
@@ -547,7 +549,7 @@ export function registerBotCommands(program, getAdapter, getAdapterFor, isJson)
                 return process.exit(1);
             }
             console.error(chalk.red(`\n  Error: The '${strategyName}' strategy requires a <symbol> argument.`));
-            console.error(chalk.gray(`  Usage: perp bot run ${strategyName} <symbol>\n`));
+            console.error(chalk.gray(`  Usage: perp strategy run ${strategyName} <symbol>\n`));
             return process.exit(1);
         }
         // Load or build config
@@ -656,7 +658,7 @@ export function registerBotCommands(program, getAdapter, getAdapterFor, isJson)
                     { name: "eth-dca-dip", type: "dca", file: "~/.perp/bots/eth-dca.yaml", config: { exchange: "hyperliquid", symbol: "ETH", strategy: { type: "dca", amount: 0.01, interval_sec: 3600, total_orders: 24 }, entry_conditions: [{ type: "price_below", value: 2500 }], exit_conditions: [{ type: "price_above", value: 2800 }], risk: { max_drawdown: 100, max_daily_loss: 50 } } },
                     { name: "funding-arb", type: "funding-arb", file: "~/.perp/bots/funding-arb.yaml", config: { exchange: "hyperliquid", symbol: "ETH", strategy: { type: "funding-arb", min_spread: 20, close_spread: 5, size_usd: 100, max_positions: 3, exchanges: ["pacifica", "hyperliquid"] }, entry_conditions: [{ type: "always", value: 0 }], risk: { max_drawdown: 200, max_daily_loss: 50 } } },
                 ],
-                usage: ["perp bot start ~/.perp/bots/eth-grid.yaml", "perp bot start ~/.perp/bots/eth-grid.yaml --background"],
+                usage: ["perp strategy start ~/.perp/bots/eth-grid.yaml", "perp strategy start ~/.perp/bots/eth-grid.yaml --background"],
             }));
             return;
         }
@@ -670,11 +672,13 @@ export function registerBotCommands(program, getAdapter, getAdapterFor, isJson)
         console.log(chalk.white.bold("  3. Funding Arb Bot"));
         console.log(chalk.gray(`  Save to ~/.perp/bots/funding-arb.yaml:\n`));
         console.log(`${ARB_EXAMPLE}\n`);
-        console.log(chalk.gray(`  Usage: perp bot start ~/.perp/bots/eth-grid.yaml`));
-        console.log(chalk.gray(`         perp bot start ~/.perp/bots/eth-grid.yaml --background\n`));
+        console.log(chalk.gray(`  Usage: perp strategy start ~/.perp/bots/eth-grid.yaml`));
+        console.log(chalk.gray(`         perp strategy start ~/.perp/bots/eth-grid.yaml --background\n`));
     });
     // Strategy subcommands: twap, funding-arb, grid, dca, trailing-stop
     registerRunSubcommands(bot, getAdapter, getAdapterFor, isJson);
+    // Nested scripted plans: `perp strategy plan {validate|execute|example}`
+    registerStrategyPlanCommands(bot, getAdapter, isJson);
 }
 function makeLog() {
     return (msg) => {
@@ -692,8 +696,8 @@ function resolveOutputMode(isJson, headless) {
 function printBotJobStarted(name, jobId) {
     console.log(chalk.green(`\n  Bot "${name}" started in background.`));
     console.log(`  Job ID: ${chalk.white.bold(jobId)}`);
-    console.log(`  Logs:   ${chalk.gray(`perp jobs logs ${jobId} -f`)}`);
-    console.log(`  Stop:   ${chalk.gray(`perp jobs stop ${jobId}`)}\n`);
+    console.log(`  Logs:   ${chalk.gray(`perp background logs ${jobId} -f`)}`);
+    console.log(`  Stop:   ${chalk.gray(`perp background stop ${jobId}`)}\n`);
 }
 // ── Example YAML configs ──
 const GRID_EXAMPLE = chalk.gray(`  name: eth-grid-bot

package/dist/commands/bridge.d.ts

@@ -1,2 +1,2 @@
 import { Command } from "commander";
-export declare function registerBridgeCommands(program: Command, isJson: () => boolean): void;
+export declare function registerFundsBridgeCommands(parent: Command, isJson: () => boolean): void;

package/dist/commands/bridge.js

@@ -2,8 +2,8 @@ import chalk from "chalk";
 import { formatUsd, makeTable, printJson, jsonOk } from "../utils.js";
 import { logExecution } from "../execution-log.js";
 import { executeBestBridge, getAllQuotes, checkDebridgeStatus, checkBridgeGasBalance, CHAIN_IDS, USDC_ADDRESSES, EXCHANGE_TO_CHAIN, } from "../bridge-engine.js";
-export function registerBridgeCommands(program, isJson) {
-    const bridge = program.command("bridge").description("Cross-chain USDC bridge (deBridge DLN). See also: perp funds bridge (CCTP V2)");
+export function registerFundsBridgeCommands(parent, isJson) {
+    const bridge = parent.command("bridge").description("Cross-chain USDC bridge (multi-provider: cctp, relay, debridge — auto-cheapest)");
     // ── bridge chains ──
     bridge
         .command("chains")
@@ -79,7 +79,7 @@ export function registerBridgeCommands(program, isJson) {
             }
         }
         console.log();
-        console.log(chalk.gray(`  Execute with: perp bridge send --from ${srcChain} --to ${dstChain} --amount ${opts.amount}`));
+        console.log(chalk.gray(`  Execute with: perp funds bridge send --from ${srcChain} --to ${dstChain} --amount ${opts.amount}`));
         console.log(chalk.gray(`  Pick provider: --provider cctp|relay|debridge\n`));
     });
     // ── bridge send ──
@@ -374,7 +374,7 @@ export function registerBridgeCommands(program, isJson) {
             console.log(chalk.green(`  USDC arrived on ${dstExchange}!`));
         }
         console.log(chalk.gray(`\n  After arrival, deposit into ${dstExchange}:`));
-        console.log(chalk.gray(`  perp deposit ${dstExchange} ${opts.amount}\n`));
+        console.log(chalk.gray(`  perp funds deposit ${dstExchange} ${opts.amount}\n`));
     });
     // ── bridge status ──
     bridge

package/dist/commands/funds.d.ts

@@ -1,4 +1,4 @@
 import { Command } from "commander";
 import type { ExchangeAdapter } from "../exchanges/index.js";
 import type { Network } from "../pacifica/index.js";
-export declare function registerFundsCommands(program: Command, getAdapter: () => Promise<ExchangeAdapter>, isJson: () => boolean, getNetwork: () => Network): void;
+export declare function registerFundsCommands(program: Command, getAdapter: () => Promise<ExchangeAdapter>, isJson: () => boolean, getNetwork: () => Network, getAdapterForExchange: (exchange: string) => Promise<ExchangeAdapter>): void;

package/dist/commands/funds.js

@@ -2,6 +2,8 @@ import chalk from "chalk";
 import { printJson, formatUsd, jsonOk, jsonError } from "../utils.js";
 import { logExecution } from "../execution-log.js";
 import { hasPacificaSdk, hasEvmAddress, isWithdrawCapable, isUsdTransferCapable, hasLighterAccount } from "../exchanges/capabilities.js";
+import { registerFundsBridgeCommands } from "./bridge.js";
+import { registerFundsRebalanceCommands } from "./rebalance.js";
 const DEFAULT_RELAYER = "http://localhost:3100";
 function getRelayerUrl() {
     return process.env.PERP_RELAYER_URL || DEFAULT_RELAYER;
@@ -15,8 +17,8 @@ async function relayerAvailable() {
         return false;
     }
 }
-export function registerFundsCommands(program, getAdapter, isJson, getNetwork) {
-    const funds = program.command("funds").description("Deposit, withdraw, bridge & transfer funds");
+export function registerFundsCommands(program, getAdapter, isJson, getNetwork, getAdapterForExchange) {
+    const funds = program.command("funds").description("Fund movement — deposit, withdraw, transfer, bridge, rebalance");
     // ═══════════════════════════════════════════════════════
     //  DEPOSIT
     // ═══════════════════════════════════════════════════════
@@ -669,69 +671,6 @@ export function registerFundsCommands(program, getAdapter, isJson, getNetwork) {
         console.log(`  To:     ${destination}\n`);
     });
     // ═══════════════════════════════════════════════════════
-    //  BRIDGE (CCTP)
-    // ═══════════════════════════════════════════════════════
-    funds
-        .command("bridge")
-        .description("Bridge USDC between chains via CCTP V2. See also: perp bridge (deBridge DLN)")
-        .requiredOption("--from <chain>", "Source chain (arbitrum, ethereum)")
-        .requiredOption("--to <chain>", "Destination chain (arbitrum, ethereum, solana)")
-        .requiredOption("--amount <amount>", "USDC amount")
-        .requiredOption("--recipient <address>", "Recipient address on destination chain")
-        .action(async (opts) => {
-        const amountNum = parseFloat(opts.amount);
-        if (isNaN(amountNum) || amountNum <= 0)
-            throw new Error("Invalid amount");
-        if (await relayerAvailable()) {
-            if (!isJson())
-                console.log(chalk.cyan(`\n  Bridging $${formatUsd(amountNum)} USDC via CCTP V2 (${opts.from} → ${opts.to})...\n`));
-            const res = await fetch(`${getRelayerUrl()}/bridge/cctp`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({
-                    fromChain: opts.from,
-                    toChain: opts.to,
-                    amount: amountNum,
-                    recipient: opts.recipient,
-                }),
-            });
-            const result = (await res.json());
-            if (!res.ok)
-                throw new Error(String(result.error || "CCTP bridge failed"));
-            if (isJson())
-                return printJson(jsonOk(result));
-            console.log(chalk.green(`  Burn TX submitted!`));
-            console.log(`  TX Hash:      ${result.txHash}`);
-            console.log(`  Message Hash: ${result.messageHash}`);
-            console.log(chalk.gray(`\n  Waiting for Circle attestation (~1-3 min)...`));
-            console.log(chalk.gray(`  Check: perp funds bridge-status --hash ${result.messageHash}\n`));
-        }
-        else {
-            if (isJson()) {
-                printJson(jsonError("RELAYER_UNAVAILABLE", "CCTP bridge requires relayer server. Start: cd packages/relayer && pnpm start"));
-                process.exit(1);
-            }
-            console.error(chalk.red("\n  CCTP bridge requires relayer server."));
-            console.error(chalk.gray("  Start: cd packages/relayer && pnpm start\n"));
-            process.exit(1);
-        }
-    });
-    funds
-        .command("bridge-status")
-        .description("Check CCTP bridge status")
-        .requiredOption("--hash <messageHash>", "Message hash from bridge TX")
-        .action(async (opts) => {
-        const res = await fetch(`${getRelayerUrl()}/bridge/cctp/status/${opts.hash}`);
-        const result = (await res.json());
-        if (isJson())
-            return printJson(jsonOk(result));
-        console.log(chalk.cyan.bold("\n  CCTP Bridge Status\n"));
-        console.log(`  Status:      ${result.status === "complete" ? chalk.green("complete") : chalk.yellow(String(result.status))}`);
-        if (result.attestation)
-            console.log(`  Attestation: ${chalk.gray("received")}`);
-        console.log();
-    });
-    // ═══════════════════════════════════════════════════════
     //  INFO (combined deposit + withdraw)
     // ═══════════════════════════════════════════════════════
     funds
@@ -791,9 +730,20 @@ export function registerFundsCommands(program, getAdapter, isJson, getNetwork) {
         console.log(chalk.white.bold("  Internal Transfer") + chalk.gray(" (Hyperliquid → Hyperliquid)"));
         console.log(`  Speed: instant  |  Fee: none`);
         console.log(`  Command: ${chalk.green("perp -e hl funds transfer <amount> <address>")}`);
-        console.log(chalk.white.bold("\n  CCTP Bridge") + chalk.gray(" (Cross-chain USDC)"));
-        console.log(`  Routes:  Arbitrum ↔ Ethereum ↔ Solana`);
-        console.log(`  Command: ${chalk.green("perp funds bridge --from arbitrum --to solana --amount 100 --recipient <addr>")}`);
+        console.log(chalk.white.bold("\n  Cross-chain Bridge") + chalk.gray(" (multi-provider: cctp, relay, debridge)"));
+        console.log(`  Routes:  Solana, Arbitrum, Base, Avalanche, Ethereum`);
+        console.log(`  Quote:   ${chalk.green("perp funds bridge quote --from <chain> --to <chain> --amount <n>")}`);
+        console.log(`  Send:    ${chalk.green("perp funds bridge send --from <chain> --to <chain> --amount <n>")}`);
+        console.log(`  Between exchanges: ${chalk.green("perp funds bridge exchange --from <ex> --to <ex> --amount <n>")}`);
+        console.log(chalk.white.bold("\n  Inter-exchange Rebalance") + chalk.gray(" (orchestrated withdraw → bridge → deposit)"));
+        console.log(`  Check:   ${chalk.green("perp funds rebalance check")}`);
+        console.log(`  Plan:    ${chalk.green("perp funds rebalance plan")}`);
+        console.log(`  Execute: ${chalk.green("perp funds rebalance execute --auto-bridge")}`);
         console.log(chalk.gray("\n  Use --no-relay to skip relayer and pay gas yourself.\n"));
     });
+    // ═══════════════════════════════════════════════════════
+    //  NESTED SUBTREES — bridge (multi-provider) + rebalance
+    // ═══════════════════════════════════════════════════════
+    registerFundsBridgeCommands(funds, isJson);
+    registerFundsRebalanceCommands(funds, getAdapterForExchange, isJson);
 }