perp-cli 0.4.2 → 0.4.9

package/dist/commands/multileg.js

@@ -0,0 +1,174 @@
+/**
+ * Multi-leg order command.
+ *
+ * Executes multiple orders across exchanges simultaneously using Promise.allSettled.
+ * Supports automatic rollback if one leg fails.
+ *
+ * Usage:
+ *   perp multi "hl:ETH:buy:0.01" "pac:ETH:sell:0.01"
+ *   perp multi "hl:BTC:buy:0.001" "lighter:BTC:sell:0.001" --smart
+ *   perp multi "hl:ETH:buy:0.01" "pac:SOL:buy:1" "lighter:BTC:sell:0.0001"
+ *
+ * Leg format: exchange:symbol:side:size
+ */
+import chalk from "chalk";
+import { printJson, jsonOk, jsonError, withJsonErrors } from "../utils.js";
+import { logExecution } from "../execution-log.js";
+import { smartOrder } from "../smart-order.js";
+function parseLeg(spec) {
+    const parts = spec.split(":");
+    if (parts.length !== 4) {
+        throw new Error(`Invalid leg format "${spec}" — expected exchange:symbol:side:size`);
+    }
+    const [exchange, symbol, side, size] = parts;
+    // Normalize exchange aliases
+    const exMap = {
+        hl: "hyperliquid", pac: "pacifica", lit: "lighter",
+        hyperliquid: "hyperliquid", pacifica: "pacifica", lighter: "lighter",
+    };
+    const normalizedExchange = exMap[exchange.toLowerCase()];
+    if (!normalizedExchange) {
+        throw new Error(`Unknown exchange "${exchange}" in leg spec`);
+    }
+    if (side !== "buy" && side !== "sell") {
+        throw new Error(`Invalid side "${side}" — must be "buy" or "sell"`);
+    }
+    if (isNaN(Number(size)) || Number(size) <= 0) {
+        throw new Error(`Invalid size "${size}" — must be a positive number`);
+    }
+    return { exchange: normalizedExchange, symbol: symbol.toUpperCase(), side, size };
+}
+export function registerMultilegCommands(program, getAdapterForExchange, isJson) {
+    program
+        .command("multi <legs...>")
+        .description("Execute multi-leg orders simultaneously (exchange:symbol:side:size)")
+        .option("--smart", "Use smart order (IOC limit + fallback) for each leg")
+        .option("--rollback", "Auto-rollback filled legs if any leg fails", true)
+        .option("--no-rollback", "Disable auto-rollback")
+        .option("--timeout <ms>", "Per-leg timeout in milliseconds", "30000")
+        .action(async (legSpecs, opts) => {
+        await withJsonErrors(isJson(), async () => {
+            // Parse legs
+            const legs = legSpecs.map(parseLeg);
+            if (legs.length < 2) {
+                const err = "Multi-leg requires at least 2 legs";
+                if (isJson()) {
+                    printJson(jsonError("INVALID_ARGS", err));
+                    return;
+                }
+                throw new Error(err);
+            }
+            if (!isJson()) {
+                console.log(chalk.cyan.bold("Multi-Leg Order\n"));
+                for (const l of legs) {
+                    const color = l.side === "buy" ? chalk.green : chalk.red;
+                    console.log(`  ${l.exchange.padEnd(14)} ${color(l.side.toUpperCase())} ${l.symbol} x ${l.size}`);
+                }
+                console.log();
+            }
+            // Get adapters (deduplicated)
+            const adapters = new Map();
+            for (const l of legs) {
+                if (!adapters.has(l.exchange)) {
+                    adapters.set(l.exchange, await getAdapterForExchange(l.exchange));
+                }
+            }
+            // Execute all legs simultaneously
+            const timeoutMs = parseInt(opts.timeout);
+            const results = await Promise.allSettled(legs.map(async (leg) => {
+                const adapter = adapters.get(leg.exchange);
+                const orderPromise = opts.smart
+                    ? smartOrder(adapter, leg.symbol, leg.side, leg.size).then(r => r.result)
+                    : adapter.marketOrder(leg.symbol, leg.side, leg.size);
+                // Apply timeout
+                const result = await Promise.race([
+                    orderPromise,
+                    new Promise((_, reject) => setTimeout(() => reject(new Error("Leg timeout")), timeoutMs)),
+                ]);
+                // Log execution
+                logExecution({
+                    type: "multi_leg",
+                    exchange: leg.exchange,
+                    symbol: leg.symbol,
+                    side: leg.side,
+                    size: leg.size,
+                    status: "success",
+                    dryRun: false,
+                    meta: { result, smart: opts.smart },
+                });
+                return { leg, status: "filled", result };
+            }));
+            // Process results
+            const legResults = results.map((r, i) => {
+                if (r.status === "fulfilled")
+                    return r.value;
+                return {
+                    leg: legs[i],
+                    status: "failed",
+                    error: r.reason instanceof Error ? r.reason.message : String(r.reason),
+                };
+            });
+            const filled = legResults.filter(r => r.status === "filled");
+            const failed = legResults.filter(r => r.status === "failed");
+            // Rollback if partial fill and rollback enabled
+            if (failed.length > 0 && filled.length > 0 && opts.rollback) {
+                if (!isJson()) {
+                    console.log(chalk.yellow(`\n  ${failed.length} leg(s) failed — rolling back ${filled.length} filled leg(s)...\n`));
+                }
+                for (const fr of filled) {
+                    const adapter = adapters.get(fr.leg.exchange);
+                    const reverseSide = fr.leg.side === "buy" ? "sell" : "buy";
+                    try {
+                        await adapter.marketOrder(fr.leg.symbol, reverseSide, fr.leg.size);
+                        fr.status = "rolled_back";
+                        logExecution({
+                            type: "multi_leg_rollback",
+                            exchange: fr.leg.exchange,
+                            symbol: fr.leg.symbol,
+                            side: reverseSide,
+                            size: fr.leg.size,
+                            status: "success",
+                            dryRun: false,
+                        });
+                        if (!isJson()) {
+                            console.log(chalk.gray(`  Rolled back: ${fr.leg.exchange} ${reverseSide} ${fr.leg.symbol} x ${fr.leg.size}`));
+                        }
+                    }
+                    catch (err) {
+                        if (!isJson()) {
+                            console.log(chalk.red(`  Rollback failed: ${fr.leg.exchange} ${fr.leg.symbol} — ${err instanceof Error ? err.message : err}`));
+                        }
+                    }
+                }
+            }
+            if (isJson()) {
+                printJson(jsonOk({
+                    legs: legResults.map(r => ({
+                        exchange: r.leg.exchange,
+                        symbol: r.leg.symbol,
+                        side: r.leg.side,
+                        size: r.leg.size,
+                        status: r.status,
+                        error: r.error,
+                    })),
+                    summary: {
+                        total: legs.length,
+                        filled: legResults.filter(r => r.status === "filled").length,
+                        failed: failed.length,
+                        rolledBack: legResults.filter(r => r.status === "rolled_back").length,
+                    },
+                }));
+            }
+            else {
+                console.log(chalk.cyan.bold("\nResults:\n"));
+                for (const r of legResults) {
+                    const icon = r.status === "filled" ? chalk.green("OK") :
+                        r.status === "rolled_back" ? chalk.yellow("ROLLBACK") :
+                            chalk.red("FAIL");
+                    console.log(`  ${icon} ${r.leg.exchange.padEnd(14)} ${r.leg.side} ${r.leg.symbol} x ${r.leg.size}${r.error ? ` — ${r.error}` : ""}`);
+                }
+                console.log(`\n  Total: ${legs.length}  Filled: ${filled.length}  Failed: ${failed.length}  Rolled back: ${legResults.filter(r => r.status === "rolled_back").length}`);
+            }
+        });
+    });
+}

package/dist/commands/pnl.d.ts

@@ -0,0 +1,12 @@
+/**
+ * PnL Tracker CLI commands.
+ *
+ * perp pnl snapshot  — take one-time equity snapshots across exchanges
+ * perp pnl track     — continuous equity tracking (foreground)
+ * perp pnl daily     — daily PnL breakdown table
+ * perp pnl weekly    — weekly PnL breakdown table
+ * perp pnl summary   — performance summary (Sharpe, drawdown, win rate)
+ */
+import { Command } from "commander";
+import type { ExchangeAdapter } from "../exchanges/interface.js";
+export declare function registerPnlCommands(program: Command, getAdapterForExchange: (exchange: string) => Promise<ExchangeAdapter>, isJson: () => boolean): void;

package/dist/commands/pnl.js

@@ -0,0 +1,243 @@
+/**
+ * PnL Tracker CLI commands.
+ *
+ * perp pnl snapshot  — take one-time equity snapshots across exchanges
+ * perp pnl track     — continuous equity tracking (foreground)
+ * perp pnl daily     — daily PnL breakdown table
+ * perp pnl weekly    — weekly PnL breakdown table
+ * perp pnl summary   — performance summary (Sharpe, drawdown, win rate)
+ */
+import chalk from "chalk";
+import { printJson, jsonOk, jsonError, makeTable, formatUsd, formatPnl, withJsonErrors } from "../utils.js";
+import { saveEquitySnapshot, readEquityHistory, computePnlMetrics, computeDailyPnl, aggregateWeekly, } from "../equity-tracker.js";
+const EXCHANGES = ["pacifica", "hyperliquid", "lighter"];
+function parseSince(since) {
+    if (!since)
+        return undefined;
+    const match = since.match(/^(\d+)(h|d|w)$/);
+    if (match) {
+        const [, num, unit] = match;
+        const ms = { h: 3600000, d: 86400000, w: 604800000 }[unit] ?? 86400000;
+        return new Date(Date.now() - parseInt(num) * ms);
+    }
+    return new Date(since);
+}
+/** Take equity snapshot for given adapters. */
+async function takeSnapshot(getAdapterForExchange, exchanges) {
+    const ts = new Date().toISOString();
+    const snaps = [];
+    const results = await Promise.allSettled(exchanges.map(async (ex) => {
+        const adapter = await getAdapterForExchange(ex);
+        const [balance, positions] = await Promise.all([
+            adapter.getBalance(),
+            adapter.getPositions(),
+        ]);
+        const snap = {
+            ts,
+            exchange: ex,
+            equity: Number(balance.equity),
+            available: Number(balance.available),
+            marginUsed: Number(balance.marginUsed),
+            unrealizedPnl: Number(balance.unrealizedPnl),
+            positionCount: positions.filter(p => Number(p.size) > 0).length,
+        };
+        saveEquitySnapshot(snap);
+        return snap;
+    }));
+    for (const r of results) {
+        if (r.status === "fulfilled")
+            snaps.push(r.value);
+    }
+    return snaps;
+}
+export function registerPnlCommands(program, getAdapterForExchange, isJson) {
+    const pnl = program.command("pnl").description("Equity snapshot tracking & time-series performance (Sharpe, drawdown)");
+    // ── pnl snapshot ──
+    pnl
+        .command("snapshot")
+        .description("Take equity snapshot across all exchanges")
+        .option("--exchanges <list>", "Comma-separated exchange list", EXCHANGES.join(","))
+        .action(async (opts) => {
+        await withJsonErrors(isJson(), async () => {
+            const exchanges = opts.exchanges.split(",").map(e => e.trim());
+            const snaps = await takeSnapshot(getAdapterForExchange, exchanges);
+            if (isJson()) {
+                printJson(jsonOk({ snapshots: snaps }));
+            }
+            else {
+                const total = snaps.reduce((s, sn) => s + sn.equity, 0);
+                console.log(chalk.cyan.bold("Equity Snapshot\n"));
+                for (const s of snaps) {
+                    console.log(`  ${s.exchange.padEnd(14)} $${formatUsd(s.equity)}  ` +
+                        `avail $${formatUsd(s.available)}  ` +
+                        `uPnL ${formatPnl(s.unrealizedPnl)}  ` +
+                        `pos: ${s.positionCount}`);
+                }
+                console.log(`\n  ${"Total".padEnd(14)} $${formatUsd(total)}`);
+                console.log(chalk.gray(`\n  Saved at ${snaps[0]?.ts ?? "—"}`));
+            }
+        });
+    });
+    // ── pnl track ──
+    pnl
+        .command("track")
+        .description("Continuously track equity (foreground)")
+        .option("--interval <sec>", "Snapshot interval in seconds", "300")
+        .option("--exchanges <list>", "Comma-separated exchange list", EXCHANGES.join(","))
+        .action(async (opts) => {
+        const intervalMs = parseInt(opts.interval) * 1000;
+        const exchanges = opts.exchanges.split(",").map(e => e.trim());
+        console.log(chalk.cyan(`PnL tracker started — snapshot every ${opts.interval}s for [${exchanges.join(", ")}]`));
+        console.log(chalk.gray("Press Ctrl+C to stop\n"));
+        const controller = new AbortController();
+        process.on("SIGINT", () => controller.abort());
+        // Initial snapshot
+        const snaps = await takeSnapshot(getAdapterForExchange, exchanges);
+        const total = snaps.reduce((s, sn) => s + sn.equity, 0);
+        console.log(`${chalk.gray(new Date().toLocaleTimeString())} Total equity: $${formatUsd(total)}`);
+        while (!controller.signal.aborted) {
+            await new Promise((resolve) => {
+                const timer = setTimeout(resolve, intervalMs);
+                controller.signal.addEventListener("abort", () => { clearTimeout(timer); resolve(); }, { once: true });
+            });
+            if (controller.signal.aborted)
+                break;
+            try {
+                const s = await takeSnapshot(getAdapterForExchange, exchanges);
+                const t = s.reduce((sum, sn) => sum + sn.equity, 0);
+                const delta = t - total;
+                console.log(`${chalk.gray(new Date().toLocaleTimeString())} ` +
+                    `Total: $${formatUsd(t)}  ${formatPnl(delta)}`);
+            }
+            catch (err) {
+                console.error(chalk.red(`Snapshot error: ${err instanceof Error ? err.message : err}`));
+            }
+        }
+    });
+    // ── pnl daily ──
+    pnl
+        .command("daily")
+        .description("Daily PnL breakdown")
+        .option("--exchange <name>", "Single exchange filter")
+        .option("--days <n>", "Number of days to show", "14")
+        .option("--since <period>", "Time range (e.g. 7d, 2w, 30d)")
+        .action(async (opts) => {
+        await withJsonErrors(isJson(), async () => {
+            const since = parseSince(opts.since) ?? new Date(Date.now() - parseInt(opts.days) * 86400000);
+            const snapshots = readEquityHistory({ exchange: opts.exchange, since });
+            if (snapshots.length === 0) {
+                if (isJson()) {
+                    printJson(jsonError("NO_DATA", "No equity snapshots found. Run 'perp pnl snapshot' or 'perp pnl track' first."));
+                }
+                else {
+                    console.log(chalk.yellow("No equity snapshots found. Run 'perp pnl snapshot' or 'perp pnl track' first."));
+                }
+                return;
+            }
+            const daily = computeDailyPnl(snapshots, opts.exchange);
+            if (isJson()) {
+                printJson(jsonOk({ daily }));
+            }
+            else {
+                console.log(chalk.cyan.bold(`Daily PnL${opts.exchange ? ` (${opts.exchange})` : ""}\n`));
+                const head = ["Date", "Start", "End", "PnL", "PnL %"];
+                const rows = daily.map(d => [
+                    d.date,
+                    `$${formatUsd(d.startEquity)}`,
+                    `$${formatUsd(d.endEquity)}`,
+                    formatPnl(d.pnl),
+                    `${d.pnlPct >= 0 ? "+" : ""}${d.pnlPct.toFixed(2)}%`,
+                ]);
+                console.log(makeTable(head, rows));
+            }
+        });
+    });
+    // ── pnl weekly ──
+    pnl
+        .command("weekly")
+        .description("Weekly PnL breakdown")
+        .option("--exchange <name>", "Single exchange filter")
+        .option("--weeks <n>", "Number of weeks to show", "8")
+        .option("--since <period>", "Time range (e.g. 4w, 8w)")
+        .action(async (opts) => {
+        await withJsonErrors(isJson(), async () => {
+            const since = parseSince(opts.since) ?? new Date(Date.now() - parseInt(opts.weeks) * 7 * 86400000);
+            const snapshots = readEquityHistory({ exchange: opts.exchange, since });
+            if (snapshots.length === 0) {
+                if (isJson()) {
+                    printJson(jsonError("NO_DATA", "No equity snapshots found."));
+                }
+                else {
+                    console.log(chalk.yellow("No equity snapshots found. Run 'perp pnl snapshot' or 'perp pnl track' first."));
+                }
+                return;
+            }
+            const daily = computeDailyPnl(snapshots, opts.exchange);
+            const weekly = aggregateWeekly(daily);
+            if (isJson()) {
+                printJson(jsonOk({ weekly }));
+            }
+            else {
+                console.log(chalk.cyan.bold(`Weekly PnL${opts.exchange ? ` (${opts.exchange})` : ""}\n`));
+                const head = ["Week", "Start", "End", "PnL", "PnL %"];
+                const rows = weekly.map(w => [
+                    w.date,
+                    `$${formatUsd(w.startEquity)}`,
+                    `$${formatUsd(w.endEquity)}`,
+                    formatPnl(w.pnl),
+                    `${w.pnlPct >= 0 ? "+" : ""}${w.pnlPct.toFixed(2)}%`,
+                ]);
+                console.log(makeTable(head, rows));
+            }
+        });
+    });
+    // ── pnl summary ──
+    pnl
+        .command("summary")
+        .description("Performance summary — Sharpe, drawdown, win rate")
+        .option("--exchange <name>", "Single exchange filter")
+        .option("--since <period>", "Time range (e.g. 7d, 30d, 12w)")
+        .action(async (opts) => {
+        await withJsonErrors(isJson(), async () => {
+            const since = parseSince(opts.since);
+            const snapshots = readEquityHistory({ exchange: opts.exchange, since });
+            if (snapshots.length === 0) {
+                if (isJson()) {
+                    printJson(jsonError("NO_DATA", "No equity snapshots found."));
+                }
+                else {
+                    console.log(chalk.yellow("No equity snapshots found. Run 'perp pnl snapshot' or 'perp pnl track' first."));
+                }
+                return;
+            }
+            const metrics = computePnlMetrics(snapshots, opts.exchange);
+            if (isJson()) {
+                printJson(jsonOk({
+                    ...metrics,
+                    dailyReturns: undefined, // omit large array from JSON
+                    dailyCount: metrics.dailyReturns.length,
+                }));
+            }
+            else {
+                console.log(chalk.cyan.bold(`Performance Summary${opts.exchange ? ` (${opts.exchange})` : ""}\n`));
+                console.log(`  Period:          ${metrics.period.from} → ${metrics.period.to} (${metrics.period.days} days)`);
+                console.log(`  Total Return:    ${formatPnl(metrics.totalReturn)} (${metrics.totalReturnPct >= 0 ? "+" : ""}${metrics.totalReturnPct.toFixed(2)}%)`);
+                console.log(`  Peak Equity:     $${formatUsd(metrics.peakEquity)}`);
+                console.log(`  Avg Daily PnL:   ${formatPnl(metrics.avgDailyPnl)}`);
+                console.log();
+                console.log(`  Sharpe Ratio:    ${metrics.sharpeRatio >= 0 ? chalk.green(metrics.sharpeRatio.toFixed(2)) : chalk.red(metrics.sharpeRatio.toFixed(2))}`);
+                console.log(`  Max Drawdown:    ${chalk.red(`$${formatUsd(metrics.maxDrawdown)}`)} (${chalk.red(`-${metrics.maxDrawdownPct.toFixed(2)}%`)})`);
+                console.log(`  Current DD:      $${formatUsd(metrics.currentDrawdown)} (-${metrics.currentDrawdownPct.toFixed(2)}%)`);
+                console.log();
+                console.log(`  Win Days:        ${chalk.green(String(metrics.winDays))} / ${metrics.winDays + metrics.lossDays}`);
+                console.log(`  Win Rate:        ${metrics.winRate.toFixed(1)}%`);
+                if (metrics.bestDay) {
+                    console.log(`  Best Day:        ${metrics.bestDay.date}  ${formatPnl(metrics.bestDay.pnl)}`);
+                }
+                if (metrics.worstDay) {
+                    console.log(`  Worst Day:       ${metrics.worstDay.date}  ${formatPnl(metrics.worstDay.pnl)}`);
+                }
+            }
+        });
+    });
+}

package/dist/commands/risk.d.ts

@@ -1,3 +1,5 @@
 import { Command } from "commander";
 import type { ExchangeAdapter } from "../exchanges/interface.js";
+/** Run health check and return results + render. Exported for use by status --health. */
+export declare function runHealthCheck(isJson: () => boolean): Promise<void>;
 export declare function registerRiskCommands(program: Command, getAdapterForExchange: (exchange: string) => Promise<ExchangeAdapter>, isJson: () => boolean): void;

package/dist/commands/risk.js

@@ -1,6 +1,52 @@
 import chalk from "chalk";
 import { printJson, jsonOk, makeTable, formatUsd, withJsonErrors } from "../utils.js";
 import { loadRiskLimits, saveRiskLimits, assessRisk, getLiquidationDistances } from "../risk.js";
+import { pingPacifica, pingHyperliquid, pingLighter } from "../shared-api.js";
+/** Run health check and return results + render. Exported for use by status --health. */
+export async function runHealthCheck(isJson) {
+    const [pacPing, hlPing, ltPing] = await Promise.all([
+        pingPacifica(),
+        pingHyperliquid(),
+        pingLighter(),
+    ]);
+    const toPingResult = (name, p) => ({
+        exchange: name,
+        status: p.ok ? "ok" : "down",
+        latency_ms: p.latencyMs,
+        error: p.ok ? undefined : `HTTP ${p.status}`,
+    });
+    const checks = [
+        toPingResult("pacifica", pacPing),
+        toPingResult("hyperliquid", hlPing),
+        toPingResult("lighter", ltPing),
+    ];
+    const allOk = checks.every(c => c.status === "ok");
+    if (isJson()) {
+        return printJson(jsonOk({ healthy: allOk, exchanges: checks }));
+    }
+    console.log(chalk.cyan.bold("\n  Exchange Health Check\n"));
+    const rows = checks.map(c => {
+        const statusIcon = c.status === "ok"
+            ? chalk.green("OK")
+            : c.status === "degraded"
+                ? chalk.yellow("DEGRADED")
+                : chalk.red("DOWN");
+        const latency = c.latency_ms < 500
+            ? chalk.green(`${c.latency_ms}ms`)
+            : c.latency_ms < 2000
+                ? chalk.yellow(`${c.latency_ms}ms`)
+                : chalk.red(`${c.latency_ms}ms`);
+        return [
+            chalk.white.bold(c.exchange),
+            statusIcon,
+            latency,
+            c.error ? chalk.red(c.error) : chalk.gray("-"),
+        ];
+    });
+    console.log(makeTable(["Exchange", "Status", "Latency", "Error"], rows));
+    const overall = allOk ? chalk.green("ALL HEALTHY") : chalk.red("ISSUES DETECTED");
+    console.log(`\n  Overall: ${overall}\n`);
+}
 const EXCHANGES = ["pacifica", "hyperliquid", "lighter"];
 export function registerRiskCommands(program, getAdapterForExchange, isJson) {
     const risk = program.command("risk").description("Risk management and guardrails");
@@ -278,4 +324,14 @@ export function registerRiskCommands(program, getAdapterForExchange, isJson) {
             }
         });
     });
+    // ── deprecated: health (merged into risk) ──
+    const healthCmd = program
+        .command("health")
+        .description("Use 'perp status --health'")
+        .action(async () => {
+        if (!isJson())
+            console.log(chalk.yellow("  Use 'perp status --health' instead.\n"));
+        await runHealthCheck(isJson);
+    });
+    healthCmd._hidden = true;
 }

package/dist/commands/settings.js

@@ -1,6 +1,26 @@
 import chalk from "chalk";
 import { printJson, jsonOk, withJsonErrors } from "../utils.js";
 import { loadSettings, saveSettings } from "../settings.js";
+import { ENV_FILE, loadEnvFile, setEnvVar, EXCHANGE_ENV_MAP, validateKey } from "./init.js";
+// Resolve exchange alias → env var key
+function resolveEnvKey(nameOrKey) {
+    // Direct env var name
+    const upper = nameOrKey.toUpperCase();
+    for (const info of Object.values(EXCHANGE_ENV_MAP)) {
+        if (info.envKey === upper)
+            return { envKey: info.envKey, chain: info.chain };
+    }
+    // Exchange name alias
+    const info = EXCHANGE_ENV_MAP[nameOrKey.toLowerCase()];
+    if (info)
+        return { envKey: info.envKey, chain: info.chain };
+    // Common aliases
+    const aliases = { hl: "hyperliquid", pac: "pacifica", lt: "lighter" };
+    const aliased = aliases[nameOrKey.toLowerCase()];
+    if (aliased)
+        return resolveEnvKey(aliased);
+    return null;
+}
 export function registerSettingsCommands(program, isJson, getAdapterForExchange) {
     const settings = program.command("settings").description("CLI settings (referrals, defaults, fees)");
     // ── settings show ──
@@ -230,4 +250,131 @@ export function registerSettingsCommands(program, isJson, getAdapterForExchange)
             console.log(chalk.green(`\n  ${key} = ${value}\n`));
         });
     });
+    // ── settings env ──
+    const env = settings.command("env").description("Manage ~/.perp/.env configuration");
+    // ── settings env show ──
+    env
+        .command("show")
+        .description("Show current configuration")
+        .action(async () => {
+        const stored = loadEnvFile();
+        const entries = [];
+        for (const [exchange, info] of Object.entries(EXCHANGE_ENV_MAP)) {
+            const fromFile = stored[info.envKey];
+            const fromEnv = process.env[info.envKey];
+            if (fromFile) {
+                entries.push({ name: exchange, chain: info.chain, key: fromFile, source: "~/.perp/.env" });
+            }
+            else if (fromEnv) {
+                entries.push({ name: exchange, chain: info.chain, key: fromEnv, source: "environment" });
+            }
+        }
+        // Derive addresses
+        const results = [];
+        for (const entry of entries) {
+            const { valid, address } = await validateKey(entry.chain, entry.key);
+            results.push({ name: entry.name, address: valid ? address : "(invalid key)", source: entry.source });
+        }
+        if (isJson()) {
+            const data = results.map((r) => ({ exchange: r.name, address: r.address, source: r.source }));
+            return printJson(jsonOk({ envFile: ENV_FILE, exchanges: data }));
+        }
+        console.log(chalk.cyan.bold("\n  perp-cli Configuration\n"));
+        console.log(`  File: ${chalk.gray(ENV_FILE)}\n`);
+        if (results.length === 0) {
+            console.log(chalk.gray("  No keys configured. Run 'perp init' or 'perp settings env set <exchange> <key>'\n"));
+            return;
+        }
+        for (const { name, address, source } of results) {
+            console.log(`  ${chalk.cyan(name.padEnd(14))} ${chalk.green(address)}  ${chalk.gray(source)}`);
+        }
+        console.log();
+    });
+    // ── settings env set <exchange|key> <value> ──
+    env
+        .command("set <name> <value>")
+        .description("Set a key (exchange name or env var name)")
+        .action(async (name, value) => {
+        const resolved = resolveEnvKey(name);
+        if (resolved) {
+            // Validate the key
+            const { valid, address } = await validateKey(resolved.chain, value);
+            if (!valid) {
+                if (isJson()) {
+                    const { jsonError } = await import("../utils.js");
+                    return printJson(jsonError("INVALID_PARAMS", `Invalid ${resolved.chain} private key`));
+                }
+                console.error(chalk.red(`\n  Invalid ${resolved.chain} private key.\n`));
+                process.exit(1);
+            }
+            const normalized = resolved.chain === "evm"
+                ? (value.startsWith("0x") ? value : `0x${value}`)
+                : value;
+            setEnvVar(resolved.envKey, normalized);
+            if (isJson())
+                return printJson(jsonOk({ key: resolved.envKey, address, file: ENV_FILE }));
+            console.log(chalk.green(`\n  ${resolved.envKey} set.`));
+            console.log(`  Address: ${chalk.gray(address)}`);
+            console.log(`  File:    ${chalk.gray("~/.perp/.env")}\n`);
+        }
+        else {
+            // Raw env var (e.g. LIGHTER_API_KEY, custom vars)
+            setEnvVar(name, value);
+            if (isJson())
+                return printJson(jsonOk({ key: name, file: ENV_FILE }));
+            console.log(chalk.green(`\n  ${name} set.`));
+            console.log(`  File: ${chalk.gray("~/.perp/.env")}\n`);
+        }
+    });
+    // ── settings env remove <name> ──
+    env
+        .command("remove <name>")
+        .description("Remove a key from ~/.perp/.env")
+        .action(async (name) => {
+        const resolved = resolveEnvKey(name);
+        const envKey = resolved?.envKey || name;
+        const env = loadEnvFile();
+        if (!(envKey in env)) {
+            if (isJson()) {
+                const { jsonError } = await import("../utils.js");
+                return printJson(jsonError("NOT_FOUND", `${envKey} not found in ~/.perp/.env`));
+            }
+            console.log(chalk.gray(`\n  ${envKey} not found in ~/.perp/.env\n`));
+            return;
+        }
+        delete env[envKey];
+        // Rewrite file
+        const { writeFileSync } = await import("fs");
+        const lines = ["# perp-cli configuration", "# Generated by 'perp init' — edit freely", ""];
+        for (const [k, v] of Object.entries(env))
+            lines.push(`${k}=${v}`);
+        lines.push("");
+        writeFileSync(ENV_FILE, lines.join("\n"), { mode: 0o600 });
+        if (isJson())
+            return printJson(jsonOk({ removed: envKey }));
+        console.log(chalk.yellow(`\n  ${envKey} removed from ~/.perp/.env\n`));
+    });
+    // ── settings env path ──
+    env
+        .command("path")
+        .description("Print env file path")
+        .action(() => {
+        if (isJson())
+            return printJson(jsonOk({ path: ENV_FILE }));
+        console.log(ENV_FILE);
+    });
+    // ── Deprecated top-level `env` command ──
+    const deprecatedEnv = program
+        .command("env")
+        .description("[deprecated] Use 'perp settings env'")
+        .allowUnknownOption()
+        .action(() => {
+        console.log(chalk.yellow("\n  'perp env' is deprecated. Use 'perp settings env' instead.\n"));
+        console.log(chalk.gray("  Examples:"));
+        console.log(chalk.gray("    perp settings env show"));
+        console.log(chalk.gray("    perp settings env set <exchange> <key>"));
+        console.log(chalk.gray("    perp settings env remove <name>"));
+        console.log(chalk.gray("    perp settings env path\n"));
+    });
+    deprecatedEnv._hidden = true;
 }