perp-cli 0.12.17 → 0.14.1

package/dist/commands/history.js

@@ -1,10 +1,11 @@
+import { listConfiguredAccountVenues } from "../config.js";
 import chalk from "chalk";
 import { printJson, jsonOk, jsonError, makeTable, formatUsd, formatPnl, withJsonErrors } from "../utils.js";
 import { readExecutionLog, getExecutionStats, pruneExecutionLog } from "../execution-log.js";
 import { loadArbState } from "../arb/index.js";
+import { networkOf } from "../cli-flags.js";
 import { readPositionHistory, getPositionStats } from "../position-history.js";
 import { saveEquitySnapshot, readEquityHistory, computePnlMetrics, computeDailyPnl, aggregateWeekly, } from "../equity-tracker.js";
-const EXCHANGES = ["pacifica", "hyperliquid", "lighter", "aster"];
 function parseSince(since) {
     if (!since)
         return undefined;
@@ -16,6 +17,18 @@ function parseSince(since) {
     }
     return since;
 }
+/**
+ * Exchange filter of a history subcommand: the ROOT `-e, --exchange`, only when given on the command
+ * line. Commander hands `-e` / `--exchange` to the root wherever it appears in argv, so a subcommand
+ * copy of the option was never set (the filter was silently dropped). The root's default venue is
+ * never used as a filter.
+ */
+function cliExchangeFilter(cmd) {
+    let root = cmd;
+    while (root.parent)
+        root = root.parent;
+    return root.getOptionValueSource("exchange") === "cli" ? String(root.opts().exchange) : undefined;
+}
 /** Parse period string (7d, 30d, 90d) to milliseconds. Returns undefined for "all" or missing. */
 function parsePeriodMs(period) {
     if (!period || period === "all")
@@ -32,14 +45,14 @@ export function registerHistoryCommands(program, isJson, getAdapterForExchange)
     // ── history list ──
     history
         .command("list")
-        .description("Show recent executions")
-        .option("-n, --limit <n>", "Number of records to show", "20")
-        .option("-e, --exchange <exchange>", "Filter by exchange")
+        .description("Show recent executions — filter with the root -e <exchange>")
+        .option("--limit <n>", "Number of records to show", "20")
         .option("-s, --symbol <symbol>", "Filter by symbol")
         .option("-t, --type <type>", "Filter by type (market_order, limit_order, arb_entry, etc.)")
         .option("--since <date>", "Show records since date (ISO format or relative like '24h', '7d')")
         .option("--dry-run-only", "Show only dry-run simulations")
         .action(async (opts) => {
+        const exchangeFilter = cliExchangeFilter(history);
         await withJsonErrors(isJson(), async () => {
             // Parse relative dates
             let since = opts.since;
@@ -53,7 +66,7 @@ export function registerHistoryCommands(program, isJson, getAdapterForExchange)
             }
             const records = readExecutionLog({
                 limit: parseInt(opts.limit),
-                exchange: opts.exchange,
+                exchange: exchangeFilter,
                 symbol: opts.symbol,
                 type: opts.type,
                 since,
@@ -143,14 +156,14 @@ export function registerHistoryCommands(program, isJson, getAdapterForExchange)
     // ── history positions ──
     history
         .command("positions")
-        .description("Show position history (from event stream logging)")
-        .option("-n, --limit <n>", "Number of records to show", "20")
-        .option("-e, --exchange <exchange>", "Filter by exchange")
+        .description("Show position history (from event stream logging) — filter with the root -e <exchange>")
+        .option("--limit <n>", "Number of records to show", "20")
         .option("-s, --symbol <symbol>", "Filter by symbol")
         .option("--status <status>", "Filter by status (open, closed, updated)")
         .option("--since <date>", "Show records since date (ISO format or relative like '24h', '7d')")
         .option("--stats", "Show aggregate position stats instead of list")
         .action(async (opts) => {
+        const exchangeFilter = cliExchangeFilter(history);
         await withJsonErrors(isJson(), async () => {
             // Parse relative dates
             let since = opts.since;
@@ -164,7 +177,7 @@ export function registerHistoryCommands(program, isJson, getAdapterForExchange)
             }
             // Stats mode
             if (opts.stats) {
-                const stats = getPositionStats({ exchange: opts.exchange, since });
+                const stats = getPositionStats({ exchange: exchangeFilter, since });
                 if (isJson()) {
                     return printJson(jsonOk(stats));
                 }
@@ -206,7 +219,7 @@ export function registerHistoryCommands(program, isJson, getAdapterForExchange)
             // List mode
             const records = readPositionHistory({
                 limit: parseInt(opts.limit),
-                exchange: opts.exchange,
+                exchange: exchangeFilter,
                 symbol: opts.symbol,
                 status: opts.status,
                 since,
@@ -330,16 +343,16 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
     // ── analytics pnl ──
     parent
         .command("pnl")
-        .description("P&L analysis — trades, fees, funding income with daily breakdown")
-        .option("-e, --exchange <exchanges>", "Comma-separated exchanges")
+        .description("P&L analysis — trades, fees, funding income with daily breakdown — filter with the root -e <exchange> (comma-separated)")
         .option("--period <duration>", "Time period: 7d, 30d, 90d, all (default: all)")
         .option("--since <period>", "Alias for --period")
-        .option("-n, --limit <n>", "History limit per exchange", "200")
+        .option("--limit <n>", "History limit per exchange", "200")
         .action(async (opts) => {
+        const exchangeFilter = cliExchangeFilter(parent);
         await withJsonErrors(isJson(), async () => {
-            const exchanges = opts.exchange
-                ? opts.exchange.split(",").map(e => e.trim())
-                : [...EXCHANGES];
+            const exchanges = exchangeFilter
+                ? exchangeFilter.split(",").map(e => e.trim())
+                : await listConfiguredAccountVenues();
             const period = opts.period ?? opts.since;
             const periodMs = parsePeriodMs(period);
             const sinceMs = periodMs ? Date.now() - periodMs : 0;
@@ -451,17 +464,17 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
     // ── analytics funding ──
     parent
         .command("funding")
-        .description("Funding income analysis — cumulative, daily, per-arb-position breakdown")
-        .option("-e, --exchange <exchanges>", "Comma-separated exchanges")
+        .description("Funding income analysis — cumulative, daily, per-arb-position breakdown — filter with the root -e <exchange> (comma-separated)")
         .option("-s, --symbol <symbol>", "Filter by symbol")
         .option("--period <duration>", "Time period: 7d, 30d, 90d, all (default: all)")
         .option("--daily", "Show daily funding breakdown")
-        .option("-n, --limit <n>", "Funding history limit per exchange", "200")
+        .option("--limit <n>", "Funding history limit per exchange", "200")
         .action(async (opts) => {
+        const exchangeFilter = cliExchangeFilter(parent);
         await withJsonErrors(isJson(), async () => {
-            const exchanges = opts.exchange
-                ? opts.exchange.split(",").map(e => e.trim())
-                : [...EXCHANGES];
+            const exchanges = exchangeFilter
+                ? exchangeFilter.split(",").map(e => e.trim())
+                : await listConfiguredAccountVenues();
             const periodMs = parsePeriodMs(opts.period);
             const sinceMs = periodMs ? Date.now() - periodMs : 0;
             const allFunding = [];
@@ -510,7 +523,7 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
                     ? (allFunding[allFunding.length - 1].time - allFunding[0].time) / 86400000
                     : 1;
             // Match funding to arb positions
-            const arbState = loadArbState();
+            const arbState = loadArbState(networkOf(parent));
             const arbPositions = arbState?.positions ?? [];
             const arbFunding = new Map();
             for (const pos of arbPositions) {
@@ -611,17 +624,17 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
     // ── analytics report ──
     parent
         .command("report")
-        .description("Full performance report (summary + pnl + funding)")
-        .option("-e, --exchange <exchanges>", "Comma-separated exchanges")
+        .description("Full performance report (summary + pnl + funding) — filter with the root -e <exchange> (comma-separated)")
         .option("--since <period>", "Period: 24h, 7d, 30d")
         .action(async (opts) => {
+        const exchangeFilter = cliExchangeFilter(parent);
         await withJsonErrors(isJson(), async () => {
             const since = parseSince(opts.since);
             const stats = getExecutionStats(since);
             const records = readExecutionLog({ since });
-            const exchanges = opts.exchange
-                ? opts.exchange.split(",").map(e => e.trim())
-                : [...EXCHANGES];
+            const exchanges = exchangeFilter
+                ? exchangeFilter.split(",").map(e => e.trim())
+                : await listConfiguredAccountVenues();
             // Volume from log
             let logVolume = 0;
             for (const r of records) {
@@ -634,24 +647,42 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
             let totalEquity = 0;
             let totalUPnl = 0;
             const symbolSet = new Set();
+            // A venue whose read failed is reported here and left out of the totals — never counted as 0.
+            const errors = {};
+            const errText = (e) => (e instanceof Error ? e.message : String(e));
             await Promise.allSettled(exchanges.map(async (ex) => {
+                let adapter;
                 try {
-                    const adapter = await getAdapterForExchange(ex);
-                    const [balance, trades, funding] = await Promise.all([
-                        adapter.getBalance(),
-                        adapter.getTradeHistory(50).catch(() => []),
-                        adapter.getFundingPayments(50).catch(() => []),
-                    ]);
+                    adapter = await getAdapterForExchange(ex);
+                }
+                catch (e) {
+                    errors[`${ex}.adapter`] = errText(e);
+                    return;
+                }
+                try {
+                    const balance = await adapter.getBalance();
                     totalEquity += Number(balance.equity);
                     totalUPnl += Number(balance.unrealizedPnl);
-                    for (const t of trades) {
+                }
+                catch (e) {
+                    errors[`${ex}.balance`] = errText(e);
+                    return;
+                }
+                const [trades, funding] = await Promise.allSettled([adapter.getTradeHistory(50), adapter.getFundingPayments(50)]);
+                if (trades.status === "fulfilled") {
+                    for (const t of trades.value) {
                         totalFees += Number(t.fee);
                         symbolSet.add(t.symbol);
                     }
-                    for (const f of funding)
+                }
+                else
+                    errors[`${ex}.trades`] = errText(trades.reason);
+                if (funding.status === "fulfilled") {
+                    for (const f of funding.value)
                         totalFunding += Number(f.payment);
                 }
-                catch { /* skip */ }
+                else
+                    errors[`${ex}.funding`] = errText(funding.reason);
             }));
             const report = {
                 period: opts.since ?? "all time",
@@ -678,6 +709,7 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
                         ? (stats.totalTrades / Math.max(1, (Date.now() - new Date(records[records.length - 1]?.timestamp ?? Date.now()).getTime()) / 86400000)).toFixed(1)
                         : "0",
                 },
+                errors,
             };
             if (isJson())
                 return printJson(jsonOk(report));
@@ -694,6 +726,8 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
             console.log(`    Trading Fees:    ${chalk.red(`-$${formatUsd(totalFees)}`)}`);
             console.log(`    Funding Income:  ${formatPnl(totalFunding)}`);
             console.log(`    Net:             ${formatPnl(totalFunding - totalFees)}`);
+            for (const [k, msg] of Object.entries(errors))
+                console.log(chalk.yellow(`    ⚠ ${k} unavailable (left out of the totals): ${msg}`));
             console.log();
         });
     });
@@ -702,10 +736,10 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
         .command("compare")
         .description("Compare active arb positions — ROI, realized PnL, funding income side by side")
         .option("--period <duration>", "Funding lookup period: 7d, 30d, 90d, all (default: all)")
-        .option("-n, --limit <n>", "Funding history limit per exchange", "200")
+        .option("--limit <n>", "Funding history limit per exchange", "200")
         .action(async (opts) => {
         await withJsonErrors(isJson(), async () => {
-            const arbState = loadArbState();
+            const arbState = loadArbState(networkOf(parent));
             const positions = arbState?.positions ?? [];
             if (positions.length === 0) {
                 if (isJson())
@@ -744,8 +778,12 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
                 }
                 catch { /* skip */ }
             }));
+            // Entries without a verified entry price (a bot leg the venue reported no fill price for)
+            // have no price PnL: listed apart, never priced at a guess.
+            const priced = positions.filter((p) => p.entryLongPrice !== null && p.entryShortPrice !== null);
+            const unpricedPositions = positions.filter(p => p.entryLongPrice === null || p.entryShortPrice === null).map(p => p.symbol);
             // Build comparison data
-            const rows = positions.map(pos => {
+            const rows = priced.map(pos => {
                 const daysHeld = Math.max(1, Math.round((Date.now() - new Date(pos.entryTime).getTime()) / 86400000));
                 const longFunding = fundingByExSym.get(`${pos.longExchange}:${pos.symbol}`) ?? 0;
                 const shortFunding = fundingByExSym.get(`${pos.shortExchange}:${pos.symbol}`) ?? 0;
@@ -790,6 +828,7 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
                 period: opts.period ?? "all",
                 positionCount: rows.length,
                 positions: rows,
+                unpricedPositions,
                 totals: {
                     ...totals,
                     roi: totals.notional > 0 ? (totals.totalPnl / totals.notional) * 100 : 0,
@@ -811,6 +850,8 @@ function registerAnalyticsSubcommands(parent, getAdapterForExchange, isJson) {
                 `${r.annualizedRoi >= 0 ? "+" : ""}${r.annualizedRoi.toFixed(1)}%`,
             ]);
             console.log(makeTable(["Symbol", "Long → Short", "Mode", "Held", "Funding", "Price PnL", "Total PnL", "ROI", "Ann.ROI"], tableRows));
+            if (unpricedPositions.length > 0)
+                console.log(chalk.gray(`  No entry price recorded (not compared): ${unpricedPositions.join(", ")}\n`));
             console.log(chalk.white.bold("  Totals:"));
             console.log(`    Funding Income:   ${formatPnl(totals.funding)}`);
             console.log(`    Price PnL:        ${formatPnl(totals.pricePnl)}`);
@@ -866,10 +907,10 @@ function registerPnlSubcommands(parent, getAdapterForExchange, isJson) {
     parent
         .command("snapshot")
         .description("Take equity snapshot across all exchanges")
-        .option("--exchanges <list>", "Comma-separated exchange list", EXCHANGES.join(","))
+        .option("--exchanges <list>", "Comma-separated exchange list (default: all with configured credentials)")
         .action(async (opts) => {
         await withJsonErrors(isJson(), async () => {
-            const exchanges = opts.exchanges.split(",").map(e => e.trim());
+            const exchanges = opts.exchanges ? opts.exchanges.split(",").map(e => e.trim()) : await listConfiguredAccountVenues();
             const snaps = await takeSnapshot(getAdapterForExchange, exchanges);
             if (isJson()) {
                 printJson(jsonOk({ snapshots: snaps }));
@@ -893,10 +934,10 @@ function registerPnlSubcommands(parent, getAdapterForExchange, isJson) {
         .command("track")
         .description("Continuously track equity (foreground)")
         .option("--interval <sec>", "Snapshot interval in seconds", "300")
-        .option("--exchanges <list>", "Comma-separated exchange list", EXCHANGES.join(","))
+        .option("--exchanges <list>", "Comma-separated exchange list (default: all with configured credentials)")
         .action(async (opts) => {
         const intervalMs = parseInt(opts.interval) * 1000;
-        const exchanges = opts.exchanges.split(",").map(e => e.trim());
+        const exchanges = opts.exchanges ? opts.exchanges.split(",").map(e => e.trim()) : await listConfiguredAccountVenues();
         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();
@@ -907,8 +948,15 @@ function registerPnlSubcommands(parent, getAdapterForExchange, isJson) {
         console.log(`${chalk.gray(new Date().toLocaleTimeString())} Total equity: $${formatUsd(prevTotal)}`);
         while (!controller.signal.aborted) {
             await new Promise((resolve) => {
-                const timer = setTimeout(resolve, intervalMs);
-                controller.signal.addEventListener("abort", () => { clearTimeout(timer); resolve(); }, { once: true });
+                let timer;
+                const onAbort = () => { clearTimeout(timer); resolve(); };
+                // Remove the listener when the timer wins so it does not pile up on
+                // the controller's signal every snapshot interval (MaxListeners leak).
+                timer = setTimeout(() => {
+                    controller.signal.removeEventListener("abort", onAbort);
+                    resolve();
+                }, intervalMs);
+                controller.signal.addEventListener("abort", onAbort, { once: true });
             });
             if (controller.signal.aborted)
                 break;
@@ -928,20 +976,20 @@ function registerPnlSubcommands(parent, getAdapterForExchange, isJson) {
     // ── perf (unified: daily/weekly/summary) ──
     parent
         .command("perf")
-        .description("Performance breakdown — daily, weekly, or summary stats")
+        .description("Performance breakdown — daily, weekly, or summary stats — filter with the root -e <exchange>")
         .option("--period <period>", "daily, weekly, or summary", "daily")
-        .option("--exchange <name>", "Single exchange filter")
         .option("--days <n>", "Number of days (daily mode)", "14")
         .option("--weeks <n>", "Number of weeks (weekly mode)", "8")
         .option("--since <period>", "Time range (e.g. 7d, 2w, 30d)")
         .action(async (opts) => {
+        const exchangeFilter = cliExchangeFilter(parent);
         await withJsonErrors(isJson(), async () => {
             const mode = opts.period.toLowerCase();
             const defaultSince = mode === "weekly"
                 ? new Date(Date.now() - parseInt(opts.weeks) * 7 * 86400000)
                 : new Date(Date.now() - parseInt(opts.days) * 86400000);
             const since = parseSinceDate(opts.since) ?? defaultSince;
-            const snapshots = readEquityHistory({ exchange: opts.exchange, since });
+            const snapshots = readEquityHistory({ exchange: exchangeFilter, since });
             if (snapshots.length === 0) {
                 if (isJson()) {
                     printJson(jsonError("NO_DATA", "No equity snapshots found. Run 'perp history snapshot' or 'perp history track' first."));
@@ -952,12 +1000,12 @@ function registerPnlSubcommands(parent, getAdapterForExchange, isJson) {
                 return;
             }
             if (mode === "summary") {
-                const metrics = computePnlMetrics(snapshots, opts.exchange);
+                const metrics = computePnlMetrics(snapshots, exchangeFilter);
                 if (isJson()) {
                     printJson(jsonOk({ ...metrics, dailyReturns: undefined, dailyCount: metrics.dailyReturns.length }));
                 }
                 else {
-                    console.log(chalk.cyan.bold(`Performance Summary${opts.exchange ? ` (${opts.exchange})` : ""}\n`));
+                    console.log(chalk.cyan.bold(`Performance Summary${exchangeFilter ? ` (${exchangeFilter})` : ""}\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)}`);
@@ -976,14 +1024,14 @@ function registerPnlSubcommands(parent, getAdapterForExchange, isJson) {
                 }
                 return;
             }
-            const daily = computeDailyPnl(snapshots, opts.exchange);
+            const daily = computeDailyPnl(snapshots, exchangeFilter);
             if (mode === "weekly") {
                 const weekly = aggregateWeekly(daily);
                 if (isJson()) {
                     printJson(jsonOk({ weekly }));
                     return;
                 }
-                console.log(chalk.cyan.bold(`Weekly PnL${opts.exchange ? ` (${opts.exchange})` : ""}\n`));
+                console.log(chalk.cyan.bold(`Weekly PnL${exchangeFilter ? ` (${exchangeFilter})` : ""}\n`));
                 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(["Week", "Start", "End", "PnL", "PnL %"], rows));
             }
@@ -993,7 +1041,7 @@ function registerPnlSubcommands(parent, getAdapterForExchange, isJson) {
                     printJson(jsonOk({ daily }));
                     return;
                 }
-                console.log(chalk.cyan.bold(`Daily PnL${opts.exchange ? ` (${opts.exchange})` : ""}\n`));
+                console.log(chalk.cyan.bold(`Daily PnL${exchangeFilter ? ` (${exchangeFilter})` : ""}\n`));
                 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(["Date", "Start", "End", "PnL", "PnL %"], rows));
             }

package/dist/commands/init.d.ts

@@ -1,4 +1,10 @@
 import { Command } from "commander";
+import { type Settings } from "../settings.js";
+import { type StructuredError } from "../errors.js";
+import { type VenueDefinition } from "../exchanges/venue.js";
+import "../exchanges/venues/index.js";
+import type { Network, VenueId } from "../exchanges/venue-types.js";
+import { type ImportVerification } from "./agent-import.js";
 declare const ENV_FILE: string;
 export { ENV_FILE, loadEnvFile, setEnvVar };
 declare function loadEnvFile(): Record<string, string>;
@@ -13,23 +19,109 @@ export declare function validateKey(chain: "solana" | "evm" | "apikey", key: str
     valid: boolean;
     address: string;
 }>;
-export declare function registerInitCommand(program: Command): void;
+/** Names (never values) of legacy private-key variables present in ~/.perp/.env. */
+export declare function legacyEnvKeyNames(): string[];
+/** Trading venues from the registry (no hardcoded list). */
+export declare function setupVenues(): VenueDefinition[];
+/** Resolve one venue id/alias for setup: must be a trading venue with an environment on `network`. */
+export declare function resolveSetupVenue(input: string, network: Network): VenueId;
+/** Parse a comma-separated venue list (ids or aliases), de-duplicated in input order. */
+export declare function parseVenueList(csv: string, network: Network): VenueId[];
+/** Parse `<venue>=<bps>` per-venue slippage overrides; each bps must fit that venue's maxSlippageBps. */
+export declare function parseVenueSlippage(entries: string[], network: Network): {
+    [K in VenueId]?: number;
+};
+export interface SetupSettingsChange {
+    /** null = leave settings.owsActiveWallet unchanged (no master wallet on this computer). */
+    owsActiveWallet: string | null;
+    /** null = leave settings.defaultExchange unchanged. */
+    defaultExchange: VenueId | null;
+    /** null = leave settings.defaultSlippageBps unchanged. */
+    defaultSlippageBps: number | null;
+    /** Per-venue overrides to set (other venues' overrides are left alone). */
+    slippageBps: {
+        [K in VenueId]?: number;
+    };
+}
+/** Write the wizard's choices to ~/.perp/settings.json (metadata only — never secrets). */
+export declare function applySetupSettings(change: SetupSettingsChange): Settings;
+/** Real follow-up commands for the configured venues (all exist in this CLI). */
+export declare function nextStepCommands(venues: VenueId[], network: Network): string[];
+/** Plain-language slippage explanation (design §13.2, §13.10 #3). */
+export declare function slippageExplanation(venues: VenueId[]): string[];
+export type AgentStepResult = {
+    venue: VenueId;
+    status: "approved";
+    agentName: string;
+} | {
+    venue: VenueId;
+    status: "imported";
+    agentName: string;
+    verification: ImportVerification;
+} | {
+    venue: VenueId;
+    status: "skipped";
+    reason: string;
+} | {
+    venue: VenueId;
+    status: "failed";
+    error: StructuredError;
+};
+/** Prompt I/O for the wizard (injectable for tests). askHidden never echoes. */
+export interface Prompter {
+    ask(question: string): Promise<string>;
+    askHidden(question: string): Promise<string>;
+}
 /**
- * Drive `perp setup` end-to-end without TTY. Required:
- *   - --passphrase or OWS_PASSPHRASE env (3-path resolver)
- * Optional:
- *   - --wallet-name (default: "main")
- *   - --default-exchange (must be one of pacifica/hyperliquid/lighter/aster)
- *
- * Side effects:
- *   1. Creates an OWS wallet via createWallet(name, passphrase)
- *   2. Sets settings.owsActiveWallet (if unset) + settings.defaultExchange (if provided)
- *
- * Errors are returned as INVALID_PARAMS / PASSPHRASE_REQUIRED — never via
- * readline. JSON envelope is emitted on stdout when --json is present.
+ * Optional builder-fee step — offered only when settings `builder.<venue>` already holds a
+ * value for a chosen venue (builder fees ship off). Explains the fee and approves only after
+ * an explicit "y" (default No). Never configures a builder itself.
  */
-export declare function runNonInteractiveSetup(opts: {
+export declare function stepBuilder(p: Prompter, venues: VenueId[], network: Network, master: string | null, getPassphrase: () => Promise<string>): Promise<void>;
+/** Interactive `perp setup`. All prompts go through `p`; nothing secret is printed or written to .env. */
+export declare function runInteractiveSetup(p: Prompter, passphraseFlag: string | undefined, preselectedNetwork: Network): Promise<void>;
+export interface SetupOpts {
+    nonInteractive?: boolean;
+    wallet?: string;
     walletName?: string;
     passphrase?: string;
+    /** Root -n/--network (validated by networkOf). */
+    network: Network;
+    venues?: string;
+    defaultVenue?: string;
     defaultExchange?: string;
-}): Promise<void>;
+    slippageBps?: string;
+    slippage: string[];
+    approveAgents?: boolean;
+    yes?: boolean;
+    ondoSecretStdin?: boolean;
+    asterCanSpot?: boolean;
+    lighterApiKeyIndex?: string;
+    lighterRhApiKeyIndex?: string;
+    arcusAccountIndex?: string;
+    /** QFEX account UUID the imported key trades (--import-agents); it is the non-interactive confirmation. */
+    qfexAccountId?: string;
+    /** Venues whose key was created on the exchange website (keys read from stdin, in this order). */
+    importAgents?: string;
+    /** `<venue>=<address>` master / owner public addresses for --import-agents (repeatable). */
+    masterAddress: string[];
+    /** --import-agents venues the user accepts storing UNVERIFIED (pacifica has no read-only check). */
+    allowUnverified?: string;
+    lighterAccountIndex?: string;
+    lighterRhAccountIndex?: string;
+}
+export declare function registerInitCommand(program: Command): void;
+/**
+ * Drive `perp setup` end-to-end without TTY.
+ *
+ * Master wallet: exactly one of --wallet <existing> or --wallet-name <new>.
+ * Passphrase (--passphrase / OWS_PASSPHRASE / stdin) is required to create a
+ * wallet or to sign agent approvals. With --ondo-secret-stdin, stdin carries
+ * the Ondo key, so the passphrase must come from the flag or env.
+ *
+ * Side effects, in order: validate everything → create wallet (if asked) →
+ * write settings (owsActiveWallet, defaultExchange, slippage) → register
+ * agents (only with --approve-agents --yes; a failure on one venue does not
+ * stop the others). Never deposits, withdraws, or trades; never writes .env.
+ */
+export declare function runNonInteractiveSetup(opts: SetupOpts): Promise<void>;