nansen-cli 2.5.0 → 2.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/cli.js CHANGED
@@ -1010,8 +1010,9 @@ export async function traceCounterparties(api, params = {}) {
1010
1010
  queue.push({ addr: cpAddr, hop: hop + 1 });
1011
1011
  }
1012
1012
  }
1013
- } catch {
1014
- // Skip addresses that fail (404, etc) but continue the traversal
1013
+ } catch (error) {
1014
+ if (hop === 0) throw error;
1015
+ // Keep later lookups best-effort once the root has been fetched.
1015
1016
  }
1016
1017
 
1017
1018
  if (queue.length > 0) await sleep(delayMs);
@@ -1151,6 +1152,11 @@ export const HELP = `Nansen CLI v${VERSION} - analytics and DEX trading for AI a
1151
1152
 
1152
1153
  USAGE: nansen <command> [subcommand] [options]
1153
1154
 
1155
+ GET STARTED:
1156
+ nansen login Sign in through browser approval
1157
+ nansen research smart-money netflow --chain solana What smart money is buying and selling
1158
+ nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
1159
+
1154
1160
  COMMANDS:
1155
1161
  trade DEX swaps/bridges: quote, execute, bridge-status, limit-order
1156
1162
  bridge Hyperliquid bridge: quote, execute, status (EVM <-> HL)
@@ -1160,7 +1166,7 @@ COMMANDS:
1160
1166
  agent Ask the Nansen AI research agent (fast/expert modes)
1161
1167
  alerts list, create, update, toggle, delete
1162
1168
  feedback preferences, submit, resume, forget local data, or get a receipt (--json for structured output)
1163
- web search, fetch
1169
+ web search
1164
1170
  mcp install/uninstall/verify the Nansen MCP server
1165
1171
  account Check the effective credential, plan, and remaining credits (free)
1166
1172
  auth status — offline credential source and cached/unverified session metadata
@@ -1171,16 +1177,26 @@ COMMANDS:
1171
1177
  completion Shell completions: bash, zsh, fish
1172
1178
  cache stats, clear
1173
1179
  changelog --since <version> to filter
1180
+ help Topics: auth, options, examples, chains, labels, deprecated, telemetry
1174
1181
 
1175
- OPTIONS: --chain --limit --page N --sort field:dir --fields a,b --days N --filters '{}'
1176
- PAGING: --paginate (alias --all) fetch every page, --max-pages N (default 10), --limit sets page size
1177
- FORMAT: --pretty --table --format csv --stream (NDJSON)
1178
- RETRY: --no-retry --retries N --cache --cache-ttl N
1179
- DEBUG: --debug (or NANSEN_DEBUG=1) traces each request on stderr: method, URL,
1180
- status, time-to-headers (TTFB), retries, request id. Never prints
1181
- credentials or bodies.
1182
+ MORE HELP:
1183
+ nansen <command> --help Subcommands and options for one command
1184
+ nansen help <topic> One topic (see "help" above)
1185
+ nansen schema JSON schema for every command
1186
+ Docs: https://docs.nansen.ai
1187
+ Skills: npx -y skills add nansen-ai/nansen-cli --skill "*" -y (agent docs per command group)
1182
1188
 
1183
- AUTHENTICATION:
1189
+ Telemetry: anonymous usage stats. Details: nansen help telemetry. Disable: DO_NOT_TRACK=1
1190
+ `;
1191
+
1192
+ /**
1193
+ * Detail that used to sit on the top-level page, one topic per
1194
+ * `nansen help <topic>`. The top page stays a short index (every fresh agent
1195
+ * reads it), so longer reference text belongs here. Each topic is also a
1196
+ * `help` subcommand in schema.json, which feeds `nansen schema` and completion.
1197
+ */
1198
+ export const HELP_TOPICS = {
1199
+ auth: `AUTHENTICATION:
1184
1200
  nansen login Fresh browser approval, even with an existing key/session
1185
1201
  nansen login --no-browser Same approval without opening the browser
1186
1202
  nansen auth status Offline, cached/unverified; does not open session storage
@@ -1193,9 +1209,15 @@ AUTHENTICATION:
1193
1209
  Browser sessions renew automatically; uncertain renewal requires fresh login.
1194
1210
  Browser nansen:api sessions have API-key-equivalent account permissions; wallet signing is separate.
1195
1211
  Browser login is enabled in production; saved sessions need native storage (see docs/browser-login.md).
1196
- Public API endpoints keep their usual account, plan and credit checks; MCP key export is separate.
1197
-
1198
- TRADING:
1212
+ Public API endpoints keep their usual account, plan and credit checks; MCP key export is separate.`,
1213
+ options: `OPTIONS: --chain --limit --page N --sort field:dir --fields a,b --days N --filters '{}'
1214
+ PAGING: --paginate (alias --all) fetch every page, --max-pages N (default 10), --limit sets page size
1215
+ FORMAT: --pretty --table --format csv --stream (NDJSON)
1216
+ RETRY: --no-retry --retries N --cache --cache-ttl N
1217
+ DEBUG: --debug (or NANSEN_DEBUG=1) traces each request on stderr: method, URL,
1218
+ status, time-to-headers (TTFB), retries, request id. Never prints
1219
+ credentials or bodies.`,
1220
+ examples: `TRADING:
1199
1221
  nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
1200
1222
  nansen trade execute --quote <quoteId>
1201
1223
  nansen trade bridge-status --tx-hash <hash> --from-chain base --to-chain solana
@@ -1213,22 +1235,16 @@ EXAMPLES:
1213
1235
  nansen trade quote --chain base --to-chain solana --from USDC --to USDC --amount 1000000
1214
1236
  nansen research smart-money netflow --chain solana
1215
1237
  nansen research token screener --chain solana --timeframe 24h
1216
- nansen research profiler balance --address 0x... --chain ethereum
1217
-
1218
- DEPRECATED ALIASES (still work, will be removed in a future version):
1219
- smart-money, profiler, token, search, portfolio → use "nansen research <command>"
1220
- quote, execute → use "nansen trade <command>"
1221
-
1222
- Research chains: ${SCHEMA.chains.join(', ')}
1238
+ nansen research profiler balance --address 0x... --chain ethereum`,
1239
+ chains: `Research chains: ${SCHEMA.chains.join(', ')}
1223
1240
  Trade chains: solana, base
1224
- Bridge routes: ${formatBridgeRoutes()}
1225
- Labels: Smart Trader, 30D/90D/180D Smart Trader, Smart HL Perps Trader (Smart Trader covers all windows; Fund is no longer a Smart Money label)
1226
-
1227
- Docs: https://docs.nansen.ai
1228
- Skills: npx skills add nansen-ai/nansen-cli (agent-optimised docs per command group)
1229
-
1230
- Telemetry: anonymous usage stats (commands, timing, errors). Perp order/close additionally send each leg's side, outcome, order id, shared submission id, and a SHA-256 wallet identifier. Raw wallet, price, size, and exchange error text are not sent. Disable: DO_NOT_TRACK=1
1231
- `;
1241
+ Bridge routes: ${formatBridgeRoutes()}`,
1242
+ labels: `Labels: Smart Trader, 30D/90D/180D Smart Trader, Smart HL Perps Trader (Smart Trader covers all windows; Fund is no longer a Smart Money label)`,
1243
+ deprecated: `DEPRECATED ALIASES (still work, will be removed in a future version):
1244
+ smart-money, profiler, token, search, portfolio → use "nansen research <command>"
1245
+ quote, execute → use "nansen trade <command>"`,
1246
+ telemetry: `Telemetry: anonymous usage stats (commands, timing, errors). Perp order/close additionally send each leg's side, outcome, order id, shared submission id, and a SHA-256 wallet identifier. Raw wallet, price, size, and exchange error text are not sent. Disable: DO_NOT_TRACK=1`,
1247
+ };
1232
1248
 
1233
1249
  // Usage text for the `cache` command group. Also the answer to "which commands
1234
1250
  // cache?" — caching is decided by the request path, so the rule lives here (and
@@ -1250,7 +1266,7 @@ WHAT CACHES:
1250
1266
  every read the CLI makes through the Nansen API client is served from and
1251
1267
  written to the response cache — that is all of "nansen research ...", plus
1252
1268
  "alerts list" and "alerts get".
1253
- Never cached: account, web search, web fetch, alerts create/update/toggle/delete,
1269
+ Never cached: account, web search, alerts create/update/toggle/delete,
1254
1270
  agent (streamed), feedback, every trade, bridge, wallet and mcp command, and perp trading.
1255
1271
  The analytics commands "perp screener" and "perp leaderboard" are cached.
1256
1272
 
@@ -1523,46 +1539,18 @@ export function buildCommands(deps = {}) {
1523
1539
  return apiInstance.webSearch({ queries, numResults });
1524
1540
  },
1525
1541
 
1526
- 'fetch': async () => {
1527
- // Accept URLs as positional args or --url (repeated)
1528
- let urls = subArgs.length > 0 ? subArgs : [];
1529
- if (options.url !== undefined) {
1530
- const fromOption = Array.isArray(options.url) ? options.url : [options.url];
1531
- urls = urls.concat(fromOption);
1532
- }
1533
- if (urls.length === 0) {
1534
- throw new NansenError('At least one URL is required. Usage: nansen web fetch https://example.com --question "What is this about?"', ErrorCode.MISSING_PARAM);
1535
- }
1536
- for (const u of urls) {
1537
- try { new URL(u); } catch {
1538
- throw new NansenError(`Invalid URL: "${u}". URLs must include a scheme, e.g. https://example.com`, ErrorCode.INVALID_PARAMS);
1539
- }
1540
- }
1541
- if (Array.isArray(options.question)) {
1542
- throw new NansenError('--question may only be specified once', ErrorCode.INVALID_PARAMS);
1543
- }
1544
- if (options.question !== undefined && typeof options.question !== 'string') {
1545
- throw new NansenError('--question must be a string', ErrorCode.INVALID_PARAMS);
1546
- }
1547
- if (!options.question || !options.question.trim()) {
1548
- throw new NansenError('--question is required and cannot be blank. Usage: nansen web fetch https://example.com --question "What is this about?"', ErrorCode.MISSING_PARAM);
1549
- }
1550
- return apiInstance.webFetch({ urls, question: options.question });
1551
- },
1552
-
1553
1542
  'help': async () => ({
1554
- subcommands: ['search', 'fetch'],
1555
- description: 'Web search and fetch commands',
1543
+ subcommands: ['search'],
1544
+ description: 'Web search commands',
1556
1545
  examples: [
1557
1546
  'nansen web search "bitcoin price"',
1558
1547
  'nansen web search "solana news" --num-results 5',
1559
- 'nansen web fetch https://nansen.ai --question "What does Nansen do?"',
1560
1548
  ],
1561
1549
  }),
1562
1550
  };
1563
1551
 
1564
1552
  if (!Object.hasOwn(handlers, subcommand)) {
1565
- throw unknownCommandError('web subcommand', subcommand, ['search', 'fetch']);
1553
+ throw unknownCommandError('web subcommand', subcommand, ['search']);
1566
1554
  }
1567
1555
 
1568
1556
  return handlers[subcommand]();
@@ -1976,11 +1964,12 @@ export function buildCommands(deps = {}) {
1976
1964
  rejectBlankOption(options.chain, 'chain', 'solana');
1977
1965
  rejectBlankOption(options.chains, 'chains', 'solana');
1978
1966
  rejectBlankOption(options.timeframe, 'timeframe', '1d');
1967
+ rejectBlankOption(options.interval, 'interval', '1d');
1979
1968
  rejectBlankOption(options['buy-or-sell'], 'buy-or-sell', 'SELL');
1980
1969
  const subcommand = args[0] || 'help';
1981
1970
  const chain = options.chain || 'solana';
1982
- const tokenAddress = normalizeAddress(options.token || options['token-address'], chain);
1983
- const tokenSymbol = options.symbol || options['token-symbol'];
1971
+ const tokenAddress = normalizeAddress(options.token, chain);
1972
+ const tokenSymbol = options.symbol;
1984
1973
  const chains = parseCsvOption(options.chains, 'chains') || [chain];
1985
1974
  const timeframe = options.timeframe || '24h';
1986
1975
  const filters = parseFiltersOption(options.filters);
@@ -2013,7 +2002,7 @@ export function buildCommands(deps = {}) {
2013
2002
 
2014
2003
  const handlers = {
2015
2004
  'indicators': () => apiInstance.tokenIndicators({ tokenAddress, chain }),
2016
- 'ohlcv': () => apiInstance.tokenOhlcv({ tokenAddress, chain, timeframe: options.timeframe || '1d' }),
2005
+ 'ohlcv': () => apiInstance.tokenOhlcv({ tokenAddress, chain, timeframe: options.interval || '1d' }),
2017
2006
  'info': () => apiInstance.tokenInformation({ tokenAddress, chain, timeframe: options.timeframe }),
2018
2007
  'screener': async () => {
2019
2008
  const search = options.search;
@@ -2437,10 +2426,10 @@ SUBCOMMANDS:
2437
2426
  leaderboard Perp trader leaderboard (analytics)
2438
2427
 
2439
2428
  USAGE:
2440
- nansen perp order --coin BTC --side buy --size 0.001 --price 50000 --type limit
2441
- nansen perp cancel --coin BTC --oid 12345
2442
- nansen perp close --coin BTC --size 0.001 --price 100000 --side sell
2443
- nansen perp leverage --coin BTC --leverage 10 --margin-type cross
2429
+ nansen perp order --symbol BTC --side buy --size 0.001 --price 50000 --type limit
2430
+ nansen perp cancel --symbol BTC --oid 12345
2431
+ nansen perp close --symbol BTC --size 0.001 --price 100000 --side sell
2432
+ nansen perp leverage --symbol BTC --leverage 10 --margin-type cross
2444
2433
  nansen perp transfer --direction spot-to-perp --amount 25
2445
2434
  nansen perp approve-builder-fee
2446
2435
  nansen perp positions
@@ -2528,6 +2517,28 @@ function costHelpLines(endpoint, options = {}) {
2528
2517
  return lines;
2529
2518
  }
2530
2519
 
2520
+ // One line per positional arg and option, from the schema: name, required
2521
+ // marker, aliases, default, enum, and what it does. Every --help body that
2522
+ // lists options goes through here, so agents never need `nansen schema` just
2523
+ // to learn what a flag means.
2524
+ export function formatOptionHelp(options = {}, args = []) {
2525
+ const line = (label, opt) => {
2526
+ const parts = [`${label}${opt.required ? '*' : ''}`];
2527
+ if (opt.aliases?.length) parts.push(`(alias ${opt.aliases.map(a => `--${a}`).join(', ')})`);
2528
+ if (opt.default !== undefined) parts.push(`(${opt.default})`);
2529
+ if (opt.enum) parts.push(`[${opt.enum.join('|')}]`);
2530
+ if (opt.repeatable) parts.push('(repeatable)');
2531
+ if (opt.requiredUnless?.length) parts.push(`(unless ${opt.requiredUnless.map(o => `--${o}`).join(', ')})`);
2532
+ if (opt.description) parts.push(`— ${opt.description}`);
2533
+ return ` ${parts.join(' ')}`;
2534
+ };
2535
+ const lines = [
2536
+ ...args.map(arg => line(`<${arg.name}>`, arg)),
2537
+ ...Object.entries(options).map(([name, opt]) => line(`--${name}`, opt)),
2538
+ ];
2539
+ return lines.length ? ['Options (* required):', ...lines] : [];
2540
+ }
2541
+
2531
2542
  // Generate help text for a specific subcommand using SCHEMA
2532
2543
  export function generateSubcommandHelp(command, subcommand, prefix = null) {
2533
2544
  // `perp` is both a top-level trading command and a research category, and
@@ -2554,23 +2565,7 @@ export function generateSubcommandHelp(command, subcommand, prefix = null) {
2554
2565
  return lines.join('\n');
2555
2566
  }
2556
2567
 
2557
- const positional = subSchema.args ?? [];
2558
- if (subSchema.options || positional.length) {
2559
- const describe = (label, opt) => {
2560
- const parts = [`${label}${opt.required ? '*' : ''}`];
2561
- if (opt.default !== undefined) parts.push(`(${opt.default})`);
2562
- if (opt.enum) parts.push(`[${opt.enum.join('|')}]`);
2563
- if (command.startsWith('trade') && opt.description) parts.push(`— ${opt.description}`);
2564
- return parts.join(' ');
2565
- };
2566
- const params = [
2567
- ...positional.map(arg => describe(`<${arg.name}>`, arg)),
2568
- ...Object.entries(subSchema.options ?? {}).map(([name, opt]) => describe(`--${name}`, opt)),
2569
- ];
2570
- lines.push(command.startsWith('trade')
2571
- ? `Options (* required):\n ${params.join('\n ')}`
2572
- : `Params (* required): ${params.join(', ')}`);
2573
- }
2568
+ lines.push(...formatOptionHelp(subSchema.options, subSchema.args));
2574
2569
 
2575
2570
  if (subSchema.supportedChains?.length) {
2576
2571
  lines.push(`Chains: ${subSchema.supportedChains.join(', ')}`);
@@ -2615,6 +2610,18 @@ export function generateSubcommandHelp(command, subcommand, prefix = null) {
2615
2610
  return lines.join('\n');
2616
2611
  }
2617
2612
 
2613
+ // A research command run without --chain/--chains uses its schema default
2614
+ // chain. Say so in `_meta.defaults.chain`, so an agent that left the chain out
2615
+ // knows which chain the data is for. The schema default is the chain the
2616
+ // handler sends (a test checks this). Only plain-object results get it, like
2617
+ // `_meta.search`; arrays, --fields, --stream, --table and CSV are unchanged.
2618
+ export function withDefaultChainMeta(result, researchCommand, options) {
2619
+ const chain = researchCommand?.leaf?.options?.chain?.default;
2620
+ if (chain === undefined || options.chain !== undefined || options.chains !== undefined) return result;
2621
+ if (!result || typeof result !== 'object' || Array.isArray(result)) return result;
2622
+ return { ...result, _meta: { ...result._meta, defaults: { ...result._meta?.defaults, chain } } };
2623
+ }
2624
+
2618
2625
  function emitResponseMetadata(api, errorOutput) {
2619
2626
  if (!api) return;
2620
2627
  const responseMeta = api.paginatedResponseMeta || api.lastResponseMeta;
@@ -2708,7 +2715,23 @@ export async function runCLI(rawArgs, deps = {}) {
2708
2715
  exit(1);
2709
2716
  return { type: 'error', data: errorData };
2710
2717
  }
2711
- const { _: positional, flags, options } = parsed;
2718
+ const { flags, options } = parsed;
2719
+ let positional = parsed._;
2720
+
2721
+ // `nansen help <topic>` prints one topic of HELP_TOPICS. `nansen help
2722
+ // <command> [sub...]` is the same request as `nansen <command> [sub...] --help`,
2723
+ // so rewrite it here and let the usual help paths answer it.
2724
+ let helpTopic = null;
2725
+ let helpRequestedFor = null;
2726
+ if (positional[0] === 'help' && positional.length > 1) {
2727
+ if (positional.length === 2 && Object.hasOwn(HELP_TOPICS, positional[1])) {
2728
+ helpTopic = positional[1];
2729
+ } else {
2730
+ helpRequestedFor = positional[1];
2731
+ positional = positional.slice(1);
2732
+ flags.help = true;
2733
+ }
2734
+ }
2712
2735
 
2713
2736
  // Resolve command aliases
2714
2737
  const rawCommand = positional[0] || 'help';
@@ -2726,10 +2749,20 @@ export async function runCLI(rawArgs, deps = {}) {
2726
2749
  const stream = flags.stream || flags.s;
2727
2750
  const csv = options.format === 'csv';
2728
2751
 
2752
+ // mcp prints its own output via `log`; runCLI callers inject their stdout
2753
+ // sink as `output`, so map it across (an explicit `log` dep still wins).
2754
+ // Only execute/login handlers consume the stdin-interactivity seam. Other
2755
+ // modules retain their existing deps: notably wallet export interprets
2756
+ // `isTTY` as stdout visibility when deciding whether to warn about printing
2757
+ // private keys, so substituting the stdin signal there changes its semantics.
2758
+ const commands = { ...buildCommands(inputInteractiveDeps), ...buildWalletCommands(deps), ...buildTradingCommands(topLevelTradingDeps), ...buildAlertsCommands(deps), ...buildAgentCommands(deps), ...buildFeedbackCommands({ ...deps, log: deps.log ?? output }), ...buildMcpCommands({ ...deps, log: deps.log ?? output }), ...buildCompletionCommands({ ...deps, log: deps.log ?? output }), ...commandOverrides };
2759
+
2729
2760
  // Commands in this set promise zero network activity. That includes update
2730
2761
  // checks, cost-map refreshes and telemetry, not just their primary work.
2731
2762
  // `cache` belongs here specifically so inspecting or clearing caches cannot
2732
- // recreate update/telemetry state during the same invocation.
2763
+ // recreate update/telemetry state during the same invocation. `help` is the
2764
+ // top-level page and its topics only: `help <command>` was rewritten above,
2765
+ // so it behaves like `<command> --help`.
2733
2766
  const isMcpUsage = command === 'mcp' && (subcommand !== 'verify' || flags.help || flags.h);
2734
2767
  const isAuthMutation = command === 'login' || command === 'logout';
2735
2768
  const isOfflineLimitOrderDryRun = command === 'trade'
@@ -2737,12 +2770,15 @@ export async function runCLI(rawArgs, deps = {}) {
2737
2770
  && (subArgs[1] === 'create' || subArgs[1] === 'cancel')
2738
2771
  && flags['dry-run'] === true;
2739
2772
  const isOfflineCommand = command === 'auth'
2773
+ || command === 'help'
2740
2774
  || (command === 'doctor' && flags.offline)
2741
2775
  || isMcpUsage
2742
2776
  || command === 'completion'
2743
2777
  || command === 'cache'
2744
2778
  || (command === 'feedback' && subcommand === 'forget')
2745
- || isOfflineLimitOrderDryRun;
2779
+ || isOfflineLimitOrderDryRun
2780
+ // Help for a name that is not a command prints only the top page or an error.
2781
+ || ((flags.help || flags.h) && !commands[command]);
2746
2782
  const trackSucceeded = isOfflineCommand ? async () => {} : isAuthMutation ? metadata => trackAuthCommand({ ...metadata, command }) : trackCommandSucceeded;
2747
2783
  const trackFailed = isOfflineCommand ? async () => {} : isAuthMutation ? metadata => trackAuthCommand({ ...metadata, command, failed: true }) : trackCommandFailed;
2748
2784
 
@@ -2762,14 +2798,6 @@ export async function runCLI(rawArgs, deps = {}) {
2762
2798
  return '';
2763
2799
  };
2764
2800
 
2765
- // mcp prints its own output via `log`; runCLI callers inject their stdout
2766
- // sink as `output`, so map it across (an explicit `log` dep still wins).
2767
- // Only execute/login handlers consume the stdin-interactivity seam. Other
2768
- // modules retain their existing deps: notably wallet export interprets
2769
- // `isTTY` as stdout visibility when deciding whether to warn about printing
2770
- // private keys, so substituting the stdin signal there changes its semantics.
2771
- const commands = { ...buildCommands(inputInteractiveDeps), ...buildWalletCommands(deps), ...buildTradingCommands(topLevelTradingDeps), ...buildAlertsCommands(deps), ...buildAgentCommands(deps), ...buildFeedbackCommands({ ...deps, log: deps.log ?? output }), ...buildMcpCommands({ ...deps, log: deps.log ?? output }), ...buildCompletionCommands({ ...deps, log: deps.log ?? output }), ...commandOverrides };
2772
-
2773
2801
  if (flags.version || flags.v) {
2774
2802
  output(VERSION);
2775
2803
  return { type: 'version', data: VERSION };
@@ -2782,7 +2810,15 @@ export async function runCLI(rawArgs, deps = {}) {
2782
2810
  if (command === 'help' || ((flags.help || flags.h) && !unavailableCommand)) {
2783
2811
  // Help for an offline command still owes the zero-network contract: the
2784
2812
  // cost-map refresh fetches the OpenAPI spec and writes ~/.nansen/cost-map.json.
2785
- if (!isOfflineCommand && !isAuthMutation) await refreshCostMapIfStale();
2813
+ // The top-level page and its topics (`help` is offline) show no costs, so
2814
+ // they skip the refresh: on a cold or stale cache it fetches the spec
2815
+ // before printing.
2816
+ if (commands[command] && !isOfflineCommand && !isAuthMutation) await refreshCostMapIfStale();
2817
+ if (helpTopic) {
2818
+ output(HELP_TOPICS[helpTopic]);
2819
+ notify();
2820
+ return { type: 'help-topic', topic: helpTopic };
2821
+ }
2786
2822
  // Check for subcommand-specific help: nansen <command> <subcommand> --help
2787
2823
  if (flags.help || flags.h) {
2788
2824
  // Handle 'research <category> <sub> --help' (3-level)
@@ -2807,13 +2843,7 @@ export async function runCLI(rawArgs, deps = {}) {
2807
2843
  lines.push(`Use: nansen research ${category} <subcommand> --help`);
2808
2844
  } else if (catSchema.options) {
2809
2845
  // Leaf historical subcommand: render options + example
2810
- const params = Object.entries(catSchema.options).map(([name, opt]) => {
2811
- const parts = [`--${name}`];
2812
- if (opt.required) parts[0] += '*';
2813
- if (opt.default !== undefined) parts.push(`(${opt.default})`);
2814
- return parts.join(' ');
2815
- });
2816
- lines.push(`Params (* required): ${params.join(', ')}`);
2846
+ lines.push(...formatOptionHelp(catSchema.options));
2817
2847
  if (catSchema.endpoint) lines.push(...costHelpLines(catSchema.endpoint, catSchema.options));
2818
2848
  }
2819
2849
  output(lines.join('\n'));
@@ -2823,7 +2853,7 @@ export async function runCLI(rawArgs, deps = {}) {
2823
2853
  }
2824
2854
  // First try subcommand help
2825
2855
  // Skip for 'trade'/'alerts' — their handlers show their own rich usage
2826
- if (command && subcommand && command !== 'trade' && command !== 'alerts' && command !== 'agent') {
2856
+ if (command && subcommand && command !== 'help' && command !== 'trade' && command !== 'alerts' && command !== 'agent') {
2827
2857
  const subHelp = generateSubcommandHelp(command, subcommand);
2828
2858
  if (subHelp) {
2829
2859
  output(deprecationNote(command) + subHelp);
@@ -2833,7 +2863,9 @@ export async function runCLI(rawArgs, deps = {}) {
2833
2863
  }
2834
2864
  // Then try command-level help (list subcommands)
2835
2865
  // Skip for 'trade'/'alerts'/'cache' — let the handler show its own usage
2836
- const cmdSchemaLookup = command !== 'trade' && command !== 'alerts' && command !== 'agent' && command !== 'cache' && (SCHEMA.commands[command] || SCHEMA.commands.research.subcommands[command]);
2866
+ // `help` is in schema.json for `nansen schema` and completion, but
2867
+ // `nansen --help` and `nansen help --help` show the top-level page.
2868
+ const cmdSchemaLookup = command !== 'help' && command !== 'trade' && command !== 'alerts' && command !== 'agent' && command !== 'cache' && (SCHEMA.commands[command] || SCHEMA.commands.research.subcommands[command]);
2837
2869
  if (command && cmdSchemaLookup) {
2838
2870
  const cmdSchema = cmdSchemaLookup;
2839
2871
  const lines = [`${command} — ${cmdSchema.description}`];
@@ -2842,16 +2874,8 @@ export async function runCLI(rawArgs, deps = {}) {
2842
2874
  lines.push('Subcommands: ' + Object.keys(cmdSchema.subcommands).join(', '));
2843
2875
  lines.push(`Use: nansen ${command} <subcommand> --help`);
2844
2876
  }
2845
- if (cmdSchema.options) {
2846
- const params = Object.entries(cmdSchema.options).map(([name, opt]) => {
2847
- const parts = [`--${name}`];
2848
- if (opt.required) parts[0] += '*';
2849
- if (opt.default !== undefined) parts.push(`(default: ${opt.default})`);
2850
- if (opt.description) parts.push(`— ${opt.description}`);
2851
- return parts.join(' ');
2852
- });
2853
- lines.push(`\nOptions (* required):\n ${params.join('\n ')}`);
2854
- }
2877
+ const optionLines = formatOptionHelp(cmdSchema.options);
2878
+ if (optionLines.length) lines.push(`\n${optionLines.join('\n')}`);
2855
2879
  if (cmdSchema.examples?.length) {
2856
2880
  lines.push(`\nExamples:\n ${cmdSchema.examples.join('\n ')}`);
2857
2881
  }
@@ -2883,6 +2907,14 @@ export async function runCLI(rawArgs, deps = {}) {
2883
2907
  notify();
2884
2908
  return { type: 'command-help', command };
2885
2909
  }
2910
+ // `nansen help <name>` where <name> is neither a topic nor a command.
2911
+ if (helpRequestedFor && !commands[command]) {
2912
+ const available = [...new Set([...Object.keys(HELP_TOPICS), ...Object.keys(commands).filter(name => name !== 'help' && !UNAVAILABLE_COMMANDS.has(name))])];
2913
+ const errorData = formatError(unknownCommandError('help topic or command', helpRequestedFor, available));
2914
+ output(formatOutput(errorData, { pretty, table, csv }).text);
2915
+ exit(1);
2916
+ return { type: 'error', data: errorData };
2917
+ }
2886
2918
  // 'help' and unknown commands: full banner + command list
2887
2919
  if (command === 'help' || !commands[command]) {
2888
2920
  output(BANNER + HELP);
@@ -3036,6 +3068,8 @@ export async function runCLI(rawArgs, deps = {}) {
3036
3068
  returns: researchCommand?.leaf?.returns,
3037
3069
  });
3038
3070
  result = filterFields(result, fields);
3071
+ } else if (!stream && !table && !csv) {
3072
+ result = withDefaultChainMeta(result, researchCommand, options);
3039
3073
  }
3040
3074
 
3041
3075
  // Alerts list with --table uses custom table format
@@ -781,7 +781,7 @@ Run: nansen alerts <subcommand> --help`,
781
781
  list: `nansen alerts list — List all alerts
782
782
 
783
783
  USAGE:
784
- nansen alerts list [--table] [--pretty] [--type <type>] [--enabled|--disabled] [--token-address <addr>] [--chain <chain>] [--limit <n>] [--offset <n>] [--reveal]
784
+ nansen alerts list [--table] [--pretty] [--type <type>] [--enabled|--disabled] [--token <addr>] [--chain <chain>] [--limit <n>] [--offset <n>] [--reveal]
785
785
 
786
786
  OPTIONS:
787
787
  --table Human-readable table output (columns: ID, NAME, TYPE, ENABLED, CHANNELS)
@@ -789,7 +789,7 @@ OPTIONS:
789
789
  --reveal Show full channel webhook URLs and secrets (redacted by default)
790
790
  --type <type> Filter by alert type (sm-token-flows, common-token-transfer, smart-contract-call)
791
791
  --enabled / --disabled Filter by enabled state
792
- --token-address <addr> Filter by token address
792
+ --token <addr> Filter by token address (alias --token-address)
793
793
  --chain <chain> Filter by chain
794
794
  --limit <n> Max results
795
795
  --offset <n> Skip first N results
@@ -890,7 +890,10 @@ OPTIONS:
890
890
  delete: `nansen alerts delete — Delete an alert
891
891
 
892
892
  USAGE:
893
- nansen alerts delete <id>`,
893
+ nansen alerts delete <id>
894
+
895
+ OPTIONS:
896
+ --reveal Show full channel URLs and secrets in the response (redacted by default)`,
894
897
  };
895
898
 
896
899
  if (!sub || sub === 'help') {
@@ -954,7 +957,13 @@ USAGE:
954
957
 
955
958
  const offset = parseNonNegativeIntegerOption(options.offset, 'offset');
956
959
  const limit = parseNonNegativeIntegerOption(options.limit, 'limit');
957
- const tokenAddress = parseStringFilter(options['token-address'], 'token-address');
960
+ // --token-address is the old name of --token.
961
+ const token = parseStringFilter(options.token, 'token');
962
+ const legacyToken = parseStringFilter(options['token-address'], 'token-address');
963
+ if (token && legacyToken) {
964
+ throw new NansenError(`--token ${token} and --token-address ${legacyToken} are the same input; pass one.`, ErrorCode.INVALID_PARAMS);
965
+ }
966
+ const tokenAddress = token ?? legacyToken;
958
967
  const chainFilter = parseStringFilter(options.chain, 'chain');
959
968
 
960
969
  const results = await apiInstance.alertsList();
@@ -33,7 +33,6 @@ export const UNSCHEMA_COMMANDS = {
33
33
  description: 'Show release history',
34
34
  options: { since: { type: 'string', description: 'Only show versions at or above this one' } },
35
35
  },
36
- help: { description: 'Show the top-level help' },
37
36
  };
38
37
 
39
38
  /**