perp-cli 0.12.3 → 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,

package/dist/commands/init.js

@@ -70,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) {
@@ -122,13 +126,24 @@ export function registerInitCommand(program) {
         .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) => {
+        .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 (opts.nonInteractive) {
-            return runNonInteractiveSetup(opts);
+        if (resolvedOpts.nonInteractive) {
+            return runNonInteractiveSetup(resolvedOpts);
         }
         const rl = createInterface({ input: process.stdin, output: process.stdout });
         try {
@@ -161,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;
             }
@@ -174,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(", ")})`));
@@ -230,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) {

package/dist/commands/wallet.js

@@ -326,7 +326,7 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
         .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);
@@ -337,8 +337,15 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
             // > 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: opts.passphrase })) ?? "";
+            const pp = (await resolvePassphrase({ flag: merged.passphrase ?? opts.passphrase })) ?? "";
             const ows = loadOws();
             const w = ows.createWallet(walletName, pp, parseInt(opts.words));
             // Set as active wallet
@@ -402,7 +409,7 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
         .option("--mnemonic", "Import as mnemonic phrase instead of private key")
         .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) {
@@ -486,8 +493,13 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
             // > 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: opts.passphrase })) ?? "";
+            const pp = (await resolvePassphrase({ flag: merged.passphrase ?? opts.passphrase })) ?? "";
             let w;
             if (opts.mnemonic) {
                 w = ows.importWalletMnemonic(opts.name, privateKey, pp);
@@ -598,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.3",
+  "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
 ```