moralis-cli 0.1.0

package/.codex/skills/moralis-cli/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: moralis-cli
+description: Use the local `moralis-cli` project to access Moralis EVM and Solana data through swagger-generated CLI commands. Trigger this skill when a user wants to list available Moralis operations, log in with a Moralis API key, map a blockchain data request to an `operationId`, or run Moralis CLI commands with required path arguments and optional flags. If a user asks for Moralis endpoint data, DO NOT fallback to web search or hand-crafting HTTP requests.
+---
+
+# Moralis CLI
+
+## Overview
+
+Use the repo-local `moralis-cli` to execute Moralis API requests from the terminal.
+Prefer running the CLI directly instead of hand-crafting HTTP requests when the user asks for Moralis endpoint data.
+
+## Quick Start
+
+Run from the repository root.
+
+Use one of these forms:
+
+- `moralis-cli ...` (if installed via `npm link`)
+- `node bin/moralis-cli.js ...` (always works inside the repo)
+
+List commands:
+
+```bash
+moralis-cli help
+moralis-cli evm help
+moralis-cli solana help
+```
+
+Log in (save API key):
+
+```bash
+moralis-cli login <api_key>
+# or interactive hidden prompt
+moralis-cli login
+```
+
+Run an endpoint command:
+
+```bash
+moralis-cli evm getTransaction <transaction_hash>
+moralis-cli evm getTransaction <transaction_hash> --chain eth
+moralis-cli solana balance mainnet <wallet_address>
+```
+
+Inspect one command's arguments:
+
+```bash
+moralis-cli evm getTransaction --help
+moralis-cli solana balance --help
+```
+
+## Workflow
+
+1. Run `moralis-cli help` (or `moralis-cli evm help` / `moralis-cli solana help`) to discover available `operationId` commands by namespace.
+2. Match the user's requested endpoint/action to the correct namespace (`evm` or `solana`) and command name.
+3. Run `moralis-cli <namespace> <operationId> --help` to see required path arguments and optional flags.
+4. Ask for missing required values only (for example transaction hash, wallet address, chain).
+5. Execute the command and return the JSON output (or summarize it if the user prefers).
+
+## Parameter Mapping
+
+- Treat Swagger/OpenAPI `path` parameters as positional CLI arguments in path order.
+- Treat non-path parameters (`query`, `header`, `formData`, `body`) as flags: `--name value`.
+- Pass booleans as `--flag` / `--no-flag` when supported.
+- Pass JSON body parameters as a JSON string, for example:
+
+```bash
+moralis-cli evm somePostOp <id> --bodyParam '{"key":"value"}'
+```
+
+## Troubleshooting
+
+- If `moralis-cli` is not found, run `node bin/moralis-cli.js ...` from the repo root or install with `npm link`.
+- If login cannot prompt, use `moralis-cli login <api_key>` (non-interactive).
+- If swagger cannot load, retry when network access is available. The CLI caches each spec (`evm` and `solana`) after a successful fetch.
+- If a command is unknown, refresh with `moralis-cli evm help` or `moralis-cli solana help` and use the exact `operationId`.
+
+## Examples
+
+- User asks: "Show me a transaction on Moralis for this hash."
+  Run: `moralis-cli evm getTransaction <transaction_hash>`
+- User asks: "Show me a Solana wallet balance on Moralis."
+  Run: `moralis-cli solana balance <network> <wallet_address>`
+- User asks: "What commands does this CLI support?"
+  Run: `moralis-cli help`
+- User asks: "Log me in to Moralis CLI."
+  Run: `moralis-cli login` (interactive) or `moralis-cli login <api_key>`

package/.codex/skills/moralis-cli/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Moralis CLI"
+  short_description: "Access EVM blockchain data via Moralis CLI"
+  default_prompt: "Use $moralis-cli to list operations, help with login, and run the correct moralis-cli command for a Moralis API request."

package/.prettierrc

@@ -0,0 +1,9 @@
+{
+	"printWidth": 140,
+	"singleQuote": true,
+	"trailingComma": "none",
+	"semi": true,
+	"useTabs": false,
+	"tabWidth": 2,
+	"arrowParens": "avoid"
+}

package/.vscode/settings.json

@@ -0,0 +1,9 @@
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "files.exclude": {
+    "**/dist": true,
+    "**/lib": true,
+    "**/node_modules": true
+  }
+}

package/README.md

@@ -0,0 +1,54 @@
+# Moralis CLI
+
+Use the Moralis API via Moralis CLI directly inside your AI agent 🤖 while keeping your API key secure and enabling smooth interaction.
+
+## Getting Started
+
+Follow these steps to start using Moralis CLI with your AI agent.
+
+## Getting Started
+
+Install:
+
+```bash
+npx -g moralis-cli
+```
+
+Login:
+
+```bash
+moralis-cli login
+```
+
+Enter your Moralis API key when prompted (stored securely).
+
+Connect to AI
+
+Import the [@moralis-cli](.codex/skills/moralis-cli/SKILL.md) skill into your AI agent and start making Moralis API calls securely.
+
+## Examples
+
+Codex:
+
+```bash
+› get my balance on solana chain kXB7FfzdrfZpAZEW3TZcp8a8CwQbsowa6BdfAHZ4gVs $moralis-cli
+
+• Using the moralis-cli skill for this directly. I’ll run the Solana balance command on mainnet for that wallet and return the current value.
+
+• Ran node bin/moralis-cli.js solana balance mainnet kXB7FfzdrfZpAZEW3TZcp8a8CwQbsowa6BdfAHZ4gVs
+  └ {
+      "lamports": "24544198",
+      "solana": "0.024544198"
+    }
+
+──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+• moralis-cli Solana balance for kXB7FfzdrfZpAZEW3TZcp8a8CwQbsowa6BdfAHZ4gVs (mainnet):
+
+  - 0.024544198 SOL
+  - 24,544,198 lamports
+```
+
+# License
+
+MIT

package/bin/moralis-cli.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+const { main } = require('../src/cli');
+
+main().catch(error => {
+  const message = error && error.message ? error.message : String(error);
+  console.error(`Error: ${message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "moralis-cli",
+  "version": "0.1.0",
+  "description": "Use Moralis API via Moralis CLI directly inside AI agents with secure API key handling and access to EVM and Solana blockchain data.",
+  "bin": {
+    "moralis-cli": "bin/moralis-cli.js"
+  },
+  "type": "commonjs",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "prettier": "^3.8.1"
+  },
+  "scripts": {
+    "start": "node bin/moralis-cli.js",
+    "help": "node bin/moralis-cli.js help"
+  },
+  "keywords": [
+    "moralis",
+    "moralis api",
+    "moralis cli",
+    "ai integration",
+    "ai agent",
+    "llm tools",
+    "blockchain api",
+    "web3 api",
+    "evm data",
+    "solana data",
+    "crypto data",
+    "onchain data",
+    "developer cli",
+    "web3 developer tools"
+  ]
+}

package/src/cli.js

@@ -0,0 +1,1119 @@
+'use strict';
+
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+
+const CONFIG_DIR = process.env.MORALIS_CLI_CONFIG_DIR || path.join(os.homedir(), '.moralis-cli');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
+const SWAGGER_CACHE_MAX_AGE_MS = 6 * 60 * 60 * 1000;
+const DEFAULT_FETCH_RETRY_ATTEMPTS = 3;
+const DEFAULT_FETCH_RETRY_BASE_DELAY_MS = 400;
+const API_TARGETS = Object.freeze({
+  evm: {
+    namespace: 'evm',
+    label: 'EVM',
+    swaggerUrl: 'https://deep-index.moralis.io/api-docs-2.2/v2.2/swagger.json',
+    prodBaseUrl: 'https://deep-index.moralis.io/api/v2.2/',
+    cacheFileName: 'swagger-cache-evm.json'
+  },
+  solana: {
+    namespace: 'solana',
+    label: 'Solana',
+    swaggerUrl: 'https://solana-gateway.moralis.io/api-json',
+    prodBaseUrl: 'https://solana-gateway.moralis.io/',
+    cacheFileName: 'swagger-cache-solana.json'
+  }
+});
+
+async function main() {
+  ensureFetchSupport();
+
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (!command || isHelpToken(command)) {
+    await printGlobalHelp(args.slice(1));
+    return;
+  }
+
+  if (command === 'login') {
+    await login(args.slice(1));
+    return;
+  }
+
+  const apiTarget = getApiTarget(command);
+  if (apiTarget) {
+    await handleApiCommand(apiTarget, args.slice(1));
+    return;
+  }
+
+  console.error(`Unknown command: ${command}`);
+  console.error('Run `moralis-cli help` to see supported commands.');
+  process.exitCode = 1;
+}
+
+function ensureFetchSupport() {
+  if (typeof fetch !== 'function') {
+    throw new Error('This CLI requires Node.js 18+ (global fetch is unavailable).');
+  }
+}
+
+function isHelpToken(value) {
+  return value === 'help' || value === '--help' || value === '-h';
+}
+
+function getApiTarget(name) {
+  return API_TARGETS[name] || null;
+}
+
+async function handleApiCommand(apiTarget, args) {
+  const subcommand = args[0];
+
+  if (!subcommand) {
+    await printNamespaceHelp(apiTarget);
+    return;
+  }
+
+  if (subcommand === 'help') {
+    const maybeOperationId = args[1];
+    if (!maybeOperationId || isHelpToken(maybeOperationId)) {
+      await printNamespaceHelp(apiTarget);
+      return;
+    }
+
+    const spec = await loadSwaggerSpec(apiTarget);
+    const operations = buildOperationMap(spec);
+    const operation = operations.get(maybeOperationId);
+    if (!operation) {
+      console.error(`Unknown ${apiTarget.namespace} operation: ${maybeOperationId}`);
+      console.error(`Run \`moralis-cli ${apiTarget.namespace} help\` to see supported operations.`);
+      process.exitCode = 1;
+      return;
+    }
+
+    printOperationHelp(spec, operation, apiTarget);
+    return;
+  }
+
+  if (subcommand === '--help' || subcommand === '-h') {
+    await printNamespaceHelp(apiTarget);
+    return;
+  }
+
+  const spec = await loadSwaggerSpec(apiTarget);
+  const operations = buildOperationMap(spec);
+  const operation = operations.get(subcommand);
+
+  if (!operation) {
+    console.error(`Unknown ${apiTarget.namespace} operation: ${subcommand}`);
+    console.error(`Run \`moralis-cli ${apiTarget.namespace} help\` to see supported operations.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const commandArgs = args.slice(1);
+  if (commandArgs.includes('--help') || commandArgs.includes('-h')) {
+    printOperationHelp(spec, operation, apiTarget);
+    return;
+  }
+
+  await invokeOperation(apiTarget, spec, operation, commandArgs);
+}
+
+async function printGlobalHelp(args = []) {
+  const requestedNamespace = args[0];
+  if (requestedNamespace) {
+    const requestedTarget = getApiTarget(requestedNamespace);
+    if (requestedTarget) {
+      await printNamespaceHelp(requestedTarget);
+      return;
+    }
+  }
+
+  console.log('moralis-cli');
+  console.log('');
+  console.log('Usage:');
+  console.log('  moralis-cli help');
+  console.log('  moralis-cli help <evm|solana>');
+  console.log('  moralis-cli login <api_key>');
+  console.log('  moralis-cli login');
+  console.log('  moralis-cli evm <operationId> [required-path-args...] [--optional value]');
+  console.log('  moralis-cli solana <operationId> [required-path-args...] [--optional value]');
+  console.log('');
+  console.log('Built-in commands:');
+  console.log('  help - Show this help message');
+  console.log('  login - Save Moralis API key (prompts if omitted)');
+  console.log('  evm - Run EVM API operations');
+  console.log('  solana - Run Solana API operations');
+  console.log('');
+
+  const targets = Object.values(API_TARGETS);
+  const results = await Promise.allSettled(targets.map(target => loadSwaggerSpec(target)));
+
+  for (let i = 0; i < targets.length; i += 1) {
+    const target = targets[i];
+    const result = results[i];
+    console.log(`${target.label} operations (${target.namespace}):`);
+    if (result.status === 'fulfilled') {
+      printOperationList(result.value, target);
+    } else {
+      console.log('  Unable to load operations right now.');
+      console.log(`  Reason: ${result.reason?.message || String(result.reason)}`);
+      console.log(`  Source: ${target.swaggerUrl}`);
+    }
+    console.log('');
+  }
+}
+
+async function printNamespaceHelp(apiTarget) {
+  console.log(`moralis-cli ${apiTarget.namespace}`);
+  console.log('');
+  console.log('Usage:');
+  console.log(`  moralis-cli ${apiTarget.namespace} help`);
+  console.log(`  moralis-cli ${apiTarget.namespace} <operationId> [required-path-args...] [--optional value]`);
+  console.log(`  moralis-cli ${apiTarget.namespace} <operationId> --help`);
+  console.log('');
+  console.log(`Swagger source: ${apiTarget.swaggerUrl}`);
+  console.log('');
+
+  try {
+    const spec = await loadSwaggerSpec(apiTarget);
+    printOperationList(spec, apiTarget);
+  } catch (error) {
+    console.log('Unable to load operations right now.');
+    console.log(`Reason: ${error.message}`);
+    console.log(`Source: ${apiTarget.swaggerUrl}`);
+  }
+}
+
+function printOperationList(spec, apiTarget) {
+  const operationMap = buildOperationMap(spec);
+  const operations = Array.from(operationMap.values()).sort((a, b) => a.operationId.localeCompare(b.operationId));
+  console.log(`Supported ${apiTarget.label} API operations (${operations.length}):`);
+  for (const operation of operations) {
+    const example = formatOperationExample(spec, operation, apiTarget);
+    const description = formatOperationListDescription(operation);
+    console.log(`  ${example}${description ? ` - ${description}` : ''}`);
+  }
+}
+
+async function login(args) {
+  let apiKey = args[0];
+  if (!apiKey) {
+    apiKey = await promptHidden('Enter Moralis API key: ');
+  }
+
+  if (!apiKey || !apiKey.trim()) {
+    throw new Error('API key is required.');
+  }
+
+  const config = await readConfig();
+  config.apiKey = apiKey.trim();
+  await writeConfig(config);
+  console.log('API key saved.');
+}
+
+function promptHidden(promptText) {
+  return new Promise((resolve, reject) => {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+
+    if (!stdin.isTTY || !stdout.isTTY) {
+      reject(new Error('Interactive login requires a TTY. Use `moralis-cli login <api_key>`.'));
+      return;
+    }
+
+    stdout.write(promptText);
+    stdin.resume();
+    stdin.setEncoding('utf8');
+
+    let value = '';
+    const wasRaw = stdin.isRaw;
+    if (typeof stdin.setRawMode === 'function') {
+      stdin.setRawMode(true);
+    }
+
+    const onData = chunk => {
+      for (const ch of chunk) {
+        if (ch === '\r' || ch === '\n') {
+          cleanup();
+          stdout.write('\n');
+          resolve(value);
+          return;
+        }
+
+        if (ch === '\u0003') {
+          cleanup();
+          reject(new Error('Cancelled.'));
+          return;
+        }
+
+        if (ch === '\u007f' || ch === '\b') {
+          if (value.length > 0) {
+            value = value.slice(0, -1);
+          }
+          continue;
+        }
+
+        value += ch;
+      }
+    };
+
+    const cleanup = () => {
+      stdin.off('data', onData);
+      if (typeof stdin.setRawMode === 'function') {
+        stdin.setRawMode(Boolean(wasRaw));
+      }
+      stdin.pause();
+    };
+
+    stdin.on('data', onData);
+  });
+}
+
+async function invokeOperation(apiTarget, spec, operation, argv) {
+  const parsedArgs = parseCliArgs(argv);
+  const params = normalizeOperationParameters(spec, operation);
+  const requiredPathParams = params.filter(p => p.in === 'path').sort(sortPathParamsByPath(operation.path));
+
+  if (parsedArgs.positionals.length < requiredPathParams.length) {
+    printOperationHelp(spec, operation, apiTarget);
+    throw new Error(`Missing required path arguments. Expected ${requiredPathParams.length}, got ${parsedArgs.positionals.length}.`);
+  }
+
+  const config = await readConfig();
+  const request = buildHttpRequest(apiTarget, spec, operation, params, parsedArgs, config);
+  const response = await fetchWithRetry(request.url, request.fetchOptions, {
+    attempts: DEFAULT_FETCH_RETRY_ATTEMPTS,
+    baseDelayMs: DEFAULT_FETCH_RETRY_BASE_DELAY_MS,
+    label: `${operation.method.toUpperCase()} ${operation.operationId}`
+  });
+  await printResponse(response);
+}
+
+function parseCliArgs(argv) {
+  const result = {
+    positionals: [],
+    flags: Object.create(null)
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--') || token === '--') {
+      result.positionals.push(token);
+      continue;
+    }
+
+    if (token.startsWith('--no-')) {
+      const key = token.slice(5);
+      result.flags[key] = false;
+      continue;
+    }
+
+    const eqIndex = token.indexOf('=');
+    if (eqIndex >= 0) {
+      const key = token.slice(2, eqIndex);
+      const value = token.slice(eqIndex + 1);
+      result.flags[key] = value;
+      continue;
+    }
+
+    const key = token.slice(2);
+    const next = argv[i + 1];
+    if (next != null && !next.startsWith('--')) {
+      result.flags[key] = next;
+      i += 1;
+    } else {
+      result.flags[key] = true;
+    }
+  }
+
+  return result;
+}
+
+function buildHttpRequest(apiTarget, spec, operation, params, parsedArgs, config) {
+  const scheme = pickScheme(spec);
+  const base = buildBaseUrl(apiTarget, spec, scheme);
+  const pathValueMap = Object.create(null);
+  const query = new URLSearchParams();
+  const headers = new Headers();
+  const consumes = pickConsumes(spec, operation);
+  const produces = pickProduces(spec, operation);
+  let body;
+  let bodyParamSeen = false;
+  let bodyContentType;
+
+  const pathParams = params.filter(p => p.in === 'path').sort(sortPathParamsByPath(operation.path));
+  pathParams.forEach((param, index) => {
+    const rawValue = parsedArgs.positionals[index];
+    if (rawValue == null || rawValue === '') {
+      throw new Error(`Missing required path parameter: ${param.name}`);
+    }
+    pathValueMap[param.name] = coerceParamValue(param, rawValue);
+  });
+
+  for (const param of params) {
+    if (param.in === 'path') {
+      continue;
+    }
+
+    const flagName = param.name;
+    const rawFlagValue = parsedArgs.flags[flagName];
+
+    if (param.in === 'body') {
+      bodyParamSeen = true;
+      bodyContentType = param.contentType || bodyContentType;
+      if (rawFlagValue == null || rawFlagValue === true) {
+        if (param.required) {
+          throw new Error(`Missing required body parameter. Pass --${param.name} '<json>'`);
+        }
+        continue;
+      }
+      body = parseBodyFlagValue(param, rawFlagValue);
+      continue;
+    }
+
+    if (rawFlagValue == null || (rawFlagValue === true && getParameterType(param) !== 'boolean')) {
+      if (param.required) {
+        throw new Error(`Missing required parameter: --${param.name}`);
+      }
+      continue;
+    }
+
+    const value = coerceParamValue(param, rawFlagValue);
+
+    if (param.in === 'query') {
+      appendQueryParam(query, param, value);
+      continue;
+    }
+
+    if (param.in === 'header') {
+      headers.set(param.name, stringifyValue(value));
+      continue;
+    }
+
+    if (param.in === 'formData') {
+      if (!(body instanceof URLSearchParams)) {
+        body = new URLSearchParams();
+      }
+      appendFormParam(body, param, value);
+      continue;
+    }
+  }
+
+  let resolvedPath = operation.path;
+  for (const [name, value] of Object.entries(pathValueMap)) {
+    resolvedPath = resolvedPath.replaceAll(`{${name}}`, encodeURIComponent(stringifyValue(value)));
+  }
+
+  const url = new URL(joinUrl(base, resolvedPath));
+  for (const [key, value] of query) {
+    url.searchParams.append(key, value);
+  }
+
+  if (produces) {
+    headers.set('accept', produces);
+  }
+
+  applyApiKeyAuth(spec, operation, config, headers, url);
+
+  let requestBody = undefined;
+  if (bodyParamSeen && body !== undefined) {
+    headers.set('content-type', bodyContentType || consumes || 'application/json');
+    requestBody = typeof body === 'string' ? body : JSON.stringify(body);
+  } else if (body instanceof URLSearchParams) {
+    headers.set('content-type', 'application/x-www-form-urlencoded');
+    requestBody = body.toString();
+  }
+
+  return {
+    url: url.toString(),
+    fetchOptions: {
+      method: operation.method.toUpperCase(),
+      headers,
+      body: allowsBody(operation.method) ? requestBody : undefined
+    }
+  };
+}
+
+function allowsBody(method) {
+  const m = method.toLowerCase();
+  return m !== 'get' && m !== 'head';
+}
+
+function appendQueryParam(query, param, value) {
+  if (Array.isArray(value)) {
+    if (param.collectionFormat === 'multi' || (param.explode === true && (param.style === 'form' || !param.style))) {
+      for (const item of value) {
+        query.append(param.name, stringifyValue(item));
+      }
+      return;
+    }
+    query.append(param.name, value.map(stringifyValue).join(','));
+    return;
+  }
+  query.append(param.name, stringifyValue(value));
+}
+
+function appendFormParam(form, param, value) {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      form.append(param.name, stringifyValue(item));
+    }
+    return;
+  }
+  form.append(param.name, stringifyValue(value));
+}
+
+function stringifyValue(value) {
+  if (typeof value === 'string') {
+    return value;
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  return JSON.stringify(value);
+}
+
+function parseBodyFlagValue(param, rawValue) {
+  if (rawValue === true) {
+    throw new Error(`Body parameter --${param.name} requires a JSON value.`);
+  }
+  try {
+    return JSON.parse(String(rawValue));
+  } catch {
+    throw new Error(`Invalid JSON for --${param.name}`);
+  }
+}
+
+function getParameterType(param) {
+  if (!param || typeof param !== 'object') {
+    return undefined;
+  }
+  return param.type || param.schema?.type;
+}
+
+function coerceParamValue(param, rawValue) {
+  const paramType = getParameterType(param);
+
+  if (rawValue === true && paramType === 'boolean') {
+    return true;
+  }
+  if (rawValue === false && paramType === 'boolean') {
+    return false;
+  }
+
+  const value = String(rawValue);
+
+  if (paramType === 'integer') {
+    const n = Number.parseInt(value, 10);
+    if (Number.isNaN(n)) {
+      throw new Error(`Invalid integer for ${param.name}: ${value}`);
+    }
+    return n;
+  }
+
+  if (paramType === 'number') {
+    const n = Number(value);
+    if (Number.isNaN(n)) {
+      throw new Error(`Invalid number for ${param.name}: ${value}`);
+    }
+    return n;
+  }
+
+  if (paramType === 'boolean') {
+    if (typeof rawValue === 'boolean') {
+      return rawValue;
+    }
+    if (value === 'true') {
+      return true;
+    }
+    if (value === 'false') {
+      return false;
+    }
+    throw new Error(`Invalid boolean for ${param.name}: ${value}`);
+  }
+
+  if (paramType === 'array') {
+    return value
+      .split(',')
+      .map(item => item.trim())
+      .filter(Boolean);
+  }
+
+  return value;
+}
+
+function applyApiKeyAuth(spec, operation, config, headers, url) {
+  if (!config.apiKey) {
+    return;
+  }
+
+  const securityDefs = {
+    ...(spec.securityDefinitions || {}),
+    ...((spec.components && spec.components.securitySchemes) || {})
+  };
+  const opSecurity = operation.raw.security || spec.security || [];
+  const activeSchemes = opSecurity.length ? opSecurity.flatMap(entry => Object.keys(entry)) : Object.keys(securityDefs);
+
+  const schemeNames = activeSchemes.length ? activeSchemes : Object.keys(securityDefs);
+
+  for (const schemeName of schemeNames) {
+    const scheme = securityDefs[schemeName];
+    if (!scheme || scheme.type !== 'apiKey') {
+      continue;
+    }
+
+    if (scheme.in === 'header') {
+      headers.set(scheme.name, config.apiKey);
+    } else if (scheme.in === 'query') {
+      url.searchParams.set(scheme.name, config.apiKey);
+    }
+  }
+
+  // Fallback for specs that omit apiKey security definitions (Moralis uses X-API-Key).
+  if (!headers.has('X-API-Key')) {
+    headers.set('X-API-Key', config.apiKey);
+  }
+}
+
+async function printResponse(response) {
+  const contentType = response.headers.get('content-type') || '';
+  const isJson = contentType.includes('application/json') || contentType.includes('+json');
+  const text = await response.text();
+
+  if (!response.ok) {
+    process.exitCode = 1;
+  }
+
+  if (isJson) {
+    try {
+      const parsed = JSON.parse(text);
+      console.log(JSON.stringify(parsed, null, 2));
+      return;
+    } catch {
+      // Fall back to raw text.
+    }
+  }
+
+  if (text) {
+    console.log(text);
+  } else {
+    console.log(`${response.status} ${response.statusText}`);
+  }
+}
+
+function pickScheme(spec) {
+  if (Array.isArray(spec.servers) && spec.servers.length > 0) {
+    try {
+      const serverUrl = new URL(String(spec.servers[0].url || ''));
+      return serverUrl.protocol.replace(':', '') || 'https';
+    } catch {
+      // Fall back to Swagger 2 fields.
+    }
+  }
+  const schemes = Array.isArray(spec.schemes) ? spec.schemes : [];
+  if (schemes.includes('https')) {
+    return 'https';
+  }
+  if (schemes[0]) {
+    return schemes[0];
+  }
+  return 'https';
+}
+
+function buildBaseUrl(apiTarget, spec, scheme) {
+  if (apiTarget && apiTarget.prodBaseUrl) {
+    return apiTarget.prodBaseUrl.replace(/\/+$/, '');
+  }
+  if (Array.isArray(spec.servers) && spec.servers.length > 0) {
+    const serverUrl = spec.servers[0] && spec.servers[0].url;
+    if (typeof serverUrl === 'string' && serverUrl.trim()) {
+      return serverUrl.replace(/\/+$/, '');
+    }
+  }
+  if (!spec.host) {
+    throw new Error('Swagger spec is missing `host`.');
+  }
+  const basePath = spec.basePath || '/';
+  const normalizedBasePath = basePath.startsWith('/') ? basePath : `/${basePath}`;
+  return `${scheme}://${spec.host}${normalizedBasePath}`.replace(/\/+$/, '');
+}
+
+function joinUrl(base, pathPart) {
+  const baseClean = base.replace(/\/+$/, '');
+  const pathClean = pathPart.startsWith('/') ? pathPart : `/${pathPart}`;
+  return `${baseClean}${pathClean}`;
+}
+
+function pickProduces(spec, operation) {
+  const responseContentTypes = pickOpenApiResponseContentTypes(operation);
+  if (responseContentTypes.length > 0) {
+    if (responseContentTypes.includes('application/json')) {
+      return 'application/json';
+    }
+    return responseContentTypes[0];
+  }
+
+  const produces = operation.raw.produces || spec.produces || [];
+  if (!Array.isArray(produces) || produces.length === 0) {
+    return 'application/json';
+  }
+  if (produces.includes('application/json')) {
+    return 'application/json';
+  }
+  return produces[0];
+}
+
+function pickConsumes(spec, operation) {
+  const requestContentTypes = pickOpenApiRequestContentTypes(operation);
+  if (requestContentTypes.length > 0) {
+    if (requestContentTypes.includes('application/json')) {
+      return 'application/json';
+    }
+    return requestContentTypes[0];
+  }
+
+  const consumes = operation.raw.consumes || spec.consumes || [];
+  if (!Array.isArray(consumes) || consumes.length === 0) {
+    return 'application/json';
+  }
+  if (consumes.includes('application/json')) {
+    return 'application/json';
+  }
+  return consumes[0];
+}
+
+function buildOperationMap(spec) {
+  const map = new Map();
+  const paths = spec.paths || {};
+
+  for (const [apiPath, pathItem] of Object.entries(paths)) {
+    for (const method of ['get', 'post', 'put', 'patch', 'delete', 'head', 'options']) {
+      const op = pathItem[method];
+      if (!op || !op.operationId) {
+        continue;
+      }
+      map.set(op.operationId, {
+        operationId: op.operationId,
+        method,
+        path: apiPath,
+        raw: op,
+        pathItem
+      });
+    }
+  }
+
+  return map;
+}
+
+function normalizeOperationParameters(spec, operation) {
+  const pathParams = Array.isArray(operation.pathItem.parameters) ? operation.pathItem.parameters : [];
+  const opParams = Array.isArray(operation.raw.parameters) ? operation.raw.parameters : [];
+
+  const merged = [];
+  const seen = new Set();
+
+  for (const param of [...pathParams, ...opParams]) {
+    const resolved = resolveParameter(spec, param);
+    const key = `${resolved.in}:${resolved.name}`;
+    if (seen.has(key)) {
+      for (let i = 0; i < merged.length; i += 1) {
+        const existing = merged[i];
+        if (`${existing.in}:${existing.name}` === key) {
+          merged[i] = resolved;
+          break;
+        }
+      }
+      continue;
+    }
+    seen.add(key);
+    merged.push(resolved);
+  }
+
+  const requestBodyParam = normalizeOpenApiRequestBodyParameter(spec, operation);
+  if (requestBodyParam) {
+    merged.push(requestBodyParam);
+  }
+
+  return merged;
+}
+
+function resolveParameter(spec, param) {
+  if (param && param.$ref) {
+    return resolveRef(spec, param.$ref);
+  }
+  return param;
+}
+
+function resolveRequestBody(spec, requestBody) {
+  if (requestBody && requestBody.$ref) {
+    return resolveRef(spec, requestBody.$ref);
+  }
+  return requestBody;
+}
+
+function normalizeOpenApiRequestBodyParameter(spec, operation) {
+  const requestBody = resolveRequestBody(spec, operation?.raw?.requestBody);
+  if (!requestBody) {
+    return null;
+  }
+
+  const content = requestBody.content && typeof requestBody.content === 'object' ? requestBody.content : {};
+  const contentTypes = Object.keys(content);
+  const preferredContentType = contentTypes.includes('application/json') ? 'application/json' : contentTypes[0] || 'application/json';
+  const mediaType = content[preferredContentType] || {};
+  const schema = mediaType.schema ? resolveSchema(spec, mediaType.schema) : undefined;
+
+  return {
+    name: 'body',
+    in: 'body',
+    required: Boolean(requestBody.required),
+    type: 'object',
+    schema,
+    contentType: preferredContentType,
+    description: requestBody.description || ''
+  };
+}
+
+function resolveSchema(spec, schema) {
+  if (schema && schema.$ref) {
+    return resolveRef(spec, schema.$ref);
+  }
+  return schema;
+}
+
+function resolveRef(root, ref) {
+  if (typeof ref !== 'string' || !ref.startsWith('#/')) {
+    throw new Error(`Unsupported $ref: ${ref}`);
+  }
+  const parts = ref.slice(2).split('/').map(unescapeJsonPointer);
+  let value = root;
+  for (const part of parts) {
+    if (value == null || !(part in value)) {
+      throw new Error(`Unable to resolve $ref: ${ref}`);
+    }
+    value = value[part];
+  }
+  if (value && value.$ref) {
+    return resolveRef(root, value.$ref);
+  }
+  return value;
+}
+
+function unescapeJsonPointer(part) {
+  return part.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+
+function sortPathParamsByPath(apiPath) {
+  const order = Array.from(apiPath.matchAll(/\{([^}]+)\}/g)).map(m => m[1]);
+  const indexMap = new Map(order.map((name, idx) => [name, idx]));
+  return (a, b) => {
+    const ai = indexMap.has(a.name) ? indexMap.get(a.name) : Number.MAX_SAFE_INTEGER;
+    const bi = indexMap.has(b.name) ? indexMap.get(b.name) : Number.MAX_SAFE_INTEGER;
+    return ai - bi;
+  };
+}
+
+function printOperationHelp(spec, operation, apiTarget) {
+  const params = normalizeOperationParameters(spec, operation);
+  const pathParams = params.filter(p => p.in === 'path').sort(sortPathParamsByPath(operation.path));
+  const otherParams = params.filter(p => p.in !== 'path');
+  const usageParts = buildOperationUsageParts(spec, operation, apiTarget);
+
+  console.log(`Usage: ${usageParts.join(' ')}`);
+  console.log('');
+  console.log(`${operation.method.toUpperCase()} ${operation.path}`);
+  if (otherParams.length > 0) {
+    console.log('');
+    console.log('Parameters:');
+    for (const param of otherParams) {
+      const type = getParameterType(param) || (param.in === 'body' ? 'json' : 'string');
+      const required = param.required ? 'required' : 'optional';
+      console.log(`  --${param.name} (${param.in}, ${type}, ${required})`);
+    }
+  }
+}
+
+function buildOperationUsageParts(spec, operation, apiTarget) {
+  const params = normalizeOperationParameters(spec, operation);
+  const pathParams = params.filter(p => p.in === 'path').sort(sortPathParamsByPath(operation.path));
+  const otherParams = params.filter(p => p.in !== 'path');
+  const namespace = apiTarget?.namespace || 'evm';
+  const usageParts = [`moralis-cli ${namespace} ${operation.operationId}`];
+
+  for (const param of pathParams) {
+    usageParts.push(`<${param.name}>`);
+  }
+  if (otherParams.length > 0) {
+    usageParts.push('[--param value]');
+  }
+
+  return usageParts;
+}
+
+function formatOperationExample(spec, operation, apiTarget) {
+  const params = normalizeOperationParameters(spec, operation);
+  const pathParams = params.filter(p => p.in === 'path').sort(sortPathParamsByPath(operation.path));
+  const namespace = apiTarget?.namespace || 'evm';
+  const parts = [`moralis-cli ${namespace} ${operation.operationId}`];
+  for (const param of pathParams) {
+    parts.push(`<${param.name}>`);
+  }
+  return parts.join(' ');
+}
+
+function pickOpenApiRequestContentTypes(operation) {
+  const content = operation?.raw?.requestBody?.content;
+  if (!content || typeof content !== 'object') {
+    return [];
+  }
+  return Object.keys(content);
+}
+
+function pickOpenApiResponseContentTypes(operation) {
+  const responses = operation?.raw?.responses;
+  if (!responses || typeof responses !== 'object') {
+    return [];
+  }
+
+  const preferredStatusCodes = Object.keys(responses).sort((a, b) => {
+    const aScore = scoreResponseStatusCode(a);
+    const bScore = scoreResponseStatusCode(b);
+    return aScore - bScore;
+  });
+
+  for (const statusCode of preferredStatusCodes) {
+    const response = responses[statusCode];
+    const content = response && response.content;
+    if (content && typeof content === 'object') {
+      const types = Object.keys(content);
+      if (types.length > 0) {
+        return types;
+      }
+    }
+  }
+
+  return [];
+}
+
+function scoreResponseStatusCode(statusCode) {
+  if (/^2\d\d$/.test(statusCode)) {
+    return Number(statusCode);
+  }
+  if (statusCode === 'default') {
+    return 900;
+  }
+  return 1000;
+}
+
+function formatOperationListDescription(operation) {
+  const summary = cleanDescriptionText(operation?.raw?.summary);
+  if (summary) {
+    return truncateText(summary, 90);
+  }
+
+  const description = cleanDescriptionText(operation?.raw?.description);
+  if (description) {
+    return truncateText(description, 90);
+  }
+
+  return '';
+}
+
+function cleanDescriptionText(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.replace(/\s+/g, ' ').trim();
+}
+
+function truncateText(value, maxLength) {
+  if (typeof value !== 'string' || value.length <= maxLength) {
+    return value || '';
+  }
+  return `${value.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
+}
+
+async function loadSwaggerSpec(apiTarget) {
+  if (!apiTarget) {
+    throw new Error('API target is required.');
+  }
+
+  const cached = await readSwaggerCache(apiTarget);
+  if (cached && Date.now() - cached.fetchedAt < SWAGGER_CACHE_MAX_AGE_MS) {
+    return cached.spec;
+  }
+
+  try {
+    const response = await fetchWithRetry(
+      apiTarget.swaggerUrl,
+      { headers: { accept: 'application/json' } },
+      {
+        attempts: DEFAULT_FETCH_RETRY_ATTEMPTS,
+        baseDelayMs: DEFAULT_FETCH_RETRY_BASE_DELAY_MS,
+        label: `${apiTarget.namespace} swagger spec`
+      }
+    );
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status} ${response.statusText}`);
+    }
+    const spec = await response.json();
+    await writeSwaggerCache(apiTarget, spec);
+    return spec;
+  } catch (error) {
+    if (cached) {
+      return cached.spec;
+    }
+    throw new Error(`Failed to load swagger spec from ${apiTarget.swaggerUrl}: ${error.message}`);
+  }
+}
+
+async function fetchWithRetry(url, options, retryOptions = {}) {
+  const attempts = Math.max(1, Number(retryOptions.attempts || DEFAULT_FETCH_RETRY_ATTEMPTS));
+  const baseDelayMs = Math.max(0, Number(retryOptions.baseDelayMs || DEFAULT_FETCH_RETRY_BASE_DELAY_MS));
+  const label = retryOptions.label || 'request';
+  let lastError;
+
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      const response = await fetch(url, options);
+      if (!shouldRetryResponse(response, attempt, attempts)) {
+        return response;
+      }
+
+      lastError = new Error(`${label} failed with HTTP ${response.status} ${response.statusText}`);
+      await sleepWithBackoff(attempt, baseDelayMs, response);
+      continue;
+    } catch (error) {
+      lastError = error;
+      if (attempt >= attempts || !shouldRetryError(error)) {
+        throw error;
+      }
+      await sleepWithBackoff(attempt, baseDelayMs);
+    }
+  }
+
+  throw lastError || new Error(`${label} failed`);
+}
+
+function shouldRetryResponse(response, attempt, maxAttempts) {
+  if (attempt >= maxAttempts) {
+    return false;
+  }
+
+  const status = response.status;
+  return status === 408 || status === 425 || status === 429 || (status >= 500 && status <= 599);
+}
+
+function shouldRetryError(error) {
+  if (!error) {
+    return false;
+  }
+
+  // Node fetch throws TypeError for transient network issues (DNS, ECONNRESET, timeouts).
+  return error instanceof TypeError || error.name === 'AbortError';
+}
+
+async function sleepWithBackoff(attempt, baseDelayMs, response) {
+  const retryAfterMs = getRetryAfterMs(response);
+  const exponentialDelay = baseDelayMs * Math.pow(2, Math.max(0, attempt - 1));
+  const jitter = Math.floor(Math.random() * Math.max(1, Math.floor(baseDelayMs / 2)));
+  const delayMs = retryAfterMs != null ? Math.max(retryAfterMs, exponentialDelay) : exponentialDelay + jitter;
+  if (delayMs > 0) {
+    await sleep(delayMs);
+  }
+}
+
+function getRetryAfterMs(response) {
+  if (!response || typeof response.headers?.get !== 'function') {
+    return null;
+  }
+
+  const retryAfter = response.headers.get('retry-after');
+  if (!retryAfter) {
+    return null;
+  }
+
+  const seconds = Number(retryAfter);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return seconds * 1000;
+  }
+
+  const dateMs = Date.parse(retryAfter);
+  if (Number.isNaN(dateMs)) {
+    return null;
+  }
+
+  return Math.max(0, dateMs - Date.now());
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function getSwaggerCachePath(apiTarget) {
+  return path.join(CONFIG_DIR, apiTarget.cacheFileName);
+}
+
+async function readSwaggerCache(apiTarget) {
+  const cachePaths = [getSwaggerCachePath(apiTarget)];
+  if (apiTarget.namespace === 'evm') {
+    cachePaths.push(path.join(CONFIG_DIR, 'swagger-cache.json'));
+  }
+
+  try {
+    for (const cachePath of cachePaths) {
+      try {
+        const raw = await fsp.readFile(cachePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && parsed.spec) {
+          return parsed;
+        }
+      } catch {
+        // Try next cache path.
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+async function writeSwaggerCache(apiTarget, spec) {
+  await ensureConfigDir();
+  const payload = { fetchedAt: Date.now(), spec };
+  await fsp.writeFile(getSwaggerCachePath(apiTarget), JSON.stringify(payload), 'utf8');
+}
+
+async function readConfig() {
+  try {
+    const raw = await fsp.readFile(CONFIG_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+async function writeConfig(config) {
+  await ensureConfigDir();
+  await fsp.writeFile(CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, {
+    encoding: 'utf8',
+    mode: 0o600
+  });
+  try {
+    await fsp.chmod(CONFIG_PATH, 0o600);
+  } catch {
+    // Ignore on filesystems that do not support POSIX perms.
+  }
+}
+
+async function ensureConfigDir() {
+  await fsp.mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
+}
+
+module.exports = {
+  main
+};