@vike-io/cli 0.5.0

package/skills/vike-wallet-summary/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: vike-wallet-summary
+description: Aggregate metrics for a single wallet — volume, inflow, outflow, net flow, tx count, tokens traded across 24h / 7d / 30d / 90d / all windows. Use when the user gives an address and asks "what's this wallet doing".
+allowed-tools: Bash(vike:*)
+---
+
+# vike-wallet-summary
+
+## Command
+
+```bash
+vike wallet summary <address> [--json]
+```
+
+## Output
+
+Per-window rows: `window`, `volume_usd`, `inflow_usd`, `outflow_usd`, `net_flow_usd`, `tx_count`, `unique_tokens`.
+
+## Reading tips
+
+- **Net flow >> 0** = accumulator. Inflow heavy → still buying.
+- **Net flow << 0** = distributor. Outflow heavy → still selling.
+- **Volume high, net flow ≈ 0** = trader/MM (churn). Look at counterparty patterns separately.
+- **Unique tokens high (>50)** = farmer / spray-and-pray. Lower signal per token.
+- **Unique tokens low (<5), high volume** = concentrated conviction.
+
+## Anti-patterns
+
+- Don't claim a wallet is "smart money" based on summary alone — cross-reference with labels and PnL: `vike wallet discover --sort pnl` to see if this address is in the top-PnL set.
+- A single big inflow can dominate `net_flow_usd` for a window — eyeball `tx_count` to gauge whether it's one trade or many.
+
+## Pairs well with
+
+- `vike wallet discover` to see if this wallet ranks in any leaderboard
+- `vike token transfers` after identifying which tokens the wallet trades

package/skills/vike-web-fetch/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: vike-web-fetch
+description: Fetch a URL's content (via Tavily extract) and optionally answer a question about it using Cerebras Llama 3.3 70B. Use when the user gives a URL and asks "what does this page say" / "summarise X" / "extract Y from this article".
+allowed-tools: Bash(vike:*)
+---
+
+# vike-web-fetch
+
+## Command
+
+```bash
+vike web fetch <url> [--ask "<question>"] [--json]
+```
+
+## Examples
+
+```bash
+vike web fetch https://example.com/article
+vike web fetch https://example.com/article --ask "what's the launch date?"
+vike web fetch https://docs.hyperliquid.xyz/funding --ask "how often does funding settle?"
+```
+
+## Output
+
+```json
+{
+  "url": "https://...",
+  "content_length": 12345,
+  "content": "First 8K chars of extracted content...",
+  "answer": "Answer to your question if --ask was provided"
+}
+```
+
+If `--ask` is omitted, you get raw extracted content only.
+
+## How it works
+
+1. Tries Tavily's `/extract` endpoint first — returns clean markdown-like text
+2. Falls back to raw HTTP GET if Tavily extract is unavailable
+3. If `--ask` is provided, sends content + question to Cerebras Llama 3.3 70B for a focused answer
+
+## Why we use Cerebras (not Gemini / OpenAI)
+
+Cerebras Llama 3.3 70B is ~10x cheaper than Gemini 2.5 Flash and ~3-5x faster (1000+ tok/sec inference). Same answer quality for short Q&A on supplied content.
+
+## Anti-patterns
+
+- Don't fetch pay-walled URLs and expect text — you'll get a paywall page. Cite the URL and tell the user instead.
+- Don't fetch huge files (PDFs > 10MB, videos) — the extract will be truncated and likely garbage.
+- Don't ask `--ask` questions the content can't possibly answer — Cerebras will hallucinate. Stay tight to what's on the page.
+
+## Pairs well with
+
+- `vike web search` — find URLs to fetch first
+- `vike-web-research` — composite multi-step research workflow

package/skills/vike-web-research/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: vike-web-research
+description: Multi-step web research playbook — search → fetch the most relevant URL → synthesize answer. Use when the user asks an open question that requires fresh web info ("what did Trump say about crypto yesterday", "latest exchange listing announcement", "summarize the latest Pendle update").
+allowed-tools: Bash(vike:*)
+---
+
+# vike-web-research
+
+Composite playbook combining `vike web search` and `vike web fetch` for cross-source synthesis.
+
+## Workflow
+
+### 1. Search (gather candidate URLs)
+
+```bash
+vike web search "<query>" --max 5 --json
+```
+
+Capture the top results' URLs and titles. If the response includes an `answer` field, that's often enough for simple factual queries — surface it directly and skip step 2.
+
+### 2. Fetch (only when search snippets are insufficient)
+
+```bash
+vike web fetch <top-result-url> --ask "<focused question>" --json
+```
+
+Fetch only the highest-scoring (Tavily) or most-credible (Serper) URL. Re-fetching all 5 search results burns credits and adds noise.
+
+### 3. Synthesize
+
+> **Question:** `<user query>`
+> **Answer (from `<source URL>`):** `<extracted answer>`
+> **Other relevant sources:** `<url1>`, `<url2>` (with one-line summaries each)
+
+Always link the source URL so the user can verify.
+
+## When to skip the workflow
+
+- **One-shot fact lookup** (price, date, contract address) → if `web search` returns it in the `answer` field, just quote that
+- **The user already gave you a URL** → skip search, jump to `web fetch`
+- **On-chain question** → don't web-research; use vike's on-chain tools (`token holders`, `wallet labels`, `perp funding`, etc.)
+
+## Anti-patterns
+
+- Don't fetch 5 URLs and average them — pick the most authoritative
+- Don't quote Reddit / Twitter as primary sources for hard claims (price, dates, addresses); use them for sentiment only
+- Don't combine web research with `vike-smart-money-discovery` results without saying so — they're different evidence types
+
+## Cost
+
+- Step 1: 2 credits (Tavily basic)
+- Step 2: 3 credits (web_fetch with --ask = Tavily extract + Cerebras Q&A)
+- Total: ~5 credits per research round
+
+## Pairs well with
+
+- `vike-token-research` — combine on-chain data with off-chain news
+- `vike-polymarket-screener` — narrative-driven prediction markets often need news context

package/skills/vike-web-search/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: vike-web-search
+description: Web search using Tavily (LLM-tuned snippets, primary) with Serper Google fallback. Use when you need current events, project announcements, exchange listing news, or anything not in the vike on-chain databases.
+allowed-tools: Bash(vike:*)
+---
+
+# vike-web-search
+
+## Command
+
+```bash
+vike web search "<query>" [--max N] [--depth basic|advanced] [--json]
+```
+
+The query can contain multiple words (no quoting required if you don't have shell-special chars).
+
+## Examples
+
+```bash
+vike web search "hyperliquid funding rate explained"
+vike web search "polymarket trump 2026 latest" --max 8
+vike web search "ETH ETF inflows last week" --depth advanced
+```
+
+## Output
+
+```json
+{
+  "provider": "tavily",
+  "query": "...",
+  "answer": "Optional one-paragraph synthesised answer (Tavily only)",
+  "results": [
+    { "title": "...", "url": "...", "snippet": "...", "score": 0.88 },
+    ...
+  ]
+}
+```
+
+`score` is a 0-1 relevance from Tavily (higher = more relevant). Serper doesn't include it.
+
+## When to use vs on-chain tools
+
+- **News / sentiment / project context** → `vike web search`
+- **On-chain flows / wallet activity / token prices** → use the dedicated `vike token`/`vike wallet`/`vike perp` tools first
+- **"What did X tweet" / "did Binance announce Y"** → web search
+
+## Cost note
+
+Web search calls cost 2 credits + an external API fee on our side. Use it when you genuinely need fresh / non-onchain info, not as a first-resort.
+
+## Anti-patterns
+
+- Don't web-search for things our on-chain tools answer faster ("top wallets holding PEPE" → `vike token holders` is faster, cheaper, and more accurate)
+- Don't request `--max > 5` unless you genuinely need a wide net — agents waste tokens summarising 10 results when 3 would do
+- `--depth advanced` doubles the cost; reserve for hard-to-answer queries
+
+## Pairs well with
+
+- `vike-web-fetch` — once you have a promising URL, fetch its full content
+- `vike-web-research` — composite playbook for multi-step research

package/src/auth.js

@@ -0,0 +1,55 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const CONFIG_DIR = join(homedir(), '.vike');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+export function getApiKey() {
+  // Resolution order: env var > config file
+  const envKey = process.env.VIKE_API_KEY;
+  if (envKey) return envKey;
+
+  if (!existsSync(CONFIG_FILE)) return null;
+  try {
+    const cfg = JSON.parse(readFileSync(CONFIG_FILE, 'utf8'));
+    return cfg.api_key || null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveApiKey(apiKey) {
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  }
+  let cfg = {};
+  if (existsSync(CONFIG_FILE)) {
+    try { cfg = JSON.parse(readFileSync(CONFIG_FILE, 'utf8')); } catch { /* ignore */ }
+  }
+  cfg.api_key = apiKey;
+  cfg.saved_at = new Date().toISOString();
+  writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+  return CONFIG_FILE;
+}
+
+export function clearApiKey() {
+  if (!existsSync(CONFIG_FILE)) return false;
+  unlinkSync(CONFIG_FILE);
+  return true;
+}
+
+export function getEndpoint() {
+  return process.env.VIKE_MCP_URL || 'https://vike.io/mcp';
+}
+
+export function requireApiKey() {
+  const key = getApiKey();
+  if (!key) {
+    throw new Error(
+      'No API key. Run `vike login --api-key <key>` or set VIKE_API_KEY. ' +
+      'Get a key at https://vike.io/api/keys',
+    );
+  }
+  return key;
+}

package/src/commands/alerts.js

@@ -0,0 +1,118 @@
+import { callTool } from '../mcp-client.js';
+import { emit, emitError } from '../format.js';
+import { parseBool, parseInt10 } from '../util.js';
+
+export function registerAlerts(program) {
+  const cmd = program
+    .command('alerts')
+    .description('Manage on-chain transfer alerts');
+
+  cmd
+    .command('list')
+    .description('List your alerts')
+    .option('--include-inactive', 'Include paused/deleted alerts')
+    .option('--json', 'Emit JSON')
+    .action(async (opts) => {
+      try {
+        const r = await callTool('alerts_list', {
+          include_inactive: parseBool(opts.includeInactive, false),
+        });
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+
+  cmd
+    .command('register-webhook <url>')
+    .description('Register an HTTPS webhook for alert delivery (HMAC-signed POST when secret given)')
+    .option('--secret <s>', 'Optional HMAC-SHA256 secret (recommended, >=16 chars)')
+    .option('--json', 'Emit JSON')
+    .action(async (url, opts) => {
+      try {
+        const r = await callTool('alerts_register_webhook', {
+          url,
+          secret: opts.secret,
+        });
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+
+  cmd
+    .command('channels')
+    .description('List your enabled notification channels (email/discord/webhook)')
+    .option('--json', 'Emit JSON')
+    .action(async (opts) => {
+      try {
+        const r = await callTool('alerts_list_channels', {});
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+
+  cmd
+    .command('create')
+    .description('Create a new on-chain transfer alert')
+    .requiredOption('--label <l>', 'Alert label (user-visible name)')
+    .option('--token <sym>', 'Token ticker, UPPERCASE (e.g. USDC, ETH)')
+    .option('--chain <c>', 'eth | bsc', 'eth')
+    .option('--min-usd <n>', 'Minimum transfer USD value')
+    .option('--max-usd <n>', 'Maximum transfer USD value')
+    .option('--channel <c...>', 'Notification channel(s): email, discord')
+    .option('--cooldown <min>', 'Minimum gap between triggers (minutes)', '60')
+    .option('--json', 'Emit JSON')
+    .action(async (opts) => {
+      try {
+        const r = await callTool('alerts_create', {
+          label: opts.label,
+          token_symbol: opts.token,
+          chain: opts.chain,
+          min_value_usd: opts.minUsd,
+          max_value_usd: opts.maxUsd,
+          channels: opts.channel,
+          cooldown_minutes: parseInt10(opts.cooldown, 60),
+        });
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+
+  cmd
+    .command('edit <alert_id>')
+    .description('Update an alert (only fields you pass are modified)')
+    .option('--label <l>')
+    .option('--token <sym>')
+    .option('--chain <c>')
+    .option('--min-usd <n>')
+    .option('--max-usd <n>')
+    .option('--channel <c...>')
+    .option('--cooldown <min>')
+    .option('--active <bool>', 'Pause/resume (true|false)')
+    .option('--json', 'Emit JSON')
+    .action(async (alertId, opts) => {
+      try {
+        const payload = { alert_id: alertId };
+        if (opts.label !== undefined) payload.label = opts.label;
+        if (opts.token !== undefined) payload.token_symbol = opts.token;
+        if (opts.chain !== undefined) payload.chain = opts.chain;
+        if (opts.minUsd !== undefined) payload.min_value_usd = opts.minUsd;
+        if (opts.maxUsd !== undefined) payload.max_value_usd = opts.maxUsd;
+        if (opts.channel !== undefined) payload.channels = opts.channel;
+        if (opts.cooldown !== undefined) payload.cooldown_minutes = opts.cooldown;
+        if (opts.active !== undefined) payload.is_active = parseBool(opts.active, true);
+        const r = await callTool('alerts_edit', payload);
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+
+  cmd
+    .command('delete <alert_id>')
+    .description('Delete (or pause) an alert')
+    .option('--hard', 'Hard-delete instead of pausing')
+    .option('--json', 'Emit JSON')
+    .action(async (alertId, opts) => {
+      try {
+        const r = await callTool('alerts_delete', {
+          alert_id: alertId,
+          hard: parseBool(opts.hard, false),
+        });
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+}

package/src/commands/auth.js

@@ -0,0 +1,43 @@
+import { saveApiKey, clearApiKey, getApiKey } from '../auth.js';
+import { emit } from '../format.js';
+
+export function registerLogin(program) {
+  program
+    .command('login')
+    .description('Save an API key to ~/.vike/config.json')
+    .option('--api-key <key>', 'API key (vk_...)')
+    .action(async (opts) => {
+      if (!opts.apiKey) {
+        console.error('Pass --api-key <vk_...>. Get a key at https://vike.io/api/keys');
+        process.exitCode = 1;
+        return;
+      }
+      const path = saveApiKey(opts.apiKey);
+      emit({ ok: true, saved_to: path });
+    });
+}
+
+export function registerLogout(program) {
+  program
+    .command('logout')
+    .description('Remove the saved API key')
+    .action(() => {
+      const cleared = clearApiKey();
+      emit({ ok: true, cleared });
+    });
+}
+
+export function registerWhoami(program) {
+  program
+    .command('whoami')
+    .description('Show which API key is in use (truncated)')
+    .action(() => {
+      const k = getApiKey();
+      if (!k) {
+        emit({ authenticated: false });
+        return;
+      }
+      const masked = k.length > 12 ? `${k.slice(0, 8)}...${k.slice(-4)}` : '***';
+      emit({ authenticated: true, api_key: masked, source: process.env.VIKE_API_KEY ? 'env' : 'config' });
+    });
+}

package/src/commands/doctor.js

@@ -0,0 +1,87 @@
+import { getApiKey, getEndpoint } from '../auth.js';
+import { ping, listTools } from '../mcp-client.js';
+
+export function registerDoctor(program) {
+  program
+    .command('doctor')
+    .description('Diagnose CLI setup, endpoint reachability, and tool availability')
+    .action(async () => {
+      const checks = [];
+
+      // 1. Node version
+      const nodeVer = process.version;
+      const major = parseInt(nodeVer.slice(1).split('.')[0], 10);
+      checks.push({
+        name: 'Node runtime',
+        ok: major >= 20,
+        detail: `${nodeVer} (need >= 20.0.0)`,
+      });
+
+      // 2. API key
+      const key = getApiKey();
+      checks.push({
+        name: 'API key',
+        ok: Boolean(key),
+        detail: key
+          ? `${key.slice(0, 8)}... (source: ${process.env.VIKE_API_KEY ? 'env' : 'config'})`
+          : 'Not set. Run `vike init` or `vike login --api-key <key>`',
+      });
+
+      // 3. Endpoint
+      const endpoint = getEndpoint();
+      checks.push({
+        name: 'Endpoint URL',
+        ok: true,
+        detail: endpoint,
+      });
+
+      // 4. Connectivity — HTTP 200 means endpoint up; auth error is separate concern
+      try {
+        const { status, body } = await ping({ apiKey: key ?? undefined });
+        const reachable = status === 200;
+        const authed = reachable && !body.error;
+        let detail;
+        if (authed) {
+          detail = `OK · server=${body?.result?.serverInfo?.name ?? '?'} v${body?.result?.serverInfo?.version ?? '?'}`;
+        } else if (reachable) {
+          detail = `Endpoint reachable; ${body?.error?.message ?? 'no auth'}`;
+        } else {
+          detail = `HTTP ${status} · ${JSON.stringify(body).slice(0, 200)}`;
+        }
+        checks.push({ name: 'MCP connectivity', ok: reachable, detail });
+      } catch (err) {
+        checks.push({ name: 'MCP connectivity', ok: false, detail: err.message });
+      }
+
+      // 5. Tool list (requires auth)
+      if (key) {
+        try {
+          const tools = await listTools();
+          checks.push({
+            name: 'Tool registry',
+            ok: tools.length > 0,
+            detail: `${tools.length} tools available`,
+          });
+        } catch (err) {
+          checks.push({ name: 'Tool registry', ok: false, detail: err.message });
+        }
+      } else {
+        checks.push({ name: 'Tool registry', ok: false, detail: 'Skipped (no API key)' });
+      }
+
+      // Render
+      const PASS = '✔';
+      const FAIL = '✗';
+      for (const c of checks) {
+        const mark = c.ok ? PASS : FAIL;
+        console.log(`${mark}  ${c.name.padEnd(20)} ${c.detail}`);
+      }
+      const failed = checks.filter((c) => !c.ok).length;
+      if (failed > 0) {
+        console.log(`\n${failed} check(s) failed.`);
+        process.exitCode = 1;
+      } else {
+        console.log('\nAll checks passed. Try: vike token search BTC');
+      }
+    });
+}

package/src/commands/init.js

@@ -0,0 +1,50 @@
+import { saveApiKey, getApiKey } from '../auth.js';
+import { ping } from '../mcp-client.js';
+import { emit } from '../format.js';
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+
+export function registerInit(program) {
+  program
+    .command('init')
+    .description('Interactive setup: save your API key and verify connectivity')
+    .option('--api-key <key>', 'Skip the prompt by passing the key')
+    .action(async (opts) => {
+      let key = opts.apiKey ?? getApiKey();
+
+      if (!key) {
+        const rl = createInterface({ input: stdin, output: stdout });
+        try {
+          console.log('Get your API key at https://vike.io/api/keys');
+          key = (await rl.question('Paste your API key (vk_...): ')).trim();
+        } finally {
+          rl.close();
+        }
+      }
+
+      if (!key) {
+        console.error('No API key provided. Aborting.');
+        process.exitCode = 1;
+        return;
+      }
+
+      const path = saveApiKey(key);
+      console.log(`Saved to ${path}`);
+
+      console.log('Verifying connection to vike.io/mcp ...');
+      const { status, body } = await ping({ apiKey: key });
+      if (status !== 200) {
+        console.error(`Endpoint returned HTTP ${status}: ${JSON.stringify(body)}`);
+        process.exitCode = 1;
+        return;
+      }
+      const info = body?.result?.serverInfo ?? {};
+      emit({
+        ok: true,
+        server: info.name,
+        version: info.version,
+        protocol: body?.result?.protocolVersion,
+        next: 'Try: vike token search BTC',
+      });
+    });
+}

package/src/commands/labels.js

@@ -0,0 +1,48 @@
+import { callTool } from '../mcp-client.js';
+import { emit, emitError } from '../format.js';
+import { parseInt10 } from '../util.js';
+
+export function registerLabels(program) {
+  // `vike labels <address>` — multi-source label provenance for one wallet
+  program
+    .command('labels <address>')
+    .description('Multi-source label cascade for a wallet (10+ providers + in-house heuristic + consensus view)')
+    .option('--json', 'Emit JSON')
+    .action(async (address, opts) => {
+      try {
+        const r = await callTool('wallet_label_provenance', { address });
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+
+  // `vike funds` — top labeled funds / MM / treasury / CEX by recent net inflow
+  program
+    .command('funds')
+    .description('Top labeled fund / market-maker / treasury / CEX wallets by net inflow')
+    .option('--kind <k>', 'funds | cex | mm | treasury', 'funds')
+    .option('--window <w>', '7d | 30d | 90d | 180d | all', '30d')
+    .option('--limit <n>', 'Max wallets (max 25)', '10')
+    .option('--json', 'Emit JSON')
+    .action(async (opts) => {
+      try {
+        const r = await callTool('fund_holdings', {
+          kind: opts.kind,
+          window: opts.window,
+          limit: parseInt10(opts.limit, 10),
+        });
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+
+  // `vike defi <address>` — DeBank protocol positions for a wallet
+  program
+    .command('defi <address>')
+    .description('DeFi protocol positions for a wallet across all DeBank-supported chains')
+    .option('--json', 'Emit JSON')
+    .action(async (address, opts) => {
+      try {
+        const r = await callTool('defi_positions', { address });
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+}

package/src/commands/options.js

@@ -0,0 +1,24 @@
+import { callTool } from '../mcp-client.js';
+import { emit, emitError } from '../format.js';
+
+export function registerOptions(program) {
+  const cmd = program
+    .command('options')
+    .description('Deribit options flow');
+
+  cmd
+    .command('flow')
+    .description('Call/put flow, volume, and put-call ratios')
+    .option('--symbol <s>', 'BTC | ETH | SOL', 'BTC')
+    .option('--window <w>', '1d | 1w | 1m', '1d')
+    .option('--json', 'Emit JSON')
+    .action(async (opts) => {
+      try {
+        const r = await callTool('options_flow', {
+          symbol: opts.symbol,
+          window: opts.window,
+        });
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+}