feat: introduce standalone PMXT CLI

Author: realfishsam

.github/workflows/publish.yml

@@ -118,6 +118,11 @@ jobs:
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
+      - name: Publish @pmxt/cli
+        run: npm publish --workspace=@pmxt/cli --provenance --access public --tag ${{ steps.get_version.outputs.npm_tag }}
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
   publish-python:
     name: Publish pmxt (Python)
     runs-on: ubuntu-latest
@@ -243,6 +248,7 @@ jobs:
             **npm:**
             ```bash
             npm install pmxtjs@${{ steps.get_version.outputs.version }}
+            npm install -g @pmxt/cli@${{ steps.get_version.outputs.version }}
             ```
 
             **PyPI:**
@@ -252,6 +258,7 @@ jobs:
 
             ## Links
             - [npm: pmxtjs](https://www.npmjs.com/package/pmxtjs/v/${{ steps.get_version.outputs.version }})
+            - [npm: @pmxt/cli](https://www.npmjs.com/package/@pmxt/cli/v/${{ steps.get_version.outputs.version }})
             - [npm: pmxt-core](https://www.npmjs.com/package/pmxt-core/v/${{ steps.get_version.outputs.version }})
             - [PyPI: pmxt](https://pypi.org/project/pmxt/${{ steps.get_version.outputs.version }}/)
           prerelease: ${{ steps.get_version.outputs.is_prerelease }}

.github/workflows/test-publish.yml

@@ -10,7 +10,7 @@ on:
 
 jobs:
   test-js-packages:
-    name: Test JS Packages (Core & SDK)
+    name: Test JS Packages (Core, SDK & CLI)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -52,6 +52,9 @@ jobs:
       - name: Dry Run Publish pmxtjs
         run: npm publish --workspace=pmxtjs --dry-run
 
+      - name: Dry Run Publish @pmxt/cli
+        run: npm publish --workspace=@pmxt/cli --dry-run
+
   test-python-package:
     name: Test Python Package
     runs-on: ubuntu-latest

changelog.md

@@ -2,6 +2,27 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.45.0] - 2026-05-25
+
+### Added
+
+- **CLI**: Introduced the standalone `@pmxt/cli` package with the `pmxt` executable. It can be installed globally with `npm install -g @pmxt/cli` or run with `npx @pmxt/cli`.
+- **CLI commands**: Added command coverage for the documented PMXT API surface, including markets, events, order books, trades, balances, positions, order build/create/submit/cancel/get, router matches, data feeds, feed streaming, WebSocket watch commands, enterprise commands, and local server management.
+- **CLI aliases**: Added an explicit alias layer for exchange-first UX such as `pmxt polymarket fetchMarkets --query Trump`, direct camelCase method aliases such as `pmxt fetchMarkets`, and space-separated command groups such as `pmxt order create` and `pmxt feed fetchTicker`.
+- **CLI auth**: Added `pmxt auth` commands for PMXT API keys and exchange credentials. Commands support saved auth, environment variables, and one-shot flags so automation can avoid interactive prompts.
+- **CLI packaging**: Added a dedicated `sdks/cli` workspace, oclif command discovery, package validation, and npm package metadata for publishing `@pmxt/cli`.
+
+### Changed
+
+- **TypeScript SDK**: Decoupled the command-line interface from `pmxtjs`. Installing `pmxtjs` now provides the SDK only; installing `@pmxt/cli` provides the CLI.
+- **Release workflow**: Updated CI/CD versioning, dry-run publishing, npm publishing, local release scripts, and GitHub release notes to include `@pmxt/cli` alongside `pmxt-core`, `pmxtjs`, and the Python `pmxt` package.
+
+### Fixed
+
+- **Package metadata**: Normalized `pmxt-core` npm metadata so publish dry-runs no longer rely on npm auto-correcting repository and bin path fields.
+- **Release dry run**: Updated the local version-update dry-run helper to validate CLI package versioning, `pmxtjs` dependency pinning, Python `__init__` versioning, and generated SDK version arguments.
+- **CLI auth**: `pmxt auth status` now dispatches correctly while preserving the existing `pmxt auth:status` command.
+
 ## [2.44.7] - 2026-05-25
 
 ### Fixed

core/package.json

@@ -6,11 +6,11 @@
   "types": "dist/index.d.ts",
   "repository": {
     "type": "git",
-    "url": "https://github.com/pmxt-dev/pmxt.git"
+    "url": "git+https://github.com/pmxt-dev/pmxt.git"
   },
   "bin": {
-    "pmxt-server": "./dist/server/index.js",
-    "pmxt-ensure-server": "./bin/pmxt-ensure-server"
+    "pmxt-server": "dist/server/index.js",
+    "pmxt-ensure-server": "bin/pmxt-ensure-server"
   },
   "files": [
     "dist",

core/src/exchanges/mock/index.ts

@@ -23,6 +23,15 @@ import { SeededRng } from './seededRng';
 
 const clamp = (n: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, n));
 const round = (n: number, decimals = 3) => parseFloat(n.toFixed(decimals));
+const toTimestamp = (value: Date | string | number | undefined): number | undefined => {
+    if (value === undefined) return undefined;
+    if (value instanceof Date) return value.getTime();
+    const parsed = typeof value === 'number' ? value : new Date(value).getTime();
+    if (!Number.isFinite(parsed)) {
+        throw new Error(`Invalid date value: ${String(value)}`);
+    }
+    return parsed;
+};
 
 const CATEGORIES = ['Politics', 'Sports', 'Crypto', 'Finance', 'Science', 'Entertainment', 'Tech', 'World'];
 const LOREM = `lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor
@@ -375,8 +384,8 @@ export class MockExchange extends PredictionMarketExchange {
         };
         const step = resolutionMs[params.resolution] ?? 3_600_000;
         const limit = params.limit ?? 100;
-        const end = params.end ? params.end.getTime() : Date.now();
-        const start = params.start ? params.start.getTime() : end - step * limit;
+        const end = toTimestamp(params.end) ?? Date.now();
+        const start = toTimestamp(params.start) ?? end - step * limit;
         const candles: PriceCandle[] = [];
         let price = round(f.float(0.2, 0.8), 3);
         let t = start;

core/src/exchanges/polymarket/websocket.ts

@@ -14,7 +14,7 @@ import {
     POLYMARKET_DEFAULT_SUBSCRIPTION,
 } from '../../subscriber/external/goldsky';
 import { AddressWatcher, WatcherConfig } from '../../subscriber/watcher';
-import { OrderBook, OrderLevel, QueuedPromise, Trade } from '../../types';
+import { OrderBook, QueuedPromise, Trade } from '../../types';
 import { DEFAULT_WATCH_TIMEOUT_MS, withWatchTimeout } from '../../utils/watch-timeout';
 
 
@@ -63,9 +63,12 @@ export interface PolymarketWebSocketConfig {
     userChannelCreds?: PolymarketUserChannelCreds;
     /** Timeout in ms for WebSocket connections to open (default: 30000). */
     connectionTimeoutMs?: number;
+    /** Time to wait for an initial market-channel book before using a REST snapshot fallback. */
+    snapshotFallbackMs?: number;
 }
 
 const DEFAULT_CONNECTION_TIMEOUT_MS = 30_000;
+const DEFAULT_SNAPSHOT_FALLBACK_MS = 3_000;
 const MAX_PENDING_TRADES_PER_ASSET = 1000;
 const MAX_USER_CALLBACKS = 100;
 
@@ -85,8 +88,11 @@ export class PolymarketWebSocket {
     private orderBooks = new Map<string, OrderBook>();
     private config: PolymarketWebSocketConfig;
     private initializationPromise?: Promise<void>;
+    private marketPingInterval: ReturnType<typeof setInterval> | null = null;
+    private readonly callApi: (operationId: string, params?: Record<string, any>) => Promise<any>;
 
     constructor(callApi: (operationId: string, params?: Record<string, any>) => Promise<any>, config: PolymarketWebSocketConfig = {}) {
+        this.callApi = callApi;
         this.config = config;
         const watcherConfig = this.config.watcherConfig;
         const subscriber = new GoldSkySubscriber({
@@ -106,14 +112,22 @@ export class PolymarketWebSocket {
         await this.ensureInitialized();
         await this.subscribe([outcomeId]);
 
-        // Return a promise that resolves on the next orderbook update
+        // Return a promise that resolves on the next orderbook update.
+        // If the upstream market channel accepts the subscription but stays
+        // quiet, return a real REST snapshot instead of hanging indefinitely.
+        const resolverEntry: QueuedPromise<OrderBook> = {
+            resolve: () => {},
+            reject: () => {},
+        };
         const dataPromise = new Promise<OrderBook>((resolve, reject) => {
+            resolverEntry.resolve = resolve;
+            resolverEntry.reject = reject;
             const existing = this.orderBookResolvers.get(outcomeId) ?? [];
-            this.orderBookResolvers.set(outcomeId, [...existing, { resolve, reject }]);
+            this.orderBookResolvers.set(outcomeId, [...existing, resolverEntry]);
         });
 
         return withWatchTimeout(
-            dataPromise,
+            this.withSnapshotFallback(outcomeId, dataPromise, resolverEntry),
             this.config.watchTimeoutMs ?? DEFAULT_WATCH_TIMEOUT_MS,
             `watchOrderBook('${outcomeId}')`,
         );
@@ -323,6 +337,7 @@ export class PolymarketWebSocket {
             this.ws.close();
             this.ws = null;
         }
+        this.stopMarketHeartbeat();
         this.subscribedAssets.clear();
         this.closeUserChannel();
         this.watcher.close();
@@ -361,12 +376,15 @@ export class PolymarketWebSocket {
 
             this.ws.on('open', () => {
                 clearTimeout(timeout);
+                this.startMarketHeartbeat();
                 resolve();
             });
 
             this.ws.on('message', (raw: any) => {
                 try {
-                    const msgs = JSON.parse(raw.toString());
+                    const text = raw.toString();
+                    if (text === 'PONG' || text === 'PING') return;
+                    const msgs = JSON.parse(text);
                     const arr = Array.isArray(msgs) ? msgs : [msgs];
                     for (const msg of arr) {
                         const type = msg.event_type;
@@ -384,10 +402,13 @@ export class PolymarketWebSocket {
             this.ws.on('error', (err: Error) => {
                 clearTimeout(timeout);
                 logger.error('[polymarket-ws] WebSocket error', { error: err.message });
+                this.rejectPendingMarketResolvers(err);
                 reject(err);
             });
 
             this.ws.on('close', () => {
+                this.stopMarketHeartbeat();
+                this.rejectPendingMarketResolvers(new Error('Polymarket market channel closed'));
                 this.initializationPromise = undefined;
                 this.ws = null;
             });
@@ -399,24 +420,117 @@ export class PolymarketWebSocket {
     private handleBookSnapshot(event: any) {
         const id = event.asset_id;
 
-        const bids: OrderLevel[] = event.bids.map((b: any) => ({
-            price: parseFloat(b.price),
-            size: parseFloat(b.size),
+        const orderBook = this.normalizeRawOrderBook(event);
+
+        this.orderBooks.set(id, orderBook);
+        this.resolveOrderBook(id, orderBook);
+    }
+
+    private withSnapshotFallback(
+        outcomeId: string,
+        dataPromise: Promise<OrderBook>,
+        resolverEntry: QueuedPromise<OrderBook>,
+    ): Promise<OrderBook> {
+        const fallbackMs = this.config.snapshotFallbackMs ?? DEFAULT_SNAPSHOT_FALLBACK_MS;
+        if (fallbackMs <= 0) return dataPromise;
+
+        let timer: ReturnType<typeof setTimeout>;
+        const fallbackPromise = new Promise<OrderBook>((resolve, reject) => {
+            timer = setTimeout(async () => {
+                this.removeOrderBookResolver(outcomeId, resolverEntry);
+                try {
+                    resolve(await this.fetchOrderBookSnapshot(outcomeId));
+                } catch (error) {
+                    reject(error);
+                }
+            }, fallbackMs);
+        });
+
+        return Promise.race([dataPromise, fallbackPromise]).finally(() => {
+            clearTimeout(timer);
+        });
+    }
+
+    private removeOrderBookResolver(outcomeId: string, resolverEntry: QueuedPromise<OrderBook>): void {
+        const resolvers = this.orderBookResolvers.get(outcomeId);
+        if (!resolvers) return;
+        const filtered = resolvers.filter((entry) => entry !== resolverEntry);
+        if (filtered.length > 0) {
+            this.orderBookResolvers.set(outcomeId, filtered);
+        } else {
+            this.orderBookResolvers.delete(outcomeId);
+        }
+    }
+
+    private async fetchOrderBookSnapshot(outcomeId: string): Promise<OrderBook> {
+        const raw = await this.callApi('getBook', { token_id: outcomeId });
+        const orderBook = this.normalizeRawOrderBook({
+            ...raw,
+            asset_id: raw?.asset_id ?? outcomeId,
+        });
+        this.orderBooks.set(outcomeId, orderBook);
+        return orderBook;
+    }
+
+    private normalizeRawOrderBook(raw: any): OrderBook {
+        const bids = (raw?.bids || []).map((level: any) => ({
+            price: parseFloat(level.price),
+            size: parseFloat(level.size),
         })).sort((a: any, b: any) => b.price - a.price);
 
-        const asks: OrderLevel[] = event.asks.map((a: any) => ({
-            price: parseFloat(a.price),
-            size: parseFloat(a.size),
+        const asks = (raw?.asks || []).map((level: any) => ({
+            price: parseFloat(level.price),
+            size: parseFloat(level.size),
         })).sort((a: any, b: any) => a.price - b.price);
 
-        const orderBook: OrderBook = {
+        return {
             bids,
             asks,
-            timestamp: event.timestamp ? (isNaN(Number(event.timestamp)) ? new Date(event.timestamp).getTime() : Number(event.timestamp)) : Date.now(),
+            timestamp: this.parseTimestamp(raw?.timestamp),
         };
+    }
 
-        this.orderBooks.set(id, orderBook);
-        this.resolveOrderBook(id, orderBook);
+    private parseTimestamp(value: unknown): number {
+        if (typeof value === 'number') return value;
+        if (typeof value === 'string' && value.length > 0) {
+            const numeric = Number(value);
+            return Number.isNaN(numeric) ? new Date(value).getTime() : numeric;
+        }
+        return Date.now();
+    }
+
+    private startMarketHeartbeat(): void {
+        this.stopMarketHeartbeat();
+        this.marketPingInterval = setInterval(() => {
+            if (this.ws && this.ws.readyState === 1) {
+                try {
+                    this.ws.send('PING');
+                } catch (error) {
+                    logger.warn('[polymarket-ws] market heartbeat failed', {
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        }, 10_000);
+    }
+
+    private stopMarketHeartbeat(): void {
+        if (this.marketPingInterval) {
+            clearInterval(this.marketPingInterval);
+            this.marketPingInterval = null;
+        }
+    }
+
+    private rejectPendingMarketResolvers(error: Error): void {
+        for (const [, resolvers] of this.orderBookResolvers) {
+            for (const resolver of resolvers) resolver.reject(error);
+        }
+        this.orderBookResolvers.clear();
+
+        for (const [, resolvers] of this.tradeResolvers) {
+            for (const resolver of resolvers) resolver.reject(error);
+        }
+        this.tradeResolvers.clear();
     }
 
     private handlePriceChange(event: any) {

core/src/router/Router.ts

@@ -287,7 +287,10 @@ export class Router extends PredictionMarketExchange {
 
         // Lookup mode: find matches for a specific market.
         const response = await this.client.getMarketMatches(params);
-        const matches = response.matches ?? [];
+        if (!response || !Array.isArray(response.matches)) {
+            throw new Error('fetchMarketMatches returned an unexpected response shape: missing matches array');
+        }
+        const matches = response.matches;
         return matches.map((m: any) => ({
             market: m.market,
             relation: m.relation,
@@ -337,7 +340,12 @@ export class Router extends PredictionMarketExchange {
         const hasIdentifier = params.eventId || params.slug;
         if (!hasIdentifier) {
             const results = await this.client.browseEventMatches(params);
-            return Array.isArray(results) ? results : [];
+            if (!Array.isArray(results)) {
+                throw new Error(
+                    `browseEventMatches returned unexpected type '${typeof results}'`
+                );
+            }
+            return results;
         }
 
         if (await this.resolveLocalMockEventLookup(params)) {
@@ -346,7 +354,10 @@ export class Router extends PredictionMarketExchange {
 
         // Lookup mode: find matches for a specific event.
         const response = await this.client.getEventMatches(params);
-        return response.matches ?? [];
+        if (!response || !Array.isArray(response.matches)) {
+            throw new Error('fetchEventMatches returned an unexpected response shape: missing matches array');
+        }
+        return response.matches;
     }
 
     // -----------------------------------------------------------------------