perp-cli 0.12.2 → 0.12.5

package/dist/commands/agent.js

@@ -266,8 +266,15 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
         .option("--ip-whitelist <list>", "Comma-separated IP whitelist (pass empty string to include empty)")
         .option("--api-key-index <n>", "Lighter slot index (4-254). Default: next free slot.")
         .option("--json", "Machine-readable output")
-        .action(async (exchange, opts) => {
+        .action(async (exchange, opts, command) => {
         const useJson = opts.json ?? isJson();
+        // optsWithGlobals() merges parent + subcommand options so --passphrase
+        // works whether placed on `perp --passphrase X wallet agent approve` or
+        // on the subcommand. Commander v13 silently shadows the subcommand flag
+        // when the parent defines an identically-named flag — the visible bug
+        // was approve throwing PASSPHRASE_REQUIRED even with --passphrase set.
+        const mergedOpts = command.optsWithGlobals();
+        const passphraseFlag = mergedOpts.passphrase ?? opts.passphrase;
         // Normalize aliases
         const exchangeNorm = exchange === "lt" ? "lighter"
             : exchange === "hl" ? "hyperliquid"
@@ -314,7 +321,7 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
                 }
                 chosenSlot = n;
             }
-            const passphrase = await resolvePassphrase({ flag: opts.passphrase });
+            const passphrase = await resolvePassphrase({ flag: passphraseFlag });
             if (passphrase === null) {
                 reportErrorAndExit(new PerpError("PASSPHRASE_REQUIRED", "No passphrase provided and stdin is non-TTY", {
                     remediation: "Provide passphrase via --passphrase flag, OWS_PASSPHRASE env var, or stdin pipe",
@@ -377,7 +384,7 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
                     remediation: "Run: perp setup or use --master <name>",
                 }));
             }
-            const passphrase = await resolvePassphrase({ flag: opts.passphrase });
+            const passphrase = await resolvePassphrase({ flag: passphraseFlag });
             if (passphrase === null) {
                 reportErrorAndExit(new PerpError("PASSPHRASE_REQUIRED", "No passphrase provided and stdin is non-TTY", {
                     remediation: "Provide passphrase via --passphrase flag, OWS_PASSPHRASE env var, or stdin pipe",
@@ -438,7 +445,7 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
                     remediation: "Run: perp setup or use --master <name>",
                 }));
             }
-            const passphrase = await resolvePassphrase({ flag: opts.passphrase });
+            const passphrase = await resolvePassphrase({ flag: passphraseFlag });
             if (passphrase === null) {
                 reportErrorAndExit(new PerpError("PASSPHRASE_REQUIRED", "No passphrase provided and stdin is non-TTY", {
                     remediation: "Provide passphrase via --passphrase flag, OWS_PASSPHRASE env var, or stdin pipe",
@@ -526,7 +533,7 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
             canSpot = opts.canSpot ?? false;
             canWithdraw = opts.canWithdraw ?? false;
             // 3-path passphrase resolver (non-TTY path)
-            passphrase = await resolvePassphrase({ flag: opts.passphrase });
+            passphrase = await resolvePassphrase({ flag: passphraseFlag });
             if (passphrase === null) {
                 // TTY but non-wizard (some flags were supplied) — throw PASSPHRASE_REQUIRED
                 reportErrorAndExit(new PerpError("PASSPHRASE_REQUIRED", "No passphrase provided and stdin is non-TTY or wizard skipped", {
@@ -666,8 +673,11 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
         .option("--force", "Skip Aster POST, only clear local state")
         .option("--passphrase <pp>", "Master OWS passphrase")
         .option("--json", "Machine-readable output")
-        .action(async (exchange, agentName, opts) => {
+        .action(async (exchange, agentName, opts, command) => {
         const useJson = opts.json ?? isJson();
+        // optsWithGlobals(): see wallet agent approve for full rationale.
+        const mergedOpts = command.optsWithGlobals();
+        const passphraseFlag = mergedOpts.passphrase ?? opts.passphrase;
         try {
             // Step 1: Check local meta (idempotent — absent = already revoked)
             const meta = getAgent(exchange, agentName);
@@ -683,7 +693,7 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
             }
             if (!opts.force) {
                 // Step 2: Resolve passphrase
-                const passphrase = await resolvePassphrase({ flag: opts.passphrase });
+                const passphrase = await resolvePassphrase({ flag: passphraseFlag });
                 if (passphrase === null) {
                     throw new PerpError("PASSPHRASE_REQUIRED", "No passphrase provided and stdin is non-TTY", {
                         remediation: "Provide passphrase via --passphrase flag, OWS_PASSPHRASE env var, or stdin pipe",
@@ -791,8 +801,11 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
         .option("--can-withdraw", "Allow withdrawals (default: inherit or off)")
         .option("--no-can-withdraw", "Disallow withdrawals")
         .option("--json", "Machine-readable output")
-        .action(async (exchange, oldAgentNameArg, opts) => {
+        .action(async (exchange, oldAgentNameArg, opts, command) => {
         const useJson = opts.json ?? isJson();
+        // optsWithGlobals(): see wallet agent approve for full rationale.
+        const mergedOpts = command.optsWithGlobals();
+        const passphraseFlag = mergedOpts.passphrase ?? opts.passphrase;
         try {
             // Determine which agent to rotate
             const agentNameToRotate = oldAgentNameArg ?? opts.agentName ?? getAgent(exchange)?.agentName;
@@ -802,7 +815,7 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
                 });
             }
             // Resolve passphrase early (needed for both revoke and approve phases)
-            const passphrase = await resolvePassphrase({ flag: opts.passphrase });
+            const passphrase = await resolvePassphrase({ flag: passphraseFlag });
             if (passphrase === null) {
                 throw new PerpError("PASSPHRASE_REQUIRED", "No passphrase provided and stdin is non-TTY", {
                     remediation: "Provide passphrase via --passphrase flag, OWS_PASSPHRASE env var, or stdin pipe",
@@ -1006,11 +1019,14 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
         .option("--account-index <n>", "Account index (Lighter only)")
         .option("--passphrase <pp>", "Master OWS passphrase (Aster/PAC). Falls back to OWS_PASSPHRASE env.")
         .option("--json", "Machine-readable output")
-        .action(async (exchange, agentName, opts) => {
+        .action(async (exchange, agentName, opts, command) => {
         const useJson = opts.json ?? isJson();
         const ts = new Date().toISOString();
+        // optsWithGlobals(): see wallet agent approve for full rationale.
+        const mergedOpts = command.optsWithGlobals();
+        const passphraseFlag = mergedOpts.passphrase ?? opts.passphrase;
         // Resolve passphrase via 3-path: flag > env > (no stdin prompt in verify)
-        const passphrase = opts.passphrase ?? process.env["OWS_PASSPHRASE"] ?? "";
+        const passphrase = passphraseFlag ?? process.env["OWS_PASSPHRASE"] ?? "";
         const verifyOpts = {
             agentName,
             master: opts.master,
@@ -1157,6 +1173,56 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
         }
     });
 }
+// ── Pre-venue rollback helpers ───────────────────────────────────────────────
+//
+// When `wallet agent approve <dex>` fails BEFORE the venue accepted the agent
+// (HTTP error, body-code rejection, parse error, network drop), the locally
+// generated `agent-<dex>-<master>` OWS wallet is orphaned in `~/.ows/wallets/`.
+// Retry collides with "wallet name already exists". These helpers auto-delete
+// the orphan and produce an actionable remediation string.
+//
+// Post-venue (persist-only) failures must NOT use these — those leave a
+// status:"partial" record so the user can still revoke venue-side state.
+/**
+ * Best-effort delete of an orphan local OWS wallet. Returns true on success,
+ * false on failure (also logs the failure to stderr per SSOT Rule #2: rollback
+ * failures must not silently mask the original error). The caller threads the
+ * boolean into the user-visible remediation.
+ */
+function tryDeleteOrphanWallet(ows, walletName) {
+    if (!walletName)
+        return false;
+    try {
+        ows.deleteWallet(walletName);
+        return true;
+    }
+    catch (cleanupErr) {
+        // Don't swallow — surface the rollback failure on stderr so the user can
+        // see exactly what's stuck. Original error still propagates from caller.
+        process.stderr.write(`[warn] failed to clean up orphan wallet "${walletName}": ${cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)}\n`);
+        return false;
+    }
+}
+/**
+ * Build an actionable remediation message for pre-venue approve failures.
+ * On clean rollback: tells the user to deposit + retry the canonical
+ * `wallet agent approve <dex> --master <master>` command (no manual steps).
+ * On rollback failure: tells the user to manually delete the orphan wallet
+ * before retrying. The agent address is appended for diagnostic purposes
+ * (some users may need it for the venue UI).
+ */
+function buildPreVenueRemediation(opts) {
+    const { cleanupOk, dex, masterName, agentAddress, hint } = opts;
+    const retry = `perp wallet agent approve ${dex} --master ${masterName}`;
+    const head = cleanupOk
+        ? `Local agent wallet cleaned up. Deposit funds and retry: ${retry}`
+        : `Manual cleanup required — local agent wallet may still exist. Run: perp wallet remove agent-${dex === "hyperliquid" ? "hl" : dex === "pacifica" ? "pac" : "aster"}-${masterName}, then retry: ${retry}`;
+    const parts = [head];
+    if (hint)
+        parts.push(hint);
+    parts.push(`Agent address (diagnostic): ${agentAddress}`);
+    return parts.join(" | ");
+}
 /**
  * Core approve flow: Steps 2-12 (OWS wallet + policy + api-key + EIP-712 + Aster POST + persist).
  * Caller MUST hold the exchange lock before calling this function.
@@ -1233,13 +1299,15 @@ async function runApproveFlow(opts) {
         });
         if (!builderRes.ok) {
             const errText = await builderRes.text().catch(() => "");
-            // Aster builder POST failed — rollback api key (no Aster agent registered yet)
+            // Aster builder POST failed — pre-venue (no Aster agent registered yet).
+            // Rollback both: api key + orphan local OWS wallet.
             if (owsApiKeyId) {
                 try {
                     ows.revokeApiKey(owsApiKeyId);
                 }
                 catch { /* best effort */ }
             }
+            tryDeleteOrphanWallet(ows, agentWalletName);
             throw new PerpError("EXCHANGE_ERROR", `Aster approveBuilder failed (${builderRes.status}): ${errText.slice(0, 200)}`, {
                 remediation: "Check builder address and max-fee-rate parameters",
             });
@@ -1253,6 +1321,7 @@ async function runApproveFlow(opts) {
                 }
                 catch { /* best effort */ }
             }
+            tryDeleteOrphanWallet(ows, agentWalletName);
             const errMsg = builderResp.msg ?? builderResp.message ?? String(builderResp.code);
             throw new PerpError("EXCHANGE_ERROR", `Aster approveBuilder failed: ${errMsg}`, {
                 remediation: "Check builder address and max-fee-rate parameters",
@@ -1307,30 +1376,37 @@ async function runApproveFlow(opts) {
             asterPostSucceeded = true;
         }
         else {
-            // Aster POST body indicated failure — rollback api key (Aster did not register)
+            // Aster POST body indicated failure — pre-venue (Aster did not register).
+            // Rollback both api key + orphan local OWS wallet.
             if (owsApiKeyId) {
                 try {
                     ows.revokeApiKey(owsApiKeyId);
                 }
                 catch { /* best effort */ }
             }
+            const cleanupOk = tryDeleteOrphanWallet(ows, agentWalletName);
             const errMsg = resp.msg ?? resp.message ?? String(resp.code);
             throw new PerpError("APPROVE_PARTIAL", `Aster approveAgent failed: ${errMsg}`, {
-                remediation: `Agent address for cleanup: ${agentEvmAddress}`,
+                remediation: buildPreVenueRemediation({
+                    cleanupOk, dex: "aster", masterName, agentAddress: agentEvmAddress,
+                }),
             });
         }
     }
     else {
-        // HTTP error — rollback api key (Aster did not register)
+        // HTTP error — pre-venue (Aster did not register). Rollback both.
         if (owsApiKeyId) {
             try {
                 ows.revokeApiKey(owsApiKeyId);
             }
             catch { /* best effort */ }
         }
+        const cleanupOk = tryDeleteOrphanWallet(ows, agentWalletName);
         const errText = await agentRes.text().catch(() => "");
         throw new PerpError("APPROVE_PARTIAL", `Aster approveAgent failed (${agentRes.status}): ${errText.slice(0, 200)}`, {
-            remediation: `Agent address for cleanup: ${agentEvmAddress}`,
+            remediation: buildPreVenueRemediation({
+                cleanupOk, dex: "aster", masterName, agentAddress: agentEvmAddress,
+            }),
         });
     }
     // Step 12: Persist agent meta
@@ -1551,13 +1627,26 @@ async function runHlApproveFlow(opts) {
         resp = JSON.parse(text);
     }
     catch {
+        // Pre-venue parse failure — Hyperliquid did NOT register the agent.
+        // Roll back the orphan local OWS wallet so retry doesn't collide with
+        // "wallet name already exists". Errors during cleanup must NOT mask the
+        // original network/parse error (SSOT Rule #2).
+        const cleanupOk = tryDeleteOrphanWallet(ows, agentWalletName);
         throw new PerpError("EXCHANGE_ERROR", `HL exchange API parse error (${agentRes.status}): ${text.slice(0, 200)}`, {
-            remediation: "Check Hyperliquid API status",
+            remediation: buildPreVenueRemediation({
+                cleanupOk, dex: "hyperliquid", masterName, agentAddress: agentEvmAddress,
+                hint: "Check Hyperliquid API status",
+            }),
         });
     }
     if (resp?.status === "err") {
+        // Pre-venue rejection — Hyperliquid did NOT register the agent. Roll
+        // back the orphan local OWS wallet so retry can proceed cleanly.
+        const cleanupOk = tryDeleteOrphanWallet(ows, agentWalletName);
         throw new PerpError("APPROVE_PARTIAL", `HL approveAgent failed: ${typeof resp.response === "string" ? resp.response : JSON.stringify(resp)}`, {
-            remediation: `Agent address for cleanup: ${agentEvmAddress}`,
+            remediation: buildPreVenueRemediation({
+                cleanupOk, dex: "hyperliquid", masterName, agentAddress: agentEvmAddress,
+            }),
         });
     }
     // Step 6: Persist
@@ -1682,24 +1771,36 @@ async function runPacApproveFlow(opts) {
             // Pacifica REST envelope: success === true OR explicit data field
             if (resp.success === false || resp.error) {
                 const errMsg = typeof resp.error === "string" ? resp.error : JSON.stringify(resp);
+                // Pre-venue rejection — Pacifica did NOT register the agent.
+                const cleanupOk = tryDeleteOrphanWallet(ows, agentWalletName);
                 throw new PerpError("APPROVE_PARTIAL", `Pacifica bind_agent_wallet failed: ${errMsg}`, {
-                    remediation: `Agent address for cleanup: ${agentSolanaAddress}`,
+                    remediation: buildPreVenueRemediation({
+                        cleanupOk, dex: "pacifica", masterName, agentAddress: agentSolanaAddress,
+                    }),
                 });
             }
             pacPostSucceeded = true;
         }
         else {
             const errText = await httpRes.text().catch(() => "");
+            // Pre-venue rejection — Pacifica did NOT register the agent.
+            const cleanupOk = tryDeleteOrphanWallet(ows, agentWalletName);
             throw new PerpError("APPROVE_PARTIAL", `Pacifica bind_agent_wallet failed (${httpRes.status}): ${errText.slice(0, 200)}`, {
-                remediation: `Agent address for cleanup: ${agentSolanaAddress}`,
+                remediation: buildPreVenueRemediation({
+                    cleanupOk, dex: "pacifica", masterName, agentAddress: agentSolanaAddress,
+                }),
             });
         }
     }
     catch (httpErr) {
         if (httpErr instanceof PerpError)
             throw httpErr;
+        // Network-level failure — Pacifica did NOT register the agent.
+        const cleanupOk = tryDeleteOrphanWallet(ows, agentWalletName);
         throw new PerpError("APPROVE_PARTIAL", `Pacifica bind_agent_wallet network error: ${httpErr instanceof Error ? httpErr.message : String(httpErr)}`, {
-            remediation: `Agent address for cleanup: ${agentSolanaAddress}`,
+            remediation: buildPreVenueRemediation({
+                cleanupOk, dex: "pacifica", masterName, agentAddress: agentSolanaAddress,
+            }),
         });
     }
     // Step 5: Persist

package/dist/commands/init.d.ts

@@ -14,3 +14,22 @@ export declare function validateKey(chain: "solana" | "evm" | "apikey", key: str
     address: string;
 }>;
 export declare function registerInitCommand(program: Command): void;
+/**
+ * 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.
+ */
+export declare function runNonInteractiveSetup(opts: {
+    walletName?: string;
+    passphrase?: string;
+    defaultExchange?: string;
+}): Promise<void>;

package/dist/commands/init.js

@@ -3,6 +3,10 @@ import { createInterface } from "readline";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { resolve } from "path";
 import { loadSettings, saveSettings } from "../settings.js";
+import { PerpError } from "../errors.js";
+import { jsonOk, jsonError, printJson } from "../utils.js";
+import { resolvePassphrase } from "../agent-wallet/passphrase.js";
+import { loadOws } from "../signer/ows-loader.js";
 const PERP_DIR = resolve(process.env.HOME || "~", ".perp");
 const ENV_FILE = resolve(PERP_DIR, ".env");
 // ── .env helpers ──────────────────────────────────────────────
@@ -66,11 +70,15 @@ function askChoice(rl, question, choices) {
     });
 }
 // ── Exchange → env var mapping ────────────────────────────────
+// Aster removed in v0.12.4: legacy HMAC API-key signing path was retired in
+// Plan v3.0. New users must onboard via `perp wallet agent approve aster`
+// (off-chain agent wallet, same flow as HL/PAC/LT). The setup wizard
+// surfaces a redirect when Aster is selected; `wallet set aster <key>`
+// throws INVALID_PARAMS pointing at the agent flow.
 export const EXCHANGE_ENV_MAP = {
     pacifica: { envKey: "PACIFICA_PRIVATE_KEY", chain: "solana", label: "Pacifica (Solana)" },
     hyperliquid: { envKey: "HL_PRIVATE_KEY", chain: "evm", label: "Hyperliquid (EVM)" },
     lighter: { envKey: "LIGHTER_PRIVATE_KEY", chain: "evm", label: "Lighter (EVM)" },
-    aster: { envKey: "ASTER_API_KEY", envKeySecret: "ASTER_API_SECRET", chain: "apikey", label: "Aster (BNB Chain)" },
 };
 // ── Validate keys ─────────────────────────────────────────────
 export async function validateKey(chain, key) {
@@ -109,12 +117,34 @@ export async function validateKey(chain, key) {
 }
 // ── Commands ──────────────────────────────────────────────────
 export function registerInitCommand(program) {
-    // ── perp setup (interactive) ──
+    // ── perp setup (interactive + non-interactive) ──
     program
         .command("setup")
         .alias("init")
-        .description("Interactive setup wizard — configure keys & default exchange")
-        .action(async () => {
+        .description("Setup wizard — interactive by default, scriptable with --non-interactive")
+        .option("--non-interactive", "Run without prompts; requires --passphrase or OWS_PASSPHRASE env")
+        .option("--wallet-name <name>", "OWS wallet alias to create (default: 'main')")
+        .option("--passphrase <pp>", "OWS vault passphrase (fallback: OWS_PASSPHRASE env / stdin)")
+        .option("--default-exchange <name>", "Default exchange (pacifica/hyperliquid/lighter/aster)")
+        .action(async (opts, command) => {
+        // optsWithGlobals() merges parent + subcommand options so --passphrase
+        // works whether placed on `perp --passphrase X setup` (parent) or
+        // `perp setup --passphrase X` (subcommand). Commander v13 silently
+        // shadows the subcommand flag when the parent defines an identically
+        // named flag — the visible bug was non-interactive setup throwing
+        // PASSPHRASE_REQUIRED with --passphrase set on the subcommand.
+        const mergedOpts = command.optsWithGlobals();
+        const resolvedOpts = {
+            ...opts,
+            passphrase: mergedOpts.passphrase ?? opts.passphrase,
+        };
+        // Non-interactive mode: skip all readline prompts, drive everything from
+        // flags + OWS_PASSPHRASE env. This is the agent-friendly onboarding path
+        // (CI / Docker / scripted init) — see plan v3.0 "agent-friendly five
+        // guarantees" P1 (no-prompt) and P3 (passphrase 3-path).
+        if (resolvedOpts.nonInteractive) {
+            return runNonInteractiveSetup(resolvedOpts);
+        }
         const rl = createInterface({ input: process.stdin, output: process.stdout });
         try {
             console.log(chalk.cyan.bold("\n  perp-cli Setup Wizard\n"));
@@ -146,12 +176,28 @@ export function registerInitCommand(program) {
             console.log(`    1) ${chalk.cyan("Pacifica")}    ${chalk.gray("— Solana perps (USDC on Solana)")}`);
             console.log(`    2) ${chalk.cyan("Hyperliquid")} ${chalk.gray("— EVM perps (USDC on Arbitrum)")}`);
             console.log(`    3) ${chalk.cyan("Lighter")}     ${chalk.gray("— EVM perps (USDC on Ethereum/Arb)")}`);
-            console.log(`    4) ${chalk.cyan("Aster")}       ${chalk.gray("— BNB Chain perps (API key + secret)")}`);
+            console.log(`    4) ${chalk.cyan("Aster")}       ${chalk.gray("— BNB Chain perps (use 'wallet agent approve aster')")}`);
             console.log();
             const exchangeChoice = await ask(rl, "  Which exchange(s)? (1,2,3,4 or 'all'): ");
-            const selected = parseExchangeChoice(exchangeChoice);
+            const selectedRaw = parseExchangeChoice(exchangeChoice);
+            // v0.12.4: legacy Aster HMAC API-key path is removed. The wizard can
+            // no longer collect ASTER_API_KEY/ASTER_API_SECRET — Aster onboarding
+            // is now exclusively via `perp wallet agent approve aster --master`.
+            // Print a redirect and drop Aster from the env-write set.
+            const asterRequested = selectedRaw.includes("aster");
+            const selected = selectedRaw.filter((e) => e !== "aster");
+            if (asterRequested) {
+                console.log(chalk.yellow.bold("\n  Aster onboarding is via agent wallet (no API keys):"));
+                console.log(`    ${chalk.green("perp wallet agent approve aster --master <name>")}`);
+                console.log(chalk.gray("  Run that after this wizard completes.\n"));
+            }
             if (selected.length === 0) {
-                console.log(chalk.red("\n  No exchanges selected.\n"));
+                if (asterRequested) {
+                    console.log(chalk.gray("  No additional exchanges to configure here. See the Aster instructions above.\n"));
+                }
+                else {
+                    console.log(chalk.red("\n  No exchanges selected.\n"));
+                }
                 rl.close();
                 return;
             }
@@ -159,7 +205,6 @@ export function registerInitCommand(program) {
             // EVM exchanges can share the same key
             const evmExchanges = selected.filter((e) => EXCHANGE_ENV_MAP[e].chain === "evm");
             const solExchanges = selected.filter((e) => EXCHANGE_ENV_MAP[e].chain === "solana");
-            const apikeyExchanges = selected.filter((e) => EXCHANGE_ENV_MAP[e].chain === "apikey");
             const newEnv = { ...env };
             if (evmExchanges.length > 0) {
                 console.log(chalk.cyan.bold("\n  EVM Private Key") + chalk.gray(` (for ${evmExchanges.join(", ")})`));
@@ -215,34 +260,9 @@ export function registerInitCommand(program) {
                     }
                 }
             }
-            if (apikeyExchanges.length > 0) {
-                for (const ex of apikeyExchanges) {
-                    const info = EXCHANGE_ENV_MAP[ex];
-                    console.log(chalk.cyan.bold(`\n  ${info.label} API Credentials`));
-                    const apiKey = await ask(rl, `  ${info.label} API key: `);
-                    if (!apiKey) {
-                        console.log(chalk.gray("  Skipped."));
-                        continue;
-                    }
-                    const { valid, address } = await validateKey("apikey", apiKey);
-                    if (!valid) {
-                        console.log(chalk.red("  Invalid API key (must be at least 16 chars), skipped."));
-                        continue;
-                    }
-                    newEnv[info.envKey] = apiKey;
-                    console.log(`  ${chalk.green("OK")} ${chalk.gray(address)}`);
-                    if (info.envKeySecret) {
-                        const secret = await ask(rl, `  ${info.label} API secret: `);
-                        if (secret) {
-                            newEnv[info.envKeySecret] = secret;
-                            console.log(`  ${chalk.green("OK")} secret saved`);
-                        }
-                        else {
-                            console.log(chalk.yellow("  No secret provided — some operations may fail."));
-                        }
-                    }
-                }
-            }
+            // v0.12.4: API-key (Aster legacy HMAC) onboarding removed from the
+            // wizard. Aster users follow the redirect above to
+            // `perp wallet agent approve aster`.
             // Default exchange
             const settings = loadSettings();
             if (selected.length === 1) {
@@ -304,3 +324,109 @@ function parseExchangeChoice(input) {
     }
     return [...new Set(exchanges)];
 }
+// ── Non-interactive setup (agent / CI / Docker) ──────────────────────────────
+const VALID_EXCHANGES = ["pacifica", "hyperliquid", "lighter", "aster"];
+/**
+ * Test seam: emit JSON envelopes when the global --json flag is present.
+ * Mirrors the inline pattern used elsewhere (see src/index.ts:87) instead of
+ * wiring isJson() through registerInitCommand for one call site.
+ */
+function setupIsJson() {
+    return process.argv.includes("--json");
+}
+/**
+ * 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.
+ */
+export async function runNonInteractiveSetup(opts) {
+    const isJson = setupIsJson();
+    try {
+        // Validate --default-exchange shape early so users hit a precise error
+        // before passphrase resolution.
+        if (opts.defaultExchange !== undefined &&
+            !VALID_EXCHANGES.includes(opts.defaultExchange)) {
+            throw new PerpError("INVALID_PARAMS", `Invalid --default-exchange "${opts.defaultExchange}"`, {
+                remediation: `Use one of: ${VALID_EXCHANGES.join(", ")}`,
+            });
+        }
+        // Resolve passphrase. resolvePassphrase already throws PASSPHRASE_REQUIRED
+        // when stdin is non-TTY and nothing was provided. In TTY mode it returns
+        // null — non-interactive mode must NOT fall back to a prompt.
+        const resolved = await resolvePassphrase({ flag: opts.passphrase });
+        if (resolved === null) {
+            throw new PerpError("PASSPHRASE_REQUIRED", "Non-interactive setup requires a passphrase", {
+                remediation: "Provide --passphrase <pp> or set OWS_PASSPHRASE env var",
+            });
+        }
+        const pp = resolved;
+        const walletName = opts.walletName ?? "main";
+        // Create OWS wallet
+        const ows = loadOws();
+        const w = ows.createWallet(walletName, pp);
+        // Update settings
+        const settings = loadSettings();
+        if (!settings.owsActiveWallet) {
+            settings.owsActiveWallet = walletName;
+        }
+        if (opts.defaultExchange) {
+            settings.defaultExchange = opts.defaultExchange;
+        }
+        saveSettings(settings);
+        if (isJson) {
+            printJson(jsonOk({
+                walletName: w.name,
+                walletId: w.id,
+                accounts: w.accounts,
+                owsActiveWallet: settings.owsActiveWallet,
+                defaultExchange: settings.defaultExchange ?? null,
+                mode: "non-interactive",
+            }));
+            return;
+        }
+        console.log(chalk.cyan.bold("\n  perp-cli Setup (non-interactive) — Done\n"));
+        console.log(`  Wallet:           ${chalk.white.bold(w.name)}`);
+        console.log(`  Active wallet:    ${chalk.cyan(settings.owsActiveWallet)}`);
+        if (settings.defaultExchange) {
+            console.log(`  Default exchange: ${chalk.cyan(settings.defaultExchange)}`);
+        }
+        console.log(chalk.gray(`\n  Vault: ~/.ows/ (AES-256-GCM encrypted)\n`));
+    }
+    catch (err) {
+        if (isJson) {
+            if (err instanceof PerpError) {
+                printJson(jsonError(err.structured.code, err.structured.message, {
+                    ...(err.structured.remediation
+                        ? { details: { remediation: err.structured.remediation } }
+                        : {}),
+                }));
+            }
+            else {
+                const msg = err instanceof Error ? err.message : String(err);
+                printJson(jsonError("UNKNOWN", msg));
+            }
+            process.exitCode = 1;
+            return;
+        }
+        if (err instanceof PerpError) {
+            console.error(chalk.red(`\n  Error [${err.structured.code}]: ${err.structured.message}`));
+            if (err.structured.remediation) {
+                console.error(chalk.gray(`  Remediation: ${err.structured.remediation}\n`));
+            }
+        }
+        else {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(chalk.red(`\n  Error: ${msg}\n`));
+        }
+        process.exitCode = 1;
+    }
+}

package/dist/commands/wallet.js

@@ -324,16 +324,30 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
         .description("Generate a new wallet (OWS encrypted vault, multi-chain)")
         .option("--words <count>", "Mnemonic word count (12 or 24)", "12")
         .option("--show-mnemonic", "Display the mnemonic phrase (CAUTION)")
+        .option("--passphrase <pp>", "Master OWS passphrase (fallback: OWS_PASSPHRASE env / stdin)")
         .option("--legacy <chain>", "Legacy mode: generate solana or evm key (unencrypted)")
-        .action(async (name, opts) => {
+        .action(async (name, opts, command) => {
         // Legacy mode for backward compat
         if (opts.legacy) {
             return _legacyGenerate(opts.legacy, name, isJson);
         }
         const walletName = name || "default";
         try {
+            // Resolve vault passphrase via the standard 3-path resolver (--passphrase
+            // > OWS_PASSPHRASE env > stdin pipe). When stdin is a TTY and nothing was
+            // provided, the resolver returns null; fall back to "" to preserve the
+            // historical "no passphrase" default for interactive use.
+            //
+            // optsWithGlobals() merges parent + subcommand options, so --passphrase
+            // works whether placed on `perp --passphrase X subcmd` (parent) or
+            // `perp subcmd --passphrase X` (subcommand). Without this, Commander v13
+            // shadows the subcommand flag with the parent's same-named flag and
+            // opts.passphrase is always undefined.
+            const merged = command.optsWithGlobals();
+            const { resolvePassphrase } = await import("../agent-wallet/passphrase.js");
+            const pp = (await resolvePassphrase({ flag: merged.passphrase ?? opts.passphrase })) ?? "";
             const ows = loadOws();
-            const w = ows.createWallet(walletName, "", parseInt(opts.words));
+            const w = ows.createWallet(walletName, pp, parseInt(opts.words));
             // Set as active wallet
             const { loadSettings: ls, saveSettings: ss } = await import("../settings.js");
             const settings = ls();
@@ -393,9 +407,9 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
         .option("--evm <hex>", "EVM (secp256k1) private key — use with --solana to import both curves")
         .option("--solana <key>", "Solana (ed25519) private key — accepts hex (64), base58 (Phantom export), or JSON byte array. Use with --evm to import both curves")
         .option("--mnemonic", "Import as mnemonic phrase instead of private key")
-        .option("--passphrase <pp>", "OWS vault encryption passphrase (default: empty / OWS_PASSPHRASE env)")
+        .option("--passphrase <pp>", "Master OWS passphrase (fallback: OWS_PASSPHRASE env / stdin)")
         .option("--legacy <chain>", "Legacy mode: import to wallets.json (solana or evm)")
-        .action(async (privateKey, opts) => {
+        .action(async (privateKey, opts, command) => {
         // Legacy mode (positional only)
         if (opts.legacy) {
             if (!privateKey) {
@@ -475,9 +489,17 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
                     throw new Error(`Invalid Solana key — expected hex (64 chars), base58 (Phantom export), or JSON byte array. Inner: ${msg}`);
                 }
             };
-            // Resolve vault passphrase (precedence: --passphrase > OWS_PASSPHRASE env > "")
-            const pp = opts.passphrase
-                ?? (("OWS_PASSPHRASE" in process.env) ? (process.env["OWS_PASSPHRASE"] ?? "") : "");
+            // Resolve vault passphrase via the standard 3-path resolver (--passphrase
+            // > OWS_PASSPHRASE env > stdin pipe). When stdin is a TTY and nothing was
+            // provided, the resolver returns null; fall back to "" to preserve the
+            // historical "no passphrase" default for interactive use.
+            //
+            // optsWithGlobals() merges parent + subcommand options — see the
+            // wallet generate action for context. Without it, the parent program's
+            // --passphrase shadows the subcommand's same-named flag.
+            const merged = command.optsWithGlobals();
+            const { resolvePassphrase } = await import("../agent-wallet/passphrase.js");
+            const pp = (await resolvePassphrase({ flag: merged.passphrase ?? opts.passphrase })) ?? "";
             let w;
             if (opts.mnemonic) {
                 w = ows.importWalletMnemonic(opts.name, privateKey, pp);
@@ -588,17 +610,32 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
         .description("Set private key for an exchange")
         .option("--default", "Also set as default exchange")
         .action(async (exchange, key, opts) => {
-        // Resolve alias (hl → hyperliquid, pac → pacifica, lt → lighter)
-        const aliases = { hl: "hyperliquid", pac: "pacifica", lt: "lighter" };
+        // Resolve alias (hl → hyperliquid, pac → pacifica, lt → lighter, ast → aster)
+        const aliases = { hl: "hyperliquid", pac: "pacifica", lt: "lighter", ast: "aster" };
         const resolved = aliases[exchange.toLowerCase()] || exchange.toLowerCase();
+        // v0.12.4: Aster legacy HMAC API-key path is removed entirely. Plan v3.0
+        // de-wired the runtime/signing surface but left the wallet set entry
+        // accepting keys that no longer drive any signing path. Fail loudly
+        // (SSOT Rule #2) and point at the agent flow.
+        if (resolved === "aster") {
+            const msg = "'wallet set aster' is removed in v0.13. Use 'wallet agent approve aster' instead.";
+            const remediation = "perp wallet agent approve aster --master <wallet>";
+            if (isJson()) {
+                const { jsonError } = await import("../utils.js");
+                return printJson(jsonError("INVALID_PARAMS", msg, { details: { remediation } }));
+            }
+            console.error(chalk.red(`\n  ${msg}`));
+            console.error(chalk.gray(`  Run: ${remediation}\n`));
+            process.exit(1);
+        }
         const info = EXCHANGE_ENV_MAP[resolved];
         if (!info) {
             if (isJson()) {
                 const { jsonError } = await import("../utils.js");
-                return printJson(jsonError("INVALID_PARAMS", `Unknown exchange: ${exchange}. Use: pacifica, hyperliquid, lighter, aster (or hl, pac, lt, ast)`));
+                return printJson(jsonError("INVALID_PARAMS", `Unknown exchange: ${exchange}. Use: pacifica, hyperliquid, lighter (or hl, pac, lt). For Aster: 'perp wallet agent approve aster'.`));
             }
             console.error(chalk.red(`\n  Unknown exchange: ${exchange}`));
-            console.error(chalk.gray(`  Use: pacifica, hyperliquid, lighter, aster (or hl, pac, lt, ast)\n`));
+            console.error(chalk.gray(`  Use: pacifica, hyperliquid, lighter (or hl, pac, lt). For Aster: 'perp wallet agent approve aster'.\n`));
             process.exit(1);
         }
         const { valid, address } = await validateKey(info.chain, key);

package/dist/config.js

@@ -74,11 +74,15 @@ export async function loadPrivateKey(exchange, pkOverride, walletName) {
         // settings module not available, skip
     }
     // 3. Exchange-specific env vars
+    // v0.12.4: Aster's ASTER_API_KEY entry is removed — the legacy HMAC
+    // signing path was retired in Plan v3.0. Aster onboarding is now via
+    // `perp wallet agent approve aster` (off-chain agent wallet); the runtime
+    // adapter pulls credentials from the agent store, not the env.
     const envMap = {
         pacifica: ["PACIFICA_PRIVATE_KEY", "pk"],
         hyperliquid: ["HYPERLIQUID_PRIVATE_KEY", "HL_PRIVATE_KEY"],
         lighter: ["LIGHTER_PRIVATE_KEY"],
-        aster: ["ASTER_API_KEY"],
+        aster: [],
     };
     for (const envVar of envMap[exchange]) {
         if (process.env[envVar])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perp-cli",
-  "version": "0.12.2",
+  "version": "0.12.5",
   "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter, Aster",
   "bin": {
     "perp": "dist/index.js",
@@ -18,7 +18,8 @@
     "test": "vitest run --exclude '**/integration/**'",
     "test:integration": "vitest run -c vitest.integration.config.ts",
     "test:all": "vitest run",
-    "prepublishOnly": "pnpm run build"
+    "sync-skill-version": "node scripts/sync-skill-version.mjs",
+    "prepublishOnly": "node scripts/sync-skill-version.mjs && pnpm run build"
   },
   "keywords": [
     "pacifica",

package/skills/perp-cli/SKILL.md

@@ -5,7 +5,7 @@ allowed-tools: "Bash(perp:*), Bash(npx perp-cli:*), Bash(npx -y perp-cli:*)"
 license: MIT
 metadata:
   author: hypurrquant
-  version: "0.7.7"
+  version: "0.12.5"
 ---
 
 # perp-cli Agent Guide
@@ -41,7 +41,7 @@ Multi-DEX perpetual futures CLI + MCP server — Pacifica (Solana), Hyperliquid
 ## Install
 
 ```bash
-perp --version 2>/dev/null  # check if exists (must be >= 0.7.7)
+perp --version 2>/dev/null  # check if exists (must be >= 0.12.5)
 npm install -g perp-cli@latest 2>/dev/null || npx -y perp-cli@latest --json --version
 ```