@nexstone/rift-cli 0.1.1

package/dist/commands/setup/proxy.d.ts

@@ -0,0 +1,10 @@
+import { GatedCommand } from '../../lib/base-command.js';
+export default class SetupProxy extends GatedCommand {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+    private optionVpnRunning;
+    private optionPasteProxy;
+    private optionGuidedSetup;
+    private optionClearProxy;
+}

package/dist/commands/setup/proxy.js

@@ -0,0 +1,267 @@
+import { GatedCommand } from '../../lib/base-command.js';
+import { createInterface } from 'node:readline';
+import { execSync } from 'node:child_process';
+import { runEngine } from '../../lib/python-bridge.js';
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+function ask(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise(resolve => {
+        rl.question(question, answer => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+async function checkApi(proxy) {
+    return new Promise(resolve => {
+        const args = proxy ? ['--proxy', proxy] : [];
+        let result = null;
+        runEngine('check-api', args, (msg) => {
+            if (msg.type === 'result') {
+                result = msg;
+            }
+        })
+            .then(() => {
+            if (result?.status === 'ok') {
+                resolve({ ok: true, latency: result.latency_ms, pairs: result.pairs });
+            }
+            else {
+                resolve({ ok: false, error: result?.error || 'Unknown error' });
+            }
+        })
+            .catch((err) => {
+            resolve({ ok: false, error: err.message.split('\n')[0] });
+        });
+    });
+}
+async function saveProxy(proxyUrl) {
+    return new Promise((resolve, reject) => {
+        runEngine('set-proxy', [proxyUrl], () => { })
+            .then(resolve)
+            .catch(reject);
+    });
+}
+async function clearProxy() {
+    return new Promise((resolve, reject) => {
+        runEngine('clear-proxy', [], () => { })
+            .then(resolve)
+            .catch(reject);
+    });
+}
+function detectVpnClients() {
+    const clients = [
+        {
+            name: 'WireGuard',
+            cmd: 'which wg',
+            hint: 'WireGuard detected. Make sure your tunnel is active: wg show',
+        },
+        {
+            name: 'Tailscale',
+            cmd: 'which tailscale',
+            hint: 'Tailscale detected. Use an exit node in a supported region: tailscale up --exit-node=<node>',
+        },
+        {
+            name: 'Mullvad',
+            cmd: 'which mullvad',
+            hint: 'Mullvad detected. Connect to a non-US server: mullvad connect',
+        },
+        {
+            name: 'NordVPN',
+            cmd: 'which nordvpn',
+            hint: 'NordVPN detected. Connect to a non-US server: nordvpn connect',
+        },
+        {
+            name: 'ProtonVPN',
+            cmd: 'which protonvpn-cli',
+            hint: 'ProtonVPN detected. Connect to a non-US server: protonvpn-cli connect',
+        },
+        {
+            name: 'OpenVPN',
+            cmd: 'which openvpn',
+            hint: 'OpenVPN detected. Connect with your config: sudo openvpn --config your.ovpn',
+        },
+    ];
+    return clients.map(c => {
+        let detected = false;
+        try {
+            execSync(c.cmd, { stdio: 'ignore' });
+            detected = true;
+        }
+        catch { }
+        return { name: c.name, detected, hint: c.hint };
+    });
+}
+export default class SetupProxy extends GatedCommand {
+    static description = 'Set up proxy for Hyperliquid API access';
+    static examples = [
+        '$ rift setup proxy',
+    ];
+    async run() {
+        this.log('');
+        this.log(`  ${bold('RIFT Proxy Setup')}`);
+        this.log(`  ${dim('─'.repeat(45))}`);
+        this.log('');
+        // Step 1: Check direct connection
+        this.log(`  ${dim('Checking Hyperliquid API access...')}`);
+        const direct = await checkApi();
+        if (direct.ok) {
+            this.log(`  ${green('✔')} Connected directly ${dim(`(${direct.latency}ms, ${direct.pairs} pairs)`)}`);
+            this.log('');
+            this.log(`  ${dim('No proxy needed — your connection works.')}`);
+            const keepGoing = await ask(`\n  ${dim('Set up a proxy anyway?')} ${dim('(y/N)')}: `);
+            if (keepGoing.toLowerCase() !== 'y') {
+                this.log('');
+                return;
+            }
+        }
+        else {
+            this.log(`  ${red('✘')} Connection blocked`);
+            this.log(`    ${dim(direct.error || 'Could not reach Hyperliquid API')}`);
+            this.log('');
+            this.log(`  ${dim("This is likely a geographic restriction. Let's fix it.")}`);
+        }
+        this.log('');
+        // Step 2: Options
+        this.log(`  ${bold('How would you like to connect?')}`);
+        this.log('');
+        this.log(`    ${cyan('1')}  I already have a VPN running        ${dim('— just test the connection')}`);
+        this.log(`    ${cyan('2')}  I have a proxy/SOCKS5 address        ${dim('— paste it in')}`);
+        this.log(`    ${cyan('3')}  Help me set one up                   ${dim("— I'll walk you through it")}`);
+        this.log(`    ${cyan('4')}  Remove existing proxy config         ${dim('— go back to direct connection')}`);
+        this.log('');
+        const choice = await ask(`  ${cyan('>')} `);
+        switch (choice) {
+            case '1':
+                await this.optionVpnRunning();
+                break;
+            case '2':
+                await this.optionPasteProxy();
+                break;
+            case '3':
+                await this.optionGuidedSetup();
+                break;
+            case '4':
+                await this.optionClearProxy();
+                break;
+            default:
+                this.log(dim('  Invalid selection.'));
+        }
+        this.log('');
+    }
+    async optionVpnRunning() {
+        this.log('');
+        this.log(`  ${dim('Testing connection with your VPN...')}`);
+        const result = await checkApi();
+        if (result.ok) {
+            this.log(`  ${green('✔')} Connected! ${dim(`(${result.latency}ms, ${result.pairs} pairs)`)}`);
+            this.log('');
+            this.log(`  ${dim('Your VPN is routing traffic correctly. No proxy config needed.')}`);
+            this.log(`  ${dim('Just keep your VPN on when using RIFT.')}`);
+        }
+        else {
+            this.log(`  ${red('✘')} Still blocked. ${dim(result.error || '')}`);
+            this.log('');
+            this.log(`  ${dim('Your VPN may not be routing all traffic, or the exit node')}`);
+            this.log(`  ${dim('is in a restricted region. Try a different server location,')}`);
+            this.log(`  ${dim('or use option 2 to configure a SOCKS5 proxy.')}`);
+        }
+    }
+    async optionPasteProxy() {
+        this.log('');
+        this.log(`  ${dim('Paste your proxy URL. Common formats:')}`);
+        this.log(`    ${dim('socks5://127.0.0.1:1080')}`);
+        this.log(`    ${dim('socks5://user:pass@host:port')}`);
+        this.log(`    ${dim('http://host:port')}`);
+        this.log(`    ${dim('https://host:port')}`);
+        this.log('');
+        const proxy = await ask(`  ${cyan('Proxy URL')}: `);
+        if (!proxy) {
+            this.log(dim('  No proxy entered.'));
+            return;
+        }
+        this.log('');
+        this.log(`  ${dim('Testing connection via')} ${proxy} ${dim('...')}`);
+        const result = await checkApi(proxy);
+        if (result.ok) {
+            this.log(`  ${green('✔')} Connected! ${dim(`(${result.latency}ms, ${result.pairs} pairs)`)}`);
+            this.log('');
+            await saveProxy(proxy);
+            this.log(`  ${green('✔')} Proxy saved to ${dim('~/.rift/config.json')}`);
+            this.log(`  ${dim('All RIFT API calls will now use this proxy.')}`);
+        }
+        else {
+            this.log(`  ${red('✘')} Failed to connect via proxy`);
+            this.log(`    ${dim(result.error || 'Unknown error')}`);
+            this.log('');
+            this.log(`  ${dim('Check that the proxy is running and the URL is correct.')}`);
+            const saveAnyway = await ask(`\n  ${dim('Save this proxy anyway?')} ${dim('(y/N)')}: `);
+            if (saveAnyway.toLowerCase() === 'y') {
+                await saveProxy(proxy);
+                this.log(`  ${yellow('!')} Proxy saved (untested)`);
+            }
+        }
+    }
+    async optionGuidedSetup() {
+        this.log('');
+        // Detect installed VPN clients
+        const clients = detectVpnClients();
+        const installed = clients.filter(c => c.detected);
+        if (installed.length > 0) {
+            this.log(`  ${bold('Detected VPN clients on your system:')}`);
+            this.log('');
+            for (const client of installed) {
+                this.log(`  ${green('✔')} ${bold(client.name)}`);
+                this.log(`    ${dim(client.hint)}`);
+                this.log('');
+            }
+            this.log(`  ${dim('Connect using one of the above, then re-run:')}`);
+            this.log(`    ${cyan('rift setup proxy')}`);
+            this.log(`  ${dim('and select option 1 to test your connection.')}`);
+            this.log('');
+            this.log(`  ${dim('─'.repeat(45))}`);
+            this.log('');
+        }
+        // SOCKS5 provider guides
+        this.log(`  ${bold('Quick setup options:')}`);
+        this.log('');
+        this.log(`  ${cyan('A')}  ${bold('Mullvad SOCKS5')} ${dim('— easiest, $5/mo, no account needed')}`);
+        this.log(`     ${dim('1. Go to mullvad.net and get an account number')}`);
+        this.log(`     ${dim('2. Download & install Mullvad')}`);
+        this.log(`     ${dim('3. Connect to any non-US server')}`);
+        this.log(`     ${dim('4. SOCKS5 proxy is at: socks5://10.64.0.1:1080')}`);
+        this.log(`     ${dim('5. Come back and run: rift setup proxy → option 2')}`);
+        this.log('');
+        this.log(`  ${cyan('B')}  ${bold('SSH tunnel')} ${dim('— if you have a VPS ($5/mo)')}`);
+        this.log(`     ${dim('Run this in a separate terminal:')}`);
+        this.log(`     ${cyan('ssh -D 1080 -N user@your-server-ip')}`);
+        this.log(`     ${dim('Then come back and enter: socks5://127.0.0.1:1080')}`);
+        this.log('');
+        this.log(`  ${cyan('C')}  ${bold('NordVPN SOCKS5')} ${dim('— if you have NordVPN')}`);
+        this.log(`     ${dim('1. Get SOCKS5 credentials from nordvpn.com/servers/socks')}`);
+        this.log(`     ${dim('2. Use: socks5://user:pass@amsterdam.nl.socks.nordhold.net:1080')}`);
+        this.log('');
+        this.log(`  ${cyan('D')}  ${bold('ProtonVPN SOCKS5')} ${dim('— if you have ProtonVPN Plus')}`);
+        this.log(`     ${dim('1. Enable SOCKS5 in ProtonVPN settings')}`);
+        this.log(`     ${dim('2. Use: socks5://127.0.0.1:1080')}`);
+        this.log('');
+        this.log(`  ${dim('─'.repeat(45))}`);
+        this.log('');
+        const ready = await ask(`  ${dim('Ready to enter a proxy URL?')} ${dim('(y/N)')}: `);
+        if (ready.toLowerCase() === 'y') {
+            await this.optionPasteProxy();
+        }
+        else {
+            this.log(`  ${dim('No problem. Run')} ${cyan('rift setup proxy')} ${dim('when you\'re ready.')}`);
+        }
+    }
+    async optionClearProxy() {
+        await clearProxy();
+        this.log('');
+        this.log(`  ${green('✔')} Proxy config removed. RIFT will connect directly.`);
+    }
+}

package/dist/commands/spot/buy.d.ts

@@ -0,0 +1,14 @@
+import { GatedCommand } from '../../lib/base-command.js';
+export default class SpotBuy extends GatedCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        coin: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        amount: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        size: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/spot/buy.js

@@ -0,0 +1,38 @@
+import { Args, Flags } from '@oclif/core';
+import { GatedCommand } from '../../lib/base-command.js';
+import { passthroughToEngine } from '../../lib/engine-passthrough.js';
+export default class SpotBuy extends GatedCommand {
+    static description = 'Buy a token on the Hyperliquid spot market. Simple purchase, no leverage. 1% builder fee on sell side only.';
+    static examples = [
+        '$ rift spot buy HYPE --amount 25       # spend 25 USDC buying HYPE',
+        '$ rift spot buy BTC --amount 50        # 50 USDC of BTC (auto-resolved to UBTC spot)',
+        '$ rift spot buy UETH --size 0.01       # buy a fixed 0.01 UETH',
+    ];
+    static args = {
+        coin: Args.string({
+            description: 'Token to buy (e.g. HYPE, BTC, ETH — names auto-resolve to HL spot tokens like UBTC, UETH)',
+            required: true,
+        }),
+    };
+    static flags = {
+        amount: Flags.string({ description: 'USDC amount to spend (one of --amount or --size required)', default: '' }),
+        size: Flags.string({ description: 'Token amount to buy (alternative to --amount)', default: '' }),
+        json: Flags.boolean({ description: 'Emit raw JSON only', default: false }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(SpotBuy);
+        const engineArgs = [args.coin];
+        if (flags.amount)
+            engineArgs.push('--amount', flags.amount);
+        if (flags.size)
+            engineArgs.push('--size', flags.size);
+        await passthroughToEngine({
+            command: 'buy',
+            args: engineArgs,
+            log: (m) => this.log(m),
+            error: (m) => this.error(m),
+            exit: (c) => this.exit(c),
+            jsonOnly: flags.json,
+        });
+    }
+}

package/dist/commands/spot/sell.d.ts

@@ -0,0 +1,14 @@
+import { GatedCommand } from '../../lib/base-command.js';
+export default class SpotSell extends GatedCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        coin: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        amount: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        pct: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/spot/sell.js

@@ -0,0 +1,39 @@
+import { Args, Flags } from '@oclif/core';
+import { GatedCommand } from '../../lib/base-command.js';
+import { passthroughToEngine } from '../../lib/engine-passthrough.js';
+export default class SpotSell extends GatedCommand {
+    static description = 'Sell a token from spot holdings back to USDC. 1% builder fee applies.';
+    static examples = [
+        '$ rift spot sell HYPE              # sell all HYPE holdings',
+        '$ rift spot sell HYPE --pct 50     # sell half',
+        '$ rift spot sell HYPE --amount 5   # sell a fixed 5 HYPE',
+        '$ rift spot sell BTC               # sell all UBTC (BTC alias)',
+    ];
+    static args = {
+        coin: Args.string({
+            description: 'Token to sell (e.g. HYPE, BTC, ETH — names auto-resolve to HL spot tokens)',
+            required: true,
+        }),
+    };
+    static flags = {
+        amount: Flags.string({ description: 'Token amount to sell (0/omit = all)', default: '' }),
+        pct: Flags.string({ description: 'Percentage to sell (e.g. 50 = half)', default: '' }),
+        json: Flags.boolean({ description: 'Emit raw JSON only', default: false }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(SpotSell);
+        const engineArgs = [args.coin];
+        if (flags.amount)
+            engineArgs.push('--amount', flags.amount);
+        if (flags.pct)
+            engineArgs.push('--pct', flags.pct);
+        await passthroughToEngine({
+            command: 'sell',
+            args: engineArgs,
+            log: (m) => this.log(m),
+            error: (m) => this.error(m),
+            exit: (c) => this.exit(c),
+            jsonOnly: flags.json,
+        });
+    }
+}

package/dist/commands/strategies/list.d.ts

@@ -0,0 +1,6 @@
+import { GatedCommand } from '../../lib/base-command.js';
+export default class StrategiesList extends GatedCommand {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/strategies/list.js

@@ -0,0 +1,34 @@
+import { GatedCommand } from '../../lib/base-command.js';
+import { runEngine } from '../../lib/python-bridge.js';
+export default class StrategiesList extends GatedCommand {
+    static description = 'List available trading strategies';
+    static examples = [
+        '$ rift strategies list',
+    ];
+    async run() {
+        await runEngine('strategies', [], (msg) => {
+            if (msg.type === 'result') {
+                const strategies = msg.strategies;
+                if (!strategies || strategies.length === 0) {
+                    this.log('No strategies found. Create one with: rift new <name>');
+                    return;
+                }
+                this.log('');
+                this.log('  Available strategies:');
+                this.log('');
+                for (const s of strategies) {
+                    this.log(`  ${s.name}`);
+                    if (s.doc)
+                        this.log(`    ${s.doc.trim()}`);
+                    if (Object.keys(s.config).length > 0) {
+                        this.log('    Config:');
+                        for (const [key, val] of Object.entries(s.config)) {
+                            this.log(`      ${key}: ${val}`);
+                        }
+                    }
+                    this.log('');
+                }
+            }
+        });
+    }
+}

package/dist/commands/sweep.d.ts

@@ -0,0 +1,19 @@
+import { GatedCommand } from '../lib/base-command.js';
+export default class Sweep extends GatedCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        strategy: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        pair: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        tf: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        equity: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        leverage: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        top: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        rank: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+    private renderResult;
+}

package/dist/commands/sweep.js

@@ -0,0 +1,137 @@
+import { Flags, Args } from '@oclif/core';
+import * as path from 'node:path';
+import { GatedCommand } from '../lib/base-command.js';
+import { runEngine } from '../lib/python-bridge.js';
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+function colorNum(val, suffix = '') {
+    const str = `${val}${suffix}`;
+    if (val > 0)
+        return green(str);
+    if (val < 0)
+        return red(str);
+    return yellow(str);
+}
+export default class Sweep extends GatedCommand {
+    static description = 'Run a parameter sweep to find optimal strategy settings';
+    static examples = [
+        '$ rift sweep trend_follow --pair BTC --tf 4h',
+        '$ rift sweep my_strategy --config strategies/my_strategy/sweep.yaml',
+        '$ rift sweep trend_follow --pair BTC --tf 4h --rank sharpe --top 5',
+    ];
+    static args = {
+        strategy: Args.string({ description: 'Strategy name', required: true }),
+    };
+    static flags = {
+        pair: Flags.string({ description: 'Trading pair', default: 'BTC-PERP' }),
+        tf: Flags.string({ description: 'Timeframe', default: '1h' }),
+        config: Flags.string({ description: 'Path to sweep.yaml config file' }),
+        equity: Flags.integer({ description: 'Starting equity', default: 10000 }),
+        leverage: Flags.integer({ description: 'Leverage multiplier', default: 1 }),
+        top: Flags.integer({ description: 'Number of top results to show', default: 10 }),
+        rank: Flags.string({ description: 'Rank by: sharpe, return, or profit_factor', default: 'sharpe', options: ['sharpe', 'return', 'profit_factor'] }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Sweep);
+        this.log('');
+        this.log(`  ${bold('Parameter Sweep')}`);
+        this.log(`  ${dim(`${args.strategy} on ${flags.pair} ${flags.tf} — ranked by ${flags.rank}`)}`);
+        this.log('');
+        const engineArgs = [
+            args.strategy,
+            '--pair', flags.pair,
+            '--tf', flags.tf,
+            '--equity', String(flags.equity),
+            '--leverage', String(flags.leverage),
+            '--top', String(flags.top),
+            '--rank', flags.rank,
+        ];
+        // Anchor relative config paths to the user's cwd — the engine
+        // subprocess runs with cwd=engine/, so a bare "strategies/.../sweep.yaml"
+        // would otherwise resolve to engine/strategies/.../sweep.yaml.
+        if (flags.config)
+            engineArgs.push('--config', path.resolve(flags.config));
+        await runEngine('sweep', engineArgs, (msg) => {
+            if (msg.type === 'progress' && msg.msg) {
+                // Compact progress display — just combo count + ETA
+                const msgStr = String(msg.msg);
+                const match = msgStr.match(/Combo (\d+)\/(\d+)(.*?ETA \S+)?/);
+                const display = match
+                    ? `Combo ${match[1]}/${match[2]}${match[3] ? ' — ' + match[3].trim() : ''}`
+                    : msgStr;
+                process.stdout.write(`\x1b[2K\r  ${dim(display)}`);
+            }
+            else if (msg.type === 'result') {
+                process.stdout.write('\r' + ' '.repeat(80) + '\r');
+                this.renderResult(msg);
+            }
+            else if (msg.type === 'error') {
+                process.stdout.write('\r' + ' '.repeat(80) + '\r');
+                this.error(msg.msg);
+            }
+        });
+    }
+    renderResult(msg) {
+        const total = msg.total_combos;
+        const completed = msg.completed;
+        const rankBy = msg.rank_by;
+        const topEntries = msg.top;
+        this.log(`  ${dim(`Tested ${completed}/${total} parameter combinations`)}`);
+        this.log('');
+        if (!topEntries || topEntries.length === 0) {
+            this.log(`  ${yellow('No results.')}`);
+            return;
+        }
+        // Get all param keys for the header
+        const paramKeys = Object.keys(topEntries[0].params);
+        // Build table header
+        const rankLabel = rankBy === 'return' ? 'Return' : rankBy === 'profit_factor' ? 'PF' : 'Sharpe';
+        this.log(dim('  ── Top Results ──'));
+        this.log('');
+        // Header
+        let header = `  ${dim('│')} ${'#'.padEnd(4)}`;
+        for (const key of paramKeys) {
+            header += `${key.padEnd(14)}`;
+        }
+        header += `${'Return'.padEnd(12)}${'Sharpe'.padEnd(12)}${'Win%'.padEnd(10)}${'Trades'.padEnd(8)}${'MaxDD'.padEnd(12)} ${dim('│')}`;
+        const hrLen = header.replace(/\x1b\[[0-9;]*m/g, '').length;
+        const hr = `  ${dim('─'.repeat(hrLen - 2))}`;
+        this.log(hr);
+        this.log(header);
+        this.log(hr);
+        for (let i = 0; i < topEntries.length; i++) {
+            const e = topEntries[i];
+            const m = e.metrics;
+            let row = `  ${dim('│')} ${bold(String(i + 1).padEnd(4))}`;
+            for (const key of paramKeys) {
+                row += `${String(e.params[key]).padEnd(14)}`;
+            }
+            const retStr = `${m.total_return_pct}%`;
+            const sharpeStr = `${m.sharpe_ratio}`;
+            const winStr = `${m.win_rate}%`;
+            const tradesStr = `${m.num_trades}`;
+            const ddStr = `${m.max_drawdown_pct}%`;
+            row += `${colorNum(m.total_return_pct, '%')}${' '.repeat(Math.max(1, 12 - retStr.length))}`;
+            row += `${colorNum(m.sharpe_ratio)}${' '.repeat(Math.max(1, 12 - sharpeStr.length))}`;
+            row += `${winStr.padEnd(10)}`;
+            row += `${tradesStr.padEnd(8)}`;
+            row += `${colorNum(m.max_drawdown_pct, '%')}${' '.repeat(Math.max(1, 12 - ddStr.length))}`;
+            row += dim('│');
+            this.log(row);
+        }
+        this.log(hr);
+        // Show best config
+        const best = topEntries[0];
+        this.log('');
+        this.log(`  ${green('★')} Best by ${rankLabel}:`);
+        for (const [key, val] of Object.entries(best.params)) {
+            this.log(`    ${key}: ${bold(String(val))}`);
+        }
+        this.log(`    → ${colorNum(best.metrics.total_return_pct, '% return')}, Sharpe ${colorNum(best.metrics.sharpe_ratio)}`);
+        this.log('');
+    }
+}

package/dist/commands/sync.d.ts

@@ -0,0 +1,17 @@
+import { GatedCommand } from '../lib/base-command.js';
+export default class Sync extends GatedCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        coins: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        tf: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        start: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        end: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'no-funding': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        full: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'aws-key': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'aws-secret': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/sync.js

@@ -0,0 +1,54 @@
+import { Flags } from '@oclif/core';
+import { GatedCommand } from '../lib/base-command.js';
+import { passthroughToEngine } from '../lib/engine-passthrough.js';
+export default class Sync extends GatedCommand {
+    static description = 'Sync historical OHLCV + funding data from the Hyperliquid S3 archive. Requires AWS credentials (free tier; ~$2 for the full download).';
+    static examples = [
+        '$ rift sync --coins BTC --tf 1h,4h',
+        '$ rift sync --coins BTC,ETH,SOL --tf 5m,15m,1h,4h --start 2024-01-01',
+        '$ rift sync --aws-key AKIA... --aws-secret ... --coins BTC --tf 1h',
+    ];
+    static flags = {
+        coins: Flags.string({
+            description: 'Comma-separated coins (empty = auto-detect from registered strategies)',
+            default: '',
+        }),
+        tf: Flags.string({
+            description: 'Comma-separated timeframes to build',
+            default: '5m,15m,1h,4h',
+        }),
+        start: Flags.string({ description: 'Start date YYYY-MM-DD', default: '2023-09-01' }),
+        end: Flags.string({ description: 'End date YYYY-MM-DD (default: today)', default: '' }),
+        'no-funding': Flags.boolean({ description: 'Skip funding rate sync', default: false }),
+        full: Flags.boolean({ description: 'Full sync (ignore incremental cache)', default: false }),
+        'aws-key': Flags.string({ description: 'AWS Access Key ID (for non-interactive setup)', default: '' }),
+        'aws-secret': Flags.string({ description: 'AWS Secret Access Key', default: '' }),
+        json: Flags.boolean({ description: 'Emit raw JSON only', default: false }),
+    };
+    async run() {
+        const { flags } = await this.parse(Sync);
+        const args = [];
+        if (flags.coins)
+            args.push('--coins', flags.coins);
+        args.push('--tf', flags.tf);
+        args.push('--start', flags.start);
+        if (flags.end)
+            args.push('--end', flags.end);
+        if (flags['no-funding'])
+            args.push('--no-funding');
+        if (flags.full)
+            args.push('--full');
+        if (flags['aws-key'])
+            args.push('--aws-key', flags['aws-key']);
+        if (flags['aws-secret'])
+            args.push('--aws-secret', flags['aws-secret']);
+        await passthroughToEngine({
+            command: 'sync',
+            args,
+            log: (m) => this.log(m),
+            error: (m) => this.error(m),
+            exit: (c) => this.exit(c),
+            jsonOnly: flags.json,
+        });
+    }
+}