@vike-io/cli 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 All notable changes are documented here. Entries follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 0.7.0 — 5 new commands (transactions, compare, trace, batch, screener)
+
+- **`vike wallet transactions <address>`** (alias `txs`) — raw per-wallet transfer list with `--direction in|out|all`, `--days`, `--min-usd`, `--token` filters.
+- **`vike wallet compare <a> <b>`** — diff two wallets (shared counterparties + shared tokens within a window).
+- **`vike wallet trace <address>`** — counterparty graph traversal, depth 1-5, width 1-10, with min-USD threshold.
+- **`vike wallet batch <addr1> <addr2> ...`** — bulk label + 30d summary lookup for up to 100 addresses, preserves input order.
+- **`vike token screener`** — token discovery filter ranked by volume / net inflow / holders / smart-money inflow.
+- 5 new SKILL.md playbooks: `vike-wallet-transactions`, `vike-wallet-compare`, `vike-wallet-trace`, `vike-wallet-batch`, `vike-token-screener`.
+
+Total: 38 skills (was 33), 34 MCP tools (was 29).
+
+## 0.6.0 — infra hardening + observability + skill eval harness
+
+Mostly internal-quality improvements; no new commands. Backbone for everything that follows.
+
+**New infra**
+- **Background update-check** — silent detached subprocess polls the registry once/day; next-run prints `Update available: X.Y.Z → A.B.C`. Honors `NO_UPDATE_NOTIFIER` / `CI` / `VIKE_NO_UPDATE_CHECK`.
+- **First-run-after-upgrade notice** — one-time `Updated to X.Y.Z` print.
+- **Telemetry skeleton** — anonymous UUID + 30-min session ID, fire-and-forget. NO sink endpoint wired yet (events drop silently); shape is stable so we can flip it on without refactoring. Opt-out via `DO_NOT_TRACK=1` or `VIKE_NO_TELEMETRY=1`.
+- **Centralized chain registry** (`src/chains.js`) — `ALL_CHAINS`, `EVM_CHAINS`, `WALLET_CHAINS`, `CHAIN_ALIASES`, `normaliseChain()`, `isEvmAddress()`.
+
+**Testing + release safety**
+- Two-tier vitest config — `npm test` (unit/integration, <30s) vs `npm run test:e2e` (live MCP, up to 2 min).
+- Four meta-tests added: shebang, pack-and-install (catches missing `files`), CLI help for every command, command coverage regression.
+- Pretest changeset validator — hard-fails on wrong package name in changeset frontmatter; warns on missing changeset.
+- Postinstall script hardened — global-install + TTY gates, always `exit 0`.
+
+**Skill quality evals (preview)**
+- `evals/` directory with a `uv run`-script harness: A/B-tests every question against `vike --help` only vs `vike --help + SKILL.md`. Scores per question; aggregates a Δ for each skill. If a skill doesn't move the score, it shouldn't ship. Run: `uv run --script evals/runner.py` (needs `ANTHROPIC_API_KEY`).
+- 14 starter questions in `evals/questions.yaml`.
+
+**Security**
+- `SECURITY.md` published (report at security@vike.io; 48h ack, 7d critical-fix SLA).
+- `CODEOWNERS` file (single-maintainer for now; security-sensitive paths called out).
+- Dependabot weekly PRs for npm + GitHub Actions deps.
+- `npm audit --audit-level=high` added to CI.
+
 ## 0.5.0 — initial public release
 
 AI-agent CLI for vike.io on-chain analytics, perpetuals, options flow, and prediction-market data across 11 chains.

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "AI-agent CLI for vike.io on-chain analytics, perps, options, and prediction markets across 11 chains",
   "type": "module",
   "main": "src/index.js",
@@ -19,8 +19,10 @@
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
     "start": "node src/index.js",
+    "pretest": "node scripts/check-changeset.js",
     "test": "vitest run --passWithNoTests",
     "test:watch": "vitest",
+    "test:e2e": "vitest run --config vitest.e2e.config.js",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "changeset": "changeset",

package/scripts/postinstall.js

@@ -1,20 +1,40 @@
-// Postinstall — print a friendly setup hint when the user installs vike-cli.
-// Silent in CI environments to avoid log noise.
+// Postinstall — print a friendly setup hint on global install only.
+//
+// Three defensive guards:
+// 1. Local installs (`npm i @vike-io/cli` inside a project) get nothing —
+//    the hint would be noise. Only global installs (`-g`) print.
+// 2. Non-TTY environments (CI, scripts, docker build) get nothing —
+//    nothing in here is interactive, but defensively short-circuit so a
+//    future maintainer can't accidentally prompt and hang `npm ci`.
+// 3. Any error is swallowed — postinstall must NEVER break `npm install`.
+//
+// Honors $CI and npm's --silent / loglevel=silent.
 
-if (process.env.CI || process.env.npm_config_loglevel === 'silent') {
+const isGlobal = String(process.env.npm_config_global || '') === 'true';
+const hasTTY = Boolean(process.stdout.isTTY) && Boolean(process.stderr.isTTY);
+const isQuiet = process.env.CI ||
+                process.env.npm_config_loglevel === 'silent' ||
+                process.env.npm_config_loglevel === 'error';
+
+if (!isGlobal || !hasTTY || isQuiet) {
   process.exit(0);
 }
 
-const lines = [
-  '',
-  '  @vike-io/cli installed.',
-  '',
-  '  Next steps:',
-  '    vike init                  — interactive setup',
-  '    vike doctor                — verify your install',
-  '    vike token search BTC      — your first query',
-  '',
-  '  Docs: https://vike.io/api',
-  '',
-];
-process.stdout.write(lines.join('\n'));
+try {
+  const lines = [
+    '',
+    '  @vike-io/cli installed.',
+    '',
+    '  Next steps:',
+    '    vike init                  — interactive setup',
+    '    vike doctor                — verify your install',
+    '    vike token search BTC      — your first query',
+    '',
+    '  Docs: https://vike.io/api',
+    '',
+  ];
+  process.stdout.write(lines.join('\n'));
+} catch {
+  // Postinstall must not fail an npm install. Swallow everything.
+}
+process.exit(0);

package/skills/vike-token-screener/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: vike-token-screener
+description: Token discovery filter — rank tokens by volume / net inflow / holder count / smart-money inflow within a window, with min-volume and min-holder filters. Use when the user asks "what tokens are trending today" / "find tokens with smart money accumulating" / "rising tokens this week" / token discovery from scratch.
+allowed-tools: Bash(vike:*)
+---
+
+# vike-token-screener
+
+## Command
+
+```bash
+vike token screener
+  [--chain ethereum|bsc|base]
+  [--window 24h|7d|30d|90d]
+  [--sort volume|net_inflow|holders|smart_inflow]
+  [--limit N]              (max 100)
+  [--min-volume USD]       (filter dust)
+  [--min-holders N]        (require N+ unique holders)
+  [--smart-money-only]     (restrict to smart-money cohort flows)
+  [--json]
+```
+
+## Examples
+
+```bash
+# Trending today by volume
+vike token screener --window 24h --sort volume --limit 20
+
+# Find tokens smart money is accumulating
+vike token screener --window 7d --sort smart_inflow --smart-money-only
+
+# Rising holders count (organic growth signal)
+vike token screener --window 30d --sort holders --min-volume 100000
+
+# Mid-cap tokens with real activity
+vike token screener --min-volume 1000000 --min-holders 100 --sort net_inflow
+```
+
+## Output columns
+
+`token_address`, `symbol` (when known), `name`, `volume_usd`, `net_flow_usd`, `in_usd`, `out_usd`, `unique_holders`, `tx_count`.
+
+## Sort modes
+
+| Sort | What it surfaces |
+|---|---|
+| `volume` | Most-traded tokens (default) — captures attention-driven action |
+| `net_inflow` | Tokens with biggest accumulation (in > out) — "what's being bought" |
+| `holders` | Tokens gaining unique addresses — organic growth signal |
+| `smart_inflow` | Tokens our smart-money cohort is buying — alpha signal |
+
+## Reading
+
+- **High volume + balanced in/out** = churn (DEX MM, arb bots). Low signal.
+- **High volume + strong net_inflow** = real demand. Worth investigating.
+- **Strong holder growth + flat volume** = small buys, distribution widening. Often early signal.
+- **`smart_inflow` mode** + high values + low overall volume = cohort is positioned BEFORE retail. Highest-conviction signal in the tool.
+
+## Filter tips
+
+| Goal | Filters |
+|---|---|
+| "Rising memecoins" | `--window 24h --sort holders --min-holders 50 --min-volume 50000` |
+| "Mid-cap alpha" | `--sort smart_inflow --min-volume 500000 --smart-money-only` |
+| "What's getting dumped" | `--sort net_inflow` then reverse — bottom rows have biggest outflows |
+
+## Anti-patterns
+
+- Don't quote the symbol as authoritative if `symbol` is null/blank — token hasn't been mapped, identify by address instead
+- Don't use `--window 24h --sort smart_inflow` for hot-new-token discovery — smart money usually positions BEFORE the 24h window; try `--window 7d` for that mode
+- Don't omit `--min-holders` when sorting by holders — junk airdrops with 50,000 1-tx addresses dominate the top otherwise
+- Don't omit `--min-volume` when sorting by net_inflow — tiny tokens with $100 net flow can rank high in % terms
+
+## Cost note
+
+3 credits per call. Cheaper than `wallet trace` (which is 4) but heavier than per-tool lookups. Use deliberately for discovery, not as a default.
+
+## Pairs well with
+
+- `vike token holders <addr>` — drill into the top holders of any flagged token
+- `vike token transfers <addr>` — see WHO is buying/selling once a token is interesting
+- `vike-smart-money-discovery` — composite playbook starting from this screen

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

@@ -0,0 +1,56 @@
+---
+name: vike-wallet-batch
+description: Bulk label + 30d summary lookup for up to 100 addresses in one call. Use when the user pastes a CSV of addresses, asks "enrich this list with labels", or wants to quickly screen many wallets for entity / risk / activity.
+allowed-tools: Bash(vike:*)
+---
+
+# vike-wallet-batch
+
+## Command
+
+```bash
+vike wallet batch <addr1> <addr2> <addr3> ...
+  [--chain ethereum|bsc|base]
+  [--json]
+```
+
+Caps at 100 addresses per call. For larger lists, split into chunks.
+
+## Example
+
+```bash
+vike wallet batch 0xd8da... 0xabc... 0xdef... --json
+```
+
+## Output
+
+One row per INPUT address (preserves input order — useful when joining back to a source CSV):
+
+```json
+[
+  { "wallet": "0xd8da...", "entity": null,       "wallet_type": "user", "confidence": "Medium", "risk_flag": null,    "net_30d_usd": 12000, "volume_30d_usd": 50000, "tx_30d": 42, "tokens_30d_count": 8, "found": true },
+  { "wallet": "0xabc...",  "entity": "Binance",  "wallet_type": "cex",  "confidence": "High",   "risk_flag": null,    "net_30d_usd": -5e9,  "volume_30d_usd": 9e9,   "tx_30d": 2000, "tokens_30d_count": 80, "found": true },
+  { "wallet": "0xdef...",  "entity": null,       "wallet_type": null,   "confidence": null,     "risk_flag": null,    "net_30d_usd": 0,     "volume_30d_usd": 0,     "tx_30d": 0,    "tokens_30d_count": 0,  "found": false }
+]
+```
+
+`found: false` = address has no labels AND no 30d activity in our DB (might be brand-new wallet or one we haven't indexed).
+
+## Reading
+
+- Filter to `wallet_type = "user"` to find real-people addresses worth investigating further
+- Any `risk_flag != null` → flag prominently in any user-facing report
+- High `volume_30d_usd` but `tx_30d = 0` shouldn't happen — if it does, indicates stale aggregate; recompute
+- `entity = "Binance"` + `wallet_type = "cex"` rows in a "smart money" list = false positives (CEX deposits aren't traders)
+
+## Anti-patterns
+
+- Don't run individual `vike wallet summary` in a loop for >5 addresses — this batch is ~20× faster
+- Don't pass mixed-case addresses inconsistently — they're normalised but cleaner CSVs help readers
+- Don't expect lifetime data — this is 30d window. For lifetime use the individual `wallet summary`
+
+## Pairs well with
+
+- `vike labels <addr>` — drill into any address showing high-confidence labels
+- `vike wallet compare <a> <b>` — pick two interesting batch results and diff them
+- `vike funds` — when batch reveals fund/MM/treasury wallets, get their flows

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

@@ -0,0 +1,56 @@
+---
+name: vike-wallet-compare
+description: Diff two wallets — find their shared counterparties (both transacted with these addresses) and shared tokens (both touched these tokens) within a window. Use when the user asks "are these two wallets related" / "what do X and Y have in common" / "find connections between wallet A and B".
+allowed-tools: Bash(vike:*)
+---
+
+# vike-wallet-compare
+
+## Command
+
+```bash
+vike wallet compare <address_a> <address_b>
+  [--chain ethereum|bsc|base]
+  [--window 24h|7d|30d|90d|180d|all]
+  [--limit N]   (max 50)
+  [--json]
+```
+
+## Output
+
+```json
+{
+  "address_a": "0x...",
+  "address_b": "0x...",
+  "window": "30d",
+  "shared_counterparties": [
+    { "wallet": "0x...", "a_volume_usd": 50000, "b_volume_usd": 75000, "a_tx_count": 3, "b_tx_count": 5, "entity": "Binance", "wallet_type": "cex" },
+    ...
+  ],
+  "shared_tokens": [
+    { "token_address": "0x...", "a_volume_usd": 12000, "b_volume_usd": 8000, "a_tx_count": 2, "b_tx_count": 4 },
+    ...
+  ],
+  "summary": { "shared_counterparty_count": 7, "shared_token_count": 12 }
+}
+```
+
+## Reading
+
+- Many shared counterparties + same entity types = likely operated by same person/group
+- Same exchange (Binance hot wallet) as counterparty for both = trivial overlap, both users of that CEX
+- Shared NICHE tokens (long-tail memes, low-vol) with similar tx counts = strong signal of coordination
+- Shared infra contracts (Uniswap, 1inch) = trivial overlap, ignore
+- Zero shared = wallets genuinely independent
+
+## Anti-patterns
+
+- **Don't infer common ownership from CEX overlap.** Millions of users deposit to the same Binance hot wallets. Shared CEX counterparty = nothing.
+- **Don't claim coordination from common DEX router overlap** (Uniswap, 1inch routers). Almost every DEX user shares those.
+- Filter mentally for `wallet_type IN ('user', 'unknown')` overlap if you want a meaningful relatedness signal.
+
+## Pairs well with
+
+- `vike labels <addr>` — drill into any interesting shared counterparty
+- `vike wallet trace <addr>` — follow money outward from either wallet
+- `vike wallet counterparties <addr>` — top partners per wallet individually

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

@@ -0,0 +1,75 @@
+---
+name: vike-wallet-trace
+description: Counterparty graph traversal from a root wallet outward. At each hop, expand to the top N counterparties by USD volume. Use when the user asks "where did funds from X go" / "follow the money 3 hops out" / "trace the network around this wallet" / wallet investigation.
+allowed-tools: Bash(vike:*)
+---
+
+# vike-wallet-trace
+
+## Command
+
+```bash
+vike wallet trace <address>
+  [--chain ethereum|bsc|base]
+  [--depth N]    (1-5, default 2)
+  [--width N]    (1-10, default 5)
+  [--window 24h|7d|30d|90d|all]
+  [--min-usd N]  (default 10000 — prunes noise)
+  [--json]
+```
+
+## Output
+
+```json
+{
+  "root": "0xabc...",
+  "depth": 2, "width": 5, "window": "30d", "min_usd": 10000,
+  "nodes": [
+    { "address": "0xabc...", "depth": 0, "total_volume_usd": 0.0 },
+    { "address": "0xdef...", "depth": 1, "total_volume_usd": 250000, "label": "Binance", "wallet_type": "cex" },
+    { "address": "0x123...", "depth": 2, "total_volume_usd": 45000, "label": null, "wallet_type": null },
+    ...
+  ],
+  "edges": [
+    { "from": "0xabc...", "to": "0xdef...", "volume_usd": 200000, "tx_count": 4 },
+    ...
+  ],
+  "stats": { "node_count": 23, "edge_count": 31, "max_depth_reached": 2 }
+}
+```
+
+## Reading the graph
+
+- **Root (depth 0)** = the wallet you traced from. `total_volume_usd` = 0 because it's where edges originate.
+- **Depth 1** = direct counterparties. Most useful layer.
+- **Depth 2-3** = "friend-of-friend" — useful for finding where funds end up.
+- **Edge volume_usd** = the volume between those two specific addresses, NOT cumulative.
+- **`wallet_type = "cex"`** at depth 1 = funds went to / came from an exchange. Often the END of the trail (anonymous from there).
+- **Unlabeled wallet with high volume at depth 1-2** = potentially related wallet, investigate with `vike labels`.
+
+## Parameter tuning
+
+| Parameter | Effect | Use when |
+|---|---|---|
+| `--depth 1` | Direct counterparties only | "Who does X trade with" — same as `wallet counterparties` |
+| `--depth 2` | One degree of separation | Default. Reveals immediate networks. |
+| `--depth 3+` | Wider net | Investigation / OSINT. Returns much more data; graph gets noisy. |
+| `--width 3` | Top 3 per hop | Cleaner, focused on biggest flows |
+| `--width 10` | Top 10 per hop | Wider scan, more noise |
+| `--min-usd 50000` | High-value flows only | Strip out dust/airdrops |
+
+## Cost note
+
+Tool credits = 4 per call (heavier than other graph-less tools). Graph explodes exponentially with depth — depth 3 + width 10 = up to 1000 nodes per scan. Use `--depth 2 --width 5` as default.
+
+## Anti-patterns
+
+- Don't trace through CEX deposits. Once funds enter Binance/Coinbase, the trail goes opaque (CEX internal accounting, not on-chain). Note CEX nodes and stop following.
+- Don't depth-5 by default. Graph blows up; results become noise.
+- Don't ignore `min_usd` — without it, dust transfers create false-positive edges.
+
+## Pairs well with
+
+- `vike labels <addr>` — identify any interesting node
+- `vike wallet compare <addr_a> <addr_b>` — confirm relatedness once trace surfaces candidates
+- `vike wallet transactions <addr>` — drill into specific transfers between two nodes

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

@@ -0,0 +1,59 @@
+---
+name: vike-wallet-transactions
+description: Raw per-wallet transfer list (individual transactions, not aggregates) with direction, day, USD, and token filters. Use when the user asks "show me recent transfers for X" / "last 100 transactions of Y" / "all USDC moves from this wallet" / any forensic audit query.
+allowed-tools: Bash(vike:*)
+---
+
+# vike-wallet-transactions
+
+## Command
+
+```bash
+vike wallet transactions <address>     # alias: vike wallet txs
+  [--chain ethereum|bsc|base]
+  [--direction in|out|all]
+  [--days N]   (max 365)
+  [--limit N]  (max 500)
+  [--min-usd N]
+  [--token <addr>]
+  [--json]
+```
+
+## Examples
+
+```bash
+# Recent in+out transfers, last 7 days
+vike wallet txs 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 --days 7 --limit 20
+
+# Only outgoing > $10k in last 30d
+vike wallet txs 0xabc... --direction out --min-usd 10000
+
+# Only USDC transfers
+vike wallet txs 0xabc... --token 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
+```
+
+## Output columns
+
+`time`, `tx_hash`, `from_address`, `to_address`, `token_address`, `value_usd`, `direction` (in/out), `block`.
+
+Sorted descending by time (most recent first).
+
+## Reading
+
+- High `tx_count` over short window + low `value_usd` per tx = bot / MM / contract
+- Mixed in/out with similar volumes = active trader
+- Many `out` to one address = sweep / deposit pattern
+- One huge `in` then nothing = airdrop receiver / one-time deposit
+
+## Anti-patterns
+
+- Don't use this for aggregated metrics (volume, PnL) — use `wallet summary` instead, it's faster
+- Don't paginate by re-running with smaller windows — limit max 500, just bump `--limit`
+- Don't use `--token` on every query if you want full activity; the filter restricts to one token
+
+## Pairs well with
+
+- `vike wallet summary <addr>` — aggregate metrics over same window
+- `vike wallet counterparties <addr>` — who they trade with most
+- `vike wallet trace <addr>` — graph-traverse outward from this wallet
+- `vike labels <addr>` — identify the wallet itself

package/src/chains.js

@@ -0,0 +1,86 @@
+// Central chain registry. Every command that takes a --chain flag should
+// import EVM_CHAINS or ALL_CHAINS from here. Adding a chain = one edit.
+
+export const EVM_CHAINS = [
+  'ethereum',
+  'bsc',
+  'base',
+  'arbitrum',
+  'polygon',
+  'optimism',
+  'hyperevm',
+];
+
+export const NON_EVM_CHAINS = [
+  'bitcoin',
+  'solana',
+  'tron',
+  'xmr',
+  'zec',
+  'dash',
+];
+
+export const ALL_CHAINS = [...EVM_CHAINS, ...NON_EVM_CHAINS];
+
+// Chains the wallet_* tools currently support (subset of EVM_CHAINS where
+// we have indexed transfers + labels). Used by --chain validation in
+// commands like `wallet summary` / `wallet counterparties` / etc.
+export const WALLET_CHAINS = ['ethereum', 'bsc', 'base'];
+
+// Chain abbreviation map: short → canonical. We accept both forms from
+// CLI input and normalise to canonical before sending to MCP.
+export const CHAIN_ALIASES = {
+  eth: 'ethereum',
+  ethereum: 'ethereum',
+  bsc: 'bsc',
+  bnb: 'bsc',
+  base: 'base',
+  arb: 'arbitrum',
+  arbitrum: 'arbitrum',
+  poly: 'polygon',
+  polygon: 'polygon',
+  op: 'optimism',
+  optimism: 'optimism',
+  hyper: 'hyperevm',
+  hyperevm: 'hyperevm',
+  btc: 'bitcoin',
+  bitcoin: 'bitcoin',
+  sol: 'solana',
+  solana: 'solana',
+  tron: 'tron',
+  trx: 'tron',
+  xmr: 'xmr',
+  monero: 'xmr',
+  zec: 'zec',
+  zcash: 'zec',
+  dash: 'dash',
+};
+
+export function normaliseChain(input, fallback = 'ethereum') {
+  if (!input) return fallback;
+  const key = String(input).toLowerCase().trim();
+  return CHAIN_ALIASES[key] ?? input;
+}
+
+// Address-format expectations per chain. Used by `vike doctor` and
+// future input validation. EVM = 0x + 40 hex; Solana = base58 32-44 chars;
+// BTC = various encodings; privacy chains = chain-specific.
+export const ADDRESS_FORMATS = {
+  ethereum: '0x + 40 hex chars',
+  bsc: '0x + 40 hex chars',
+  base: '0x + 40 hex chars',
+  arbitrum: '0x + 40 hex chars',
+  polygon: '0x + 40 hex chars',
+  optimism: '0x + 40 hex chars',
+  hyperevm: '0x + 40 hex chars',
+  solana: 'base58, 32-44 chars',
+  bitcoin: 'bech32 / P2PKH / P2SH',
+  tron: 'base58 starting with T',
+  xmr: 'monero address (95 chars)',
+  zec: 'zcash transparent or shielded',
+  dash: 'P2PKH starting with X',
+};
+
+export function isEvmAddress(addr) {
+  return typeof addr === 'string' && /^0x[0-9a-fA-F]{40}$/.test(addr);
+}

package/src/commands/token.js

@@ -58,6 +58,32 @@ export function registerToken(program) {
       } catch (err) { emitError(err, opts); }
     });
 
+  cmd
+    .command('screener')
+    .description('Token discovery filter — rank tokens by volume / inflow / holders / smart-money inflow')
+    .option('--chain <c>', 'ethereum | bsc | base', 'ethereum')
+    .option('--window <w>', '24h | 7d | 30d | 90d', '24h')
+    .option('--sort <s>', 'volume | net_inflow | holders | smart_inflow', 'volume')
+    .option('--limit <n>', 'Max tokens (max 100)', '20')
+    .option('--min-volume <usd>', 'Minimum window volume USD', '0')
+    .option('--min-holders <n>', 'Minimum unique holders', '0')
+    .option('--smart-money-only', 'Restrict flows to smart-money cohort')
+    .option('--json', 'Emit JSON')
+    .action(async (opts) => {
+      try {
+        const r = await callTool('token_screener', {
+          chain: opts.chain,
+          window: opts.window,
+          sort: opts.sort,
+          limit: parseInt10(opts.limit, 20),
+          min_volume_usd: parseFloat(opts.minVolume) || 0,
+          min_holders: parseInt10(opts.minHolders, 0),
+          smart_money_only: Boolean(opts.smartMoneyOnly),
+        });
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+
   cmd
     .command('holders <token_address>')
     .description('Top holders of a token by cumulative net inflow USD')

package/src/commands/wallet.js

@@ -18,6 +18,87 @@ export function registerWallet(program) {
       } catch (err) { emitError(err, opts); }
     });
 
+  cmd
+    .command('transactions <address>')
+    .alias('txs')
+    .description('Raw per-wallet transfer list with filters')
+    .option('--chain <c>', 'ethereum | bsc | base', 'ethereum')
+    .option('--direction <d>', 'in | out | all', 'all')
+    .option('--days <n>', 'Days back (max 365)', '30')
+    .option('--limit <n>', 'Max txs (max 500)', '50')
+    .option('--min-usd <n>', 'Filter dust below this USD value', '0')
+    .option('--token <addr>', 'Optional: restrict to one token address')
+    .option('--json', 'Emit JSON')
+    .action(async (address, opts) => {
+      try {
+        const r = await callTool('wallet_transactions', {
+          address,
+          chain: opts.chain,
+          direction: opts.direction,
+          days: parseInt10(opts.days, 30),
+          limit: parseInt10(opts.limit, 50),
+          min_usd: parseFloat(opts.minUsd) || 0,
+          token_address: opts.token,
+        });
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+
+  cmd
+    .command('compare <address_a> <address_b>')
+    .description('Diff two wallets — shared counterparties + shared tokens')
+    .option('--chain <c>', 'ethereum | bsc | base', 'ethereum')
+    .option('--window <w>', '24h | 7d | 30d | 90d | 180d | all', '30d')
+    .option('--limit <n>', 'Max shared items per category (max 50)', '10')
+    .option('--json', 'Emit JSON')
+    .action(async (a, b, opts) => {
+      try {
+        const r = await callTool('wallet_compare', {
+          address_a: a, address_b: b,
+          chain: opts.chain, window: opts.window,
+          limit: parseInt10(opts.limit, 10),
+        });
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+
+  cmd
+    .command('trace <address>')
+    .description('Counterparty graph traversal from a root wallet')
+    .option('--chain <c>', 'ethereum | bsc | base', 'ethereum')
+    .option('--depth <n>', 'Hops to follow (1-5)', '2')
+    .option('--width <n>', 'Top counterparties per hop (1-10)', '5')
+    .option('--window <w>', '24h | 7d | 30d | 90d | all', '30d')
+    .option('--min-usd <n>', 'Minimum USD per transfer to follow', '10000')
+    .option('--json', 'Emit JSON')
+    .action(async (address, opts) => {
+      try {
+        const r = await callTool('wallet_trace', {
+          address,
+          chain: opts.chain,
+          depth: parseInt10(opts.depth, 2),
+          width: parseInt10(opts.width, 5),
+          window: opts.window,
+          min_usd: parseFloat(opts.minUsd) || 10000,
+        });
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+
+  cmd
+    .command('batch <addresses...>')
+    .description('Bulk label + 30d summary lookup for many addresses (max 100)')
+    .option('--chain <c>', 'ethereum | bsc | base', 'ethereum')
+    .option('--json', 'Emit JSON')
+    .action(async (addresses, opts) => {
+      try {
+        const r = await callTool('wallet_batch_labels', {
+          addresses, chain: opts.chain,
+        });
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+
   cmd
     .command('counterparties <address>')
     .description('Top trading partners of a wallet by combined transfer volume')

package/src/index.js

@@ -16,13 +16,27 @@ import { registerDoctor } from './commands/doctor.js';
 import { registerSchema } from './commands/schema.js';
 import { registerLogin, registerLogout } from './commands/auth.js';
 import { readPackageVersion } from './util.js';
+import {
+  getUpdateNotification,
+  getUpgradeNotice,
+  scheduleUpdateCheck,
+} from './update-check.js';
+
+const version = readPackageVersion();
+
+// Print at-most-once notifications: upgrade-since-last-run, and update-available
+// (the latter from the previous background check). Cheap, sync, exits if quiet.
+const upgradeNotice = getUpgradeNotice(version);
+const updateNotice = getUpdateNotification(version);
+if (upgradeNotice) process.stderr.write(upgradeNotice);
+if (updateNotice) process.stderr.write(updateNotice);
 
 const program = new Command();
 
 program
   .name('vike')
   .description('AI-agent CLI for vike.io on-chain analytics')
-  .version(readPackageVersion(), '-v, --version', 'Show CLI version');
+  .version(version, '-v, --version', 'Show CLI version');
 
 registerLogin(program);
 registerLogout(program);
@@ -38,7 +52,12 @@ registerPolymarket(program);
 registerLabels(program);
 registerWeb(program);
 
-program.parseAsync(process.argv).catch((err) => {
-  console.error(`vike: ${err.message ?? err}`);
-  process.exitCode = 1;
-});
+program.parseAsync(process.argv)
+  .catch((err) => {
+    console.error(`vike: ${err.message ?? err}`);
+    process.exitCode = 1;
+  })
+  .finally(() => {
+    // Fire-and-forget background check, detached subprocess. Survives our exit.
+    scheduleUpdateCheck();
+  });

package/src/telemetry.js

@@ -0,0 +1,120 @@
+// Anonymous, opt-out telemetry skeleton.
+//
+// Design decisions:
+// - Honors DO_NOT_TRACK=1 (industry standard) AND VIKE_NO_TELEMETRY=1
+// - Honors CI / NODE_ENV=test (never phones home from CI)
+// - Persistent UUIDv4 in ~/.vike/telemetry-id (regenerated on delete)
+// - Rolling 30-min session ID — same session_id within a 30-min window
+// - AbortController + 1000ms timeout, timer.unref() so we can't keep
+//   the process alive
+// - Payload includes: flag NAMES (no values), latency, success/error_code,
+//   chain (if relevant). NEVER the actual data the user queried.
+// - Fire-and-forget: errors are swallowed
+//
+// THE SINK IS NOT YET WIRED. `_send()` is a no-op until we have an
+// endpoint. Keeping the API shape stable now so we can flip the switch
+// later without a refactor.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const CONFIG_DIR = join(homedir(), '.vike');
+const ID_FILE = join(CONFIG_DIR, 'telemetry-id');
+const SESSION_FILE = join(CONFIG_DIR, 'session');
+const SESSION_TTL_MS = 30 * 60 * 1000;
+const ENDPOINT = process.env.VIKE_TELEMETRY_ENDPOINT || '';
+const REQUEST_TIMEOUT_MS = 1000;
+
+function disabled() {
+  return process.env.DO_NOT_TRACK === '1' ||
+         process.env.VIKE_NO_TELEMETRY === '1' ||
+         process.env.CI ||
+         process.env.NODE_ENV === 'test';
+}
+
+function ensureDir() {
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  }
+}
+
+function getDeviceId() {
+  try {
+    if (existsSync(ID_FILE)) return readFileSync(ID_FILE, 'utf8').trim();
+  } catch { /* ignore */ }
+  const id = randomUUID();
+  try { ensureDir(); writeFileSync(ID_FILE, id, { mode: 0o600 }); } catch { /* ignore */ }
+  return id;
+}
+
+function getSessionId() {
+  let prev = null;
+  try {
+    if (existsSync(SESSION_FILE)) {
+      prev = JSON.parse(readFileSync(SESSION_FILE, 'utf8'));
+    }
+  } catch { /* ignore */ }
+  const now = Date.now();
+  // Reuse session if within TTL; cheaply update touched timestamp at most
+  // once per minute to avoid hammering the file on rapid commands.
+  if (prev && prev.id && now - (prev.touched || 0) < SESSION_TTL_MS) {
+    if (now - (prev.touched || 0) > 60_000) {
+      try { writeFileSync(SESSION_FILE, JSON.stringify({ id: prev.id, touched: now })); }
+      catch { /* ignore */ }
+    }
+    return prev.id;
+  }
+  const id = randomUUID();
+  try {
+    ensureDir();
+    writeFileSync(SESSION_FILE, JSON.stringify({ id, touched: now }));
+  } catch { /* ignore */ }
+  return id;
+}
+
+function _send(event, payload) {
+  if (disabled() || !ENDPOINT) return;
+  // Fire-and-forget. No await; can't keep the process alive.
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
+  if (typeof timer.unref === 'function') timer.unref();
+  fetch(ENDPOINT, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      event,
+      device_id: getDeviceId(),
+      session_id: getSessionId(),
+      ts: Date.now(),
+      ...payload,
+    }),
+    signal: ctrl.signal,
+  })
+    .catch(() => { /* fire-and-forget */ })
+    .finally(() => clearTimeout(timer));
+}
+
+function flagNames(opts) {
+  // Extract flag names from a commander options object. Values stripped.
+  if (!opts || typeof opts !== 'object') return [];
+  return Object.keys(opts).filter((k) => !k.startsWith('_') && k !== 'parent');
+}
+
+export function trackCommandSucceeded(command, opts, { durationMs } = {}) {
+  _send('command_succeeded', {
+    command,
+    flags: flagNames(opts),
+    duration_ms: typeof durationMs === 'number' ? Math.round(durationMs) : null,
+  });
+}
+
+export function trackCommandFailed(command, opts, { errorCode, durationMs } = {}) {
+  _send('command_failed', {
+    command,
+    flags: flagNames(opts),
+    error_code: errorCode || 'unknown',
+    duration_ms: typeof durationMs === 'number' ? Math.round(durationMs) : null,
+  });
+}

package/src/update-check.js

@@ -0,0 +1,126 @@
+// Background update check — reads cached result synchronously on startup,
+// kicks off the registry probe as a detached subprocess that survives
+// process exit. Zero blocking I/O on the user's command.
+//
+// Pattern: print a one-liner the *next* time the user runs us, after the
+// background check has cached the result. No "checking for updates..."
+// spinner ever appears.
+//
+// Honors NO_UPDATE_NOTIFIER and CI (industry-standard opt-out).
+
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const CONFIG_DIR = join(homedir(), '.vike');
+const CHECK_FILE = join(CONFIG_DIR, 'update-check.json');
+const LAST_VERSION_FILE = join(CONFIG_DIR, 'last-version.json');
+const PACKAGE_NAME = '@vike-io/cli';
+const REGISTRY = 'https://registry.npmjs.org';
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 1 day
+
+function suppressed() {
+  return process.env.NO_UPDATE_NOTIFIER === '1' ||
+         process.env.CI ||
+         process.env.NODE_ENV === 'test' ||
+         process.env.VIKE_NO_UPDATE_CHECK === '1';
+}
+
+function readCache() {
+  if (!existsSync(CHECK_FILE)) return null;
+  try { return JSON.parse(readFileSync(CHECK_FILE, 'utf8')); } catch { return null; }
+}
+
+function writeCache(latest) {
+  try {
+    if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    writeFileSync(CHECK_FILE, JSON.stringify({ latest, checkedAt: Date.now() }, null, 2));
+  } catch { /* ignore */ }
+}
+
+function cmpSemver(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+  }
+  return 0;
+}
+
+// Synchronous: read whatever the background process last cached.
+// Returns a notification string or null. Call at startup.
+export function getUpdateNotification(currentVersion) {
+  if (suppressed()) return null;
+  const cache = readCache();
+  if (!cache || !cache.latest) return null;
+  if (cmpSemver(cache.latest, currentVersion) > 0) {
+    return (
+      `\n  Update available: ${currentVersion} → ${cache.latest}\n` +
+      `  Run: npm install -g ${PACKAGE_NAME}\n`
+    );
+  }
+  return null;
+}
+
+// Fire the check as a detached subprocess. Doesn't block process exit.
+// Honors a 1-day cache window — re-checking on every command would
+// hammer the npm registry.
+export function scheduleUpdateCheck() {
+  if (suppressed()) return;
+  const cache = readCache();
+  if (cache && Date.now() - (cache.checkedAt || 0) < CHECK_INTERVAL_MS) return;
+
+  const __filename = fileURLToPath(import.meta.url);
+  // Inline child script — no separate file needed, no dependency on
+  // package layout, survives `npm install -g` symlinking.
+  const code = `
+    const https = require('https');
+    const fs = require('fs');
+    const path = require('path');
+    const os = require('os');
+    const file = path.join(os.homedir(), '.vike', 'update-check.json');
+    https.get('${REGISTRY}/${PACKAGE_NAME}/latest', { timeout: 5000 }, (r) => {
+      let buf = '';
+      r.on('data', (c) => { buf += c; });
+      r.on('end', () => {
+        try {
+          const v = JSON.parse(buf).version;
+          if (!v) return;
+          fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+          fs.writeFileSync(file, JSON.stringify({ latest: v, checkedAt: Date.now() }));
+        } catch {}
+      });
+    }).on('error', () => {}).on('timeout', function () { this.destroy(); });
+  `;
+
+  try {
+    const child = spawn(process.execPath, ['-e', code], {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.unref();
+  } catch { /* ignore */ }
+}
+
+// First-run-after-upgrade hook. Stores last-seen version; if it changes,
+// prints a one-time "you upgraded" notice on the next command.
+export function getUpgradeNotice(currentVersion) {
+  if (suppressed()) return null;
+  let last = null;
+  try {
+    if (existsSync(LAST_VERSION_FILE)) {
+      last = JSON.parse(readFileSync(LAST_VERSION_FILE, 'utf8')).version;
+    }
+  } catch { /* ignore */ }
+  try {
+    if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    writeFileSync(LAST_VERSION_FILE, JSON.stringify({ version: currentVersion }));
+  } catch { /* ignore */ }
+  if (last && last !== currentVersion && cmpSemver(currentVersion, last) > 0) {
+    return `\n  Updated to ${currentVersion} (was ${last}).\n`;
+  }
+  return null;
+}