nansen-cli 2.5.0 → 2.6.1
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/CHANGELOG.md +52 -0
- package/README.md +19 -13
- package/docs/error-codes.md +1 -0
- package/package.json +5 -5
- package/scripts/postinstall.js +36 -11
- package/skills/nansen-alerts-webhook-listener/SKILL.md +1 -1
- package/skills/nansen-limit-orders/SKILL.md +6 -3
- package/skills/nansen-smart-alerts/SKILL.md +0 -21
- package/skills/nansen-token-research/SKILL.md +1 -1
- package/skills/nansen-trading/SKILL.md +18 -15
- package/skills/nansen-web-searcher/SKILL.md +1 -1
- package/src/api.js +0 -14
- package/src/bridge.js +48 -4
- package/src/cli.js +151 -117
- package/src/commands/alerts.js +54 -66
- package/src/commands/completion.js +0 -1
- package/src/commands/research.js +35 -35
- package/src/crypto.js +17 -0
- package/src/error-codes.js +1 -0
- package/src/execute-guard.js +43 -3
- package/src/input-validation.js +32 -3
- package/src/limit-order.js +12 -4
- package/src/perp.js +72 -13
- package/src/privy.js +145 -103
- package/src/schema.json +499 -93
- package/src/trade-validation.js +57 -2
- package/src/trading.js +14 -14
- package/src/transfer.js +65 -7
- package/src/wallet.js +9 -10
- package/skills/nansen-web-fetcher/SKILL.md +0 -53
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
|
-
|
|
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
|
|
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
|
-
|
|
1176
|
-
|
|
1177
|
-
|
|
1178
|
-
|
|
1179
|
-
|
|
1180
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1228
|
-
|
|
1229
|
-
|
|
1230
|
-
|
|
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,
|
|
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'
|
|
1555
|
-
description: 'Web search
|
|
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'
|
|
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
|
|
1983
|
-
const tokenSymbol = options.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.
|
|
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,16 +2426,16 @@ SUBCOMMANDS:
|
|
|
2437
2426
|
leaderboard Perp trader leaderboard (analytics)
|
|
2438
2427
|
|
|
2439
2428
|
USAGE:
|
|
2440
|
-
nansen perp order --
|
|
2441
|
-
nansen perp cancel --
|
|
2442
|
-
nansen perp close --
|
|
2443
|
-
nansen perp leverage --
|
|
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
|
|
2447
2436
|
nansen perp account
|
|
2448
2437
|
|
|
2449
|
-
BEFORE SUBMITTING (order, cancel, close, leverage):
|
|
2438
|
+
BEFORE SUBMITTING (order, cancel, close, leverage, transfer, approve-builder-fee):
|
|
2450
2439
|
--dry-run Validate and print what would be submitted, then stop. Exits 0.
|
|
2451
2440
|
--yes, -y Skip the confirmation prompt (same as NANSEN_YES=1). The prompt only
|
|
2452
2441
|
appears when stdin is a terminal; declining exits 1, signing nothing.`);
|
|
@@ -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
|
-
|
|
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 {
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
2846
|
-
|
|
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
|