@countrystatecity/cli 0.1.1

package/dist/index.js

@@ -0,0 +1,1578 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/auth.ts
+import chalk3 from "chalk";
+import readline from "readline";
+import { Writable } from "stream";
+
+// src/lib/config.ts
+import Conf from "conf";
+var config = new Conf({
+  projectName: "csc",
+  schema: {
+    apiKey: { type: "string", default: "" },
+    apiBase: { type: "string", default: "https://api.countrystatecity.in/v1" }
+  }
+});
+function getApiKey() {
+  const key = config.get("apiKey");
+  return key || void 0;
+}
+function setApiKey(key) {
+  config.set("apiKey", key);
+}
+function clearApiKey() {
+  config.delete("apiKey");
+}
+function getApiBase() {
+  return config.get("apiBase");
+}
+
+// src/lib/api.ts
+import axios, { AxiosError } from "axios";
+import chalk from "chalk";
+function extractUsage(headers) {
+  const dailyUsed = headers["x-csc-daily-used"];
+  const dailyLimit = headers["x-csc-daily-limit"];
+  const monthlyUsed = headers["x-csc-monthly-used"];
+  const monthlyLimit = headers["x-csc-monthly-limit"];
+  if (!dailyUsed || !dailyLimit || !monthlyUsed || !monthlyLimit) {
+    return null;
+  }
+  return {
+    dailyUsed: parseInt(dailyUsed, 10),
+    dailyLimit: parseInt(dailyLimit, 10),
+    monthlyUsed: parseInt(monthlyUsed, 10),
+    monthlyLimit: parseInt(monthlyLimit, 10)
+  };
+}
+async function get(path) {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    console.error(chalk.red("Not authenticated."));
+    console.error(chalk.dim("Run `csc auth login` to set your API key."));
+    process.exit(1);
+  }
+  const baseUrl = getApiBase();
+  try {
+    const response = await axios.get(`${baseUrl}${path}`, {
+      headers: {
+        "X-CSCAPI-KEY": apiKey,
+        "User-Agent": "@countrystatecity/cli/0.1.1"
+      }
+    });
+    const usage = extractUsage(response.headers);
+    return { data: response.data, usage };
+  } catch (error) {
+    if (error instanceof AxiosError) {
+      const status = error.response?.status;
+      if (status === 401) {
+        console.error(chalk.red("Invalid or missing API key."));
+        console.error(chalk.dim("Run `csc auth login` to set your key."));
+        process.exit(1);
+      }
+      if (status === 429) {
+        console.error(chalk.red("Daily limit reached."));
+        console.error(chalk.yellow("Run `csc upgrade` to increase your limits."));
+        process.exit(1);
+      }
+      if (status === 404) {
+        console.error(chalk.red("Not found."));
+        process.exit(1);
+      }
+      console.error(chalk.red(`API error: ${error.message}`));
+      process.exit(1);
+    }
+    console.error(chalk.red("Cannot reach API. Check your internet connection."));
+    process.exit(1);
+  }
+}
+async function validateKey(apiKey) {
+  const baseUrl = getApiBase();
+  try {
+    const response = await axios.get(`${baseUrl}/countries/IN`, {
+      headers: {
+        "X-CSCAPI-KEY": apiKey,
+        "User-Agent": "@countrystatecity/cli/0.1.1"
+      }
+    });
+    const usage = extractUsage(response.headers);
+    return { valid: true, usage };
+  } catch {
+    return { valid: false, usage: null };
+  }
+}
+
+// src/lib/usage-footer.ts
+import chalk2 from "chalk";
+function getTierName(dailyLimit) {
+  if (dailyLimit <= 100) return "Community";
+  if (dailyLimit <= 300) return "Starter";
+  if (dailyLimit <= 1e3) return "Supporter";
+  if (dailyLimit <= 3300) return "Professional";
+  if (dailyLimit <= 25e3) return "Business";
+  if (dailyLimit <= 5e4) return "Legacy";
+  return "Custom";
+}
+function formatNumber(n) {
+  return n.toLocaleString("en-US");
+}
+function timeUntilDailyReset() {
+  const now = Date.now();
+  const resetAt = /* @__PURE__ */ new Date();
+  resetAt.setUTCHours(24, 0, 0, 0);
+  const ms = resetAt.getTime() - now;
+  const hours = Math.floor(ms / (1e3 * 60 * 60));
+  const minutes = Math.floor(ms % (1e3 * 60 * 60) / (1e3 * 60));
+  return `${hours}h ${minutes}m`;
+}
+function printUsageFooter(usage, flags) {
+  if (flags?.noFooter || flags?.json) return;
+  if (!usage) return;
+  const { dailyUsed, dailyLimit, monthlyUsed, monthlyLimit } = usage;
+  if (dailyLimit === 0 || monthlyLimit === 0) return;
+  const dailyPercent = dailyUsed / dailyLimit * 100;
+  const tier = getTierName(dailyLimit);
+  process.stderr.write("\n");
+  if (dailyPercent >= 100) {
+    process.stderr.write(
+      chalk2.red(
+        `Daily limit reached (${formatNumber(dailyUsed)}/${formatNumber(dailyLimit)}). Resets in ${timeUntilDailyReset()}.`
+      ) + "\n"
+    );
+    const nextTier = dailyLimit <= 300 ? "Supporter ($9/mo)" : "a higher plan";
+    process.stderr.write(chalk2.red(`Upgrade to ${nextTier} for more requests/day.`) + "\n");
+    process.stderr.write(
+      chalk2.red("Run `csc upgrade` or visit https://app.countrystatecity.in/pricing") + "\n"
+    );
+  } else if (dailyPercent >= 80) {
+    process.stderr.write(
+      chalk2.yellow(
+        `Warning: ${formatNumber(dailyUsed)}/${formatNumber(dailyLimit)} daily requests used (${Math.round(dailyPercent)}%). Upgrade for more at $9/mo.`
+      ) + "\n"
+    );
+    process.stderr.write(chalk2.yellow("Run `csc upgrade` to view plans.") + "\n");
+  } else {
+    process.stderr.write(
+      chalk2.dim(
+        `Usage: ${formatNumber(dailyUsed)}/${formatNumber(dailyLimit)} today | ${formatNumber(monthlyUsed)}/${formatNumber(monthlyLimit)} this month (${tier})`
+      ) + "\n"
+    );
+  }
+}
+function progressBar(used, limit) {
+  if (limit === 0) return "[--------------------]";
+  const ratio = Math.min(used / limit, 1);
+  const filled = Math.round(ratio * 20);
+  const empty = 20 - filled;
+  const percent = Math.round(ratio * 100);
+  let colorFn;
+  if (percent >= 80) colorFn = chalk2.red;
+  else if (percent >= 60) colorFn = chalk2.yellow;
+  else colorFn = chalk2.green;
+  return colorFn(`[${"=".repeat(filled)}${"-".repeat(empty)}]`);
+}
+
+// src/lib/output.ts
+import search from "@inquirer/search";
+function stderr(message) {
+  process.stderr.write(message + "\n");
+}
+async function createSpinner(text, flags) {
+  if (flags.quiet || flags.json) {
+    return buildNoopSpinner(text);
+  }
+  const ora = (await import("ora")).default;
+  const spinner = ora({ text, stream: process.stderr });
+  spinner.start();
+  return spinner;
+}
+function isTTY() {
+  return !!process.stdin.isTTY;
+}
+async function promptCountry(countries) {
+  return search({
+    message: "Select a country",
+    source: (input) => {
+      const query = (input ?? "").toLowerCase();
+      return Promise.resolve(
+        countries.filter(
+          (c) => c.name.toLowerCase().includes(query) || c.iso2.toLowerCase().includes(query)
+        ).map((c) => ({
+          name: c.emoji ? `${c.emoji}  ${c.name}` : c.name,
+          value: c.iso2
+        }))
+      );
+    }
+  });
+}
+async function promptState(states) {
+  return search({
+    message: "Select a state",
+    source: (input) => {
+      const query = (input ?? "").toLowerCase();
+      return Promise.resolve(
+        states.filter(
+          (s) => s.name.toLowerCase().includes(query) || s.iso2.toLowerCase().includes(query)
+        ).map((s) => ({ name: s.name, value: s.iso2 }))
+      );
+    }
+  });
+}
+function buildNoopSpinner(initialText) {
+  const noop = {
+    text: initialText,
+    start(_text) {
+      return this;
+    },
+    stop() {
+    },
+    succeed(_text) {
+    },
+    fail(_text) {
+    }
+  };
+  return noop;
+}
+
+// src/commands/auth.ts
+async function promptForKey() {
+  return new Promise((resolve) => {
+    let muted = false;
+    let settled = false;
+    const mutableStdout = new Writable({
+      write(chunk, encoding, callback) {
+        if (!muted) {
+          process.stdout.write(chunk, encoding);
+        }
+        callback();
+      }
+    });
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: mutableStdout,
+      terminal: true
+    });
+    const finish = (answer) => {
+      if (settled) return;
+      settled = true;
+      rl.close();
+      console.log();
+      resolve(answer.trim());
+    };
+    rl.question(
+      `Enter your API key (get one at ${chalk3.cyan("https://app.countrystatecity.in")}): `,
+      (answer) => finish(answer)
+    );
+    rl.on("close", () => {
+      if (!settled) {
+        settled = true;
+        console.log();
+        resolve("");
+      }
+    });
+    muted = true;
+  });
+}
+function registerAuthCommands(program2) {
+  const auth = program2.command("auth").description("Manage API authentication");
+  auth.command("login").description("Authenticate with your API key").option("--key <apiKey>", "Provide API key directly").action(async (options, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const flags = {
+      json: globalOpts.json ?? false,
+      quiet: globalOpts.quiet ?? false,
+      noFooter: globalOpts.footer === false
+    };
+    if (!options.key && !isTTY()) {
+      process.stderr.write(chalk3.red("API key required in non-interactive mode.") + "\n");
+      process.stderr.write(
+        chalk3.dim("Use `csc auth login --key <API_KEY>` to provide it directly.") + "\n"
+      );
+      process.exit(1);
+    }
+    const key = options.key || await promptForKey();
+    if (!key) {
+      process.stderr.write(chalk3.red("No API key provided.") + "\n");
+      process.exit(1);
+    }
+    const spinner = await createSpinner("Validating API key...", flags);
+    const result = await validateKey(key);
+    if (!result.valid) {
+      spinner.fail("Invalid API key.");
+      process.stderr.write(chalk3.dim("Check your key at https://app.countrystatecity.in") + "\n");
+      process.exit(1);
+    }
+    setApiKey(key);
+    spinner.succeed("API key saved successfully.");
+    if (result.usage) {
+      const tier = getTierName(result.usage.dailyLimit);
+      process.stderr.write(
+        chalk3.dim(
+          `Tier: ${tier} | ${formatNumber(result.usage.dailyLimit)}/day | ${formatNumber(result.usage.monthlyLimit)}/month`
+        ) + "\n"
+      );
+    }
+  });
+  auth.command("status").description("Check authentication status").action(async (_options, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const flags = {
+      json: globalOpts.json ?? false,
+      quiet: globalOpts.quiet ?? false,
+      noFooter: globalOpts.footer === false
+    };
+    const key = getApiKey();
+    if (!key) {
+      if (flags.json) {
+        process.stdout.write(JSON.stringify({ authenticated: false }) + "\n");
+      } else {
+        process.stderr.write(chalk3.yellow("Not logged in.") + "\n");
+        process.stderr.write(chalk3.dim("Run `csc auth login` to set your API key.") + "\n");
+      }
+      return;
+    }
+    const spinner = await createSpinner("Checking status...", flags);
+    const result = await validateKey(key);
+    if (!result.valid) {
+      spinner.fail("Stored API key is invalid.");
+      process.stderr.write(chalk3.dim("Run `csc auth login` to set a new key.") + "\n");
+      return;
+    }
+    spinner.stop();
+    if (flags.json) {
+      const masked2 = "****..." + key.slice(-4);
+      const output = { authenticated: true, key: masked2 };
+      if (result.usage) {
+        const tier = getTierName(result.usage.dailyLimit);
+        output.tier = tier;
+        output.daily = { used: result.usage.dailyUsed, limit: result.usage.dailyLimit };
+        output.monthly = { used: result.usage.monthlyUsed, limit: result.usage.monthlyLimit };
+      }
+      process.stdout.write(JSON.stringify(output) + "\n");
+      return;
+    }
+    const masked = "****..." + key.slice(-4);
+    console.log(chalk3.green("Authenticated"));
+    console.log(`${chalk3.bold("Key:".padEnd(10))}${masked}`);
+    if (result.usage) {
+      const tier = getTierName(result.usage.dailyLimit);
+      console.log(`${chalk3.bold("Tier:".padEnd(10))}${tier}`);
+      console.log(
+        `${chalk3.bold("Daily:".padEnd(10))}${formatNumber(result.usage.dailyUsed)} / ${formatNumber(result.usage.dailyLimit)}`
+      );
+      console.log(
+        `${chalk3.bold("Monthly:".padEnd(10))}${formatNumber(result.usage.monthlyUsed)} / ${formatNumber(result.usage.monthlyLimit)}`
+      );
+    }
+  });
+  auth.command("logout").description("Remove stored API key").action((_options, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const flags = {
+      json: globalOpts.json ?? false,
+      quiet: globalOpts.quiet ?? false,
+      noFooter: globalOpts.footer === false
+    };
+    clearApiKey();
+    if (flags.json) {
+      process.stdout.write(JSON.stringify({ success: true }) + "\n");
+    } else {
+      console.log(chalk3.green("API key removed."));
+    }
+  });
+}
+
+// src/commands/search.ts
+import chalk5 from "chalk";
+
+// src/lib/display.ts
+import Table from "cli-table3";
+import chalk4 from "chalk";
+function printTable(headers, rows) {
+  const table = new Table({
+    head: headers.map((h) => chalk4.cyan(h)),
+    style: { head: [], border: [] }
+  });
+  for (const row of rows) {
+    table.push(row);
+  }
+  console.log(table.toString());
+}
+function printJson(data) {
+  const json = JSON.stringify(data, null, 2);
+  const highlighted = json.replace(
+    /"([^"]+)"\s*:|:\s*"((?:[^"\\]|\\.)*)"|:\s*(-?\d+(?:\.\d+)?)/g,
+    (match, key, strVal, numVal) => {
+      if (key !== void 0) return `${chalk4.cyan(`"${key}"`)}:`;
+      if (strVal !== void 0) return `: ${chalk4.green(`"${strVal}"`)}`;
+      if (numVal !== void 0) return `: ${chalk4.yellow(numVal)}`;
+      return match;
+    }
+  );
+  console.log(highlighted);
+}
+function printDetail(label, value) {
+  console.log(`${chalk4.bold(label.padEnd(14))}${value}`);
+}
+
+// src/commands/search.ts
+function registerSearchCommands(program2) {
+  const search3 = program2.command("search").description("Search countries, states, and cities");
+  search3.command("countries").description("List all countries").option("--filter <text>", "Filter by name").action(async (options, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const flags = {
+      json: globalOpts.json ?? false,
+      quiet: globalOpts.quiet ?? false,
+      noFooter: globalOpts.footer === false
+    };
+    const spinner = await createSpinner("Fetching countries...", flags);
+    const { data, usage } = await get("/countries");
+    spinner.stop();
+    let countries = data;
+    if (options.filter) {
+      const term = options.filter.toLowerCase();
+      countries = countries.filter((c) => c.name.toLowerCase().includes(term));
+    }
+    if (flags.json) {
+      printJson(countries);
+    } else {
+      const rows = countries.map((c) => [
+        c.iso2,
+        c.iso3,
+        c.name,
+        c.capital || "",
+        c.phonecode ? `+${c.phonecode.replace(/^\+/, "")}` : "",
+        c.currency || ""
+      ]);
+      printTable(["ISO2", "ISO3", "Name", "Capital", "Phone", "Currency"], rows);
+    }
+    printUsageFooter(usage, flags);
+  });
+  search3.command("states").description("List states for a country").option("-c, --country <iso2>", "Country ISO2 code").option("--filter <text>", "Filter by name").action(async (options, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const flags = {
+      json: globalOpts.json ?? false,
+      quiet: globalOpts.quiet ?? false,
+      noFooter: globalOpts.footer === false
+    };
+    let code = options.country?.toUpperCase();
+    if (!code) {
+      if (isTTY()) {
+        const countrySpinner = await createSpinner("Loading countries...", flags);
+        const { data: allCountries } = await get("/countries");
+        countrySpinner.stop();
+        code = await promptCountry(allCountries);
+      } else {
+        process.stderr.write(chalk5.red("Country code required. Use --country IN\n"));
+        process.exit(1);
+        return;
+      }
+    }
+    const spinner = await createSpinner(`Fetching states for ${code}...`, flags);
+    const { data, usage } = await get(`/countries/${code}/states`);
+    spinner.stop();
+    let states = data;
+    if (options.filter) {
+      const term = options.filter.toLowerCase();
+      states = states.filter((s) => s.name.toLowerCase().includes(term));
+    }
+    if (flags.json) {
+      printJson(states);
+    } else {
+      const rows = states.map((s) => [
+        String(s.id),
+        s.name,
+        s.iso2 || "",
+        s.type || ""
+      ]);
+      printTable(["ID", "Name", "ISO2", "Type"], rows);
+    }
+    printUsageFooter(usage, flags);
+  });
+  search3.command("cities").description("List cities for a state").option("-c, --country <iso2>", "Country ISO2 code").option("-s, --state <iso2>", "State ISO2 code").option("--filter <text>", "Filter by name").action(
+    async (options, cmd) => {
+      const globalOpts = cmd.optsWithGlobals();
+      const flags = {
+        json: globalOpts.json ?? false,
+        quiet: globalOpts.quiet ?? false,
+        noFooter: globalOpts.footer === false
+      };
+      let countryCode = options.country?.toUpperCase();
+      if (!countryCode) {
+        if (isTTY()) {
+          const countrySpinner = await createSpinner("Loading countries...", flags);
+          const { data: allCountries } = await get("/countries");
+          countrySpinner.stop();
+          countryCode = await promptCountry(allCountries);
+        } else {
+          process.stderr.write(chalk5.red("Country code required. Use --country IN\n"));
+          process.exit(1);
+          return;
+        }
+      }
+      let stateCode = options.state?.toUpperCase();
+      if (!stateCode) {
+        if (isTTY()) {
+          const stateSpinner = await createSpinner(`Loading states for ${countryCode}...`, flags);
+          const { data: allStates } = await get(`/countries/${countryCode}/states`);
+          stateSpinner.stop();
+          stateCode = await promptState(allStates);
+        } else {
+          process.stderr.write(chalk5.red("State code required. Use --state MH\n"));
+          process.exit(1);
+          return;
+        }
+      }
+      const spinner = await createSpinner(
+        `Fetching cities for ${countryCode}/${stateCode}...`,
+        flags
+      );
+      const { data, usage } = await get(
+        `/countries/${countryCode}/states/${stateCode}/cities`
+      );
+      spinner.stop();
+      let cities = data;
+      if (options.filter) {
+        const term = options.filter.toLowerCase();
+        cities = cities.filter((c) => c.name.toLowerCase().includes(term));
+      }
+      if (flags.json) {
+        printJson(cities);
+      } else {
+        const rows = cities.map((c) => [String(c.id), c.name]);
+        printTable(["ID", "Name"], rows);
+      }
+      printUsageFooter(usage, flags);
+    }
+  );
+  search3.argument("[query]", "Search term to match country names").action(async (query, options, cmd) => {
+    if (!query) return;
+    const globalOpts = cmd.optsWithGlobals();
+    const flags = {
+      json: globalOpts.json ?? false,
+      quiet: globalOpts.quiet ?? false,
+      noFooter: globalOpts.footer === false
+    };
+    const spinner = await createSpinner("Searching...", flags);
+    const { data, usage } = await get("/countries");
+    spinner.stop();
+    const term = query.toLowerCase();
+    const matches = data.filter((c) => c.name.toLowerCase().includes(term));
+    if (flags.json) {
+      printJson(matches);
+    } else if (matches.length === 0) {
+      console.log(chalk5.yellow(`No countries matching "${query}".`));
+    } else {
+      const rows = matches.map((c) => [
+        c.iso2,
+        c.iso3,
+        c.name,
+        c.capital || "",
+        c.phonecode ? `+${c.phonecode.replace(/^\+/, "")}` : "",
+        c.currency || ""
+      ]);
+      printTable(["ISO2", "ISO3", "Name", "Capital", "Phone", "Currency"], rows);
+    }
+    if (!flags.json) {
+      process.stderr.write(
+        chalk5.dim("\nTip: Use `csc search states --country IN` to search within a country") + "\n"
+      );
+    }
+    printUsageFooter(usage, flags);
+  });
+}
+
+// src/commands/get.ts
+import chalk6 from "chalk";
+function tryParseJson(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+function formatTimezones(raw) {
+  const parsed = tryParseJson(raw);
+  if (!Array.isArray(parsed)) return raw;
+  return parsed.map((tz) => {
+    const offset = tz.utcOffset || tz.gmtOffsetName || "";
+    const offsetStr = offset.startsWith("UTC") ? offset : `UTC${offset}`;
+    return `${tz.zoneName || ""} (${tz.abbreviation || ""}, ${offsetStr})`;
+  }).join(", ");
+}
+function formatCoord(value) {
+  const num = parseFloat(value);
+  return isNaN(num) ? value : num.toFixed(4);
+}
+function registerGetCommands(program2) {
+  const getCmd = program2.command("get").description("Get detailed information");
+  getCmd.command("country [iso2]").description("Get detailed country information").action(async (iso2, options, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const flags = {
+      json: globalOpts.json ?? false,
+      quiet: globalOpts.quiet ?? false,
+      noFooter: globalOpts.footer === false
+    };
+    let code;
+    if (iso2) {
+      code = iso2.toUpperCase();
+    } else if (isTTY()) {
+      const countrySpinner = await createSpinner("Loading countries...", flags);
+      const { data: allCountries } = await get("/countries");
+      countrySpinner.stop();
+      code = await promptCountry(allCountries);
+    } else {
+      process.stderr.write(chalk6.red("Country ISO2 code required. Example: csc get country IN\n"));
+      process.exit(1);
+      return;
+    }
+    const spinner = await createSpinner(`Fetching ${code}...`, flags);
+    const { data, usage } = await get(`/countries/${code}`);
+    spinner.stop();
+    if (flags.json) {
+      printJson(data);
+    } else {
+      printDetail("Country:", data.name);
+      printDetail("ISO2:", data.iso2);
+      printDetail("ISO3:", data.iso3);
+      printDetail("Capital:", data.capital || "N/A");
+      printDetail("Phone Code:", `+${(data.phonecode || "").replace(/^\+/, "")}`);
+      const currencyParts = [data.currency, data.currency_name, data.currency_symbol].filter(Boolean);
+      printDetail("Currency:", currencyParts.length > 1 ? `${data.currency} (${data.currency_name}) ${data.currency_symbol}` : data.currency || "N/A");
+      printDetail("Region:", `${data.region}${data.subregion ? ` > ${data.subregion}` : ""}`);
+      printDetail("Coordinates:", `${formatCoord(data.latitude)}, ${formatCoord(data.longitude)}`);
+      if (data.tld) printDetail("TLD:", data.tld);
+      printDetail("Native Name:", data.native || "N/A");
+      printDetail("Flag:", data.emoji || "");
+      printDetail("Timezones:", formatTimezones(data.timezones));
+    }
+    printUsageFooter(usage, flags);
+  });
+  getCmd.command("state [country_iso2] [state_iso2]").description("Get detailed state information").action(async (countryIso2, stateIso2, options, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const flags = {
+      json: globalOpts.json ?? false,
+      quiet: globalOpts.quiet ?? false,
+      noFooter: globalOpts.footer === false
+    };
+    let countryCode;
+    if (countryIso2) {
+      countryCode = countryIso2.toUpperCase();
+    } else if (isTTY()) {
+      const countrySpinner = await createSpinner("Loading countries...", flags);
+      const { data: allCountries } = await get("/countries");
+      countrySpinner.stop();
+      countryCode = await promptCountry(allCountries);
+    } else {
+      process.stderr.write(chalk6.red("Country ISO2 code required. Example: csc get state IN MH\n"));
+      process.exit(1);
+      return;
+    }
+    let stateCode;
+    if (stateIso2) {
+      stateCode = stateIso2.toUpperCase();
+    } else if (isTTY()) {
+      const stateSpinner = await createSpinner(`Loading states for ${countryCode}...`, flags);
+      const { data: allStates } = await get(`/countries/${countryCode}/states`);
+      stateSpinner.stop();
+      stateCode = await promptState(allStates);
+    } else {
+      process.stderr.write(chalk6.red("State ISO2 code required. Example: csc get state IN MH\n"));
+      process.exit(1);
+      return;
+    }
+    const spinner = await createSpinner(`Fetching ${countryCode}/${stateCode}...`, flags);
+    const { data, usage } = await get(
+      `/countries/${countryCode}/states/${stateCode}`
+    );
+    spinner.stop();
+    if (flags.json) {
+      printJson(data);
+    } else {
+      printDetail("State:", data.name);
+      printDetail("ISO2:", data.iso2);
+      printDetail("Country:", data.country_code);
+      if (data.type) printDetail("Type:", data.type);
+      if (data.latitude && data.longitude) {
+        printDetail("Coordinates:", `${formatCoord(data.latitude)}, ${formatCoord(data.longitude)}`);
+      }
+    }
+    printUsageFooter(usage, flags);
+  });
+}
+
+// src/commands/usage.ts
+import chalk7 from "chalk";
+function tierPrice(dailyLimit) {
+  if (dailyLimit <= 100) return "Free";
+  if (dailyLimit <= 300) return "$5/mo";
+  if (dailyLimit <= 1e3) return "$9/mo";
+  if (dailyLimit <= 3300) return "$29/mo";
+  if (dailyLimit <= 25e3) return "$79/mo";
+  return "Custom";
+}
+function daysUntilMonthlyReset() {
+  const now = /* @__PURE__ */ new Date();
+  const nextMonth = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1));
+  return Math.ceil((nextMonth.getTime() - now.getTime()) / (1e3 * 60 * 60 * 24));
+}
+function registerUsageCommand(program2) {
+  program2.command("usage").description("View API usage and quota").action(async (_options, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const flags = {
+      json: globalOpts.json ?? false,
+      quiet: globalOpts.quiet ?? false,
+      noFooter: globalOpts.footer === false
+    };
+    const spinner = await createSpinner("Fetching usage...", flags);
+    const { usage } = await get("/countries/IN");
+    spinner.stop();
+    if (!usage) {
+      if (flags.json) {
+        process.stdout.write(JSON.stringify({ error: "Usage information not available." }) + "\n");
+      } else {
+        console.log(chalk7.yellow("Usage information not available."));
+      }
+      return;
+    }
+    const { dailyUsed, dailyLimit, monthlyUsed, monthlyLimit } = usage;
+    if (dailyLimit === 0 || monthlyLimit === 0) {
+      if (flags.json) {
+        process.stdout.write(JSON.stringify({ error: "Usage limit data is unavailable." }) + "\n");
+      } else {
+        console.log(chalk7.yellow("Usage limit data is unavailable."));
+      }
+      return;
+    }
+    const tier = getTierName(dailyLimit);
+    const price = tierPrice(dailyLimit);
+    const dailyPct = Math.round(dailyUsed / dailyLimit * 100);
+    const monthlyPct = Math.round(monthlyUsed / monthlyLimit * 100);
+    if (flags.json) {
+      process.stdout.write(
+        JSON.stringify({
+          plan: tier,
+          price,
+          daily: { used: dailyUsed, limit: dailyLimit, percent: dailyPct },
+          monthly: { used: monthlyUsed, limit: monthlyLimit, percent: monthlyPct }
+        }) + "\n"
+      );
+      return;
+    }
+    console.log(`${chalk7.bold("Plan:".padEnd(12))}${tier} (${price})`);
+    console.log(
+      `${chalk7.bold("Daily:".padEnd(12))}${progressBar(dailyUsed, dailyLimit)} ${formatNumber(dailyUsed)} / ${formatNumber(dailyLimit)} (${dailyPct}%)`
+    );
+    console.log(
+      `${chalk7.bold("Monthly:".padEnd(12))}${progressBar(monthlyUsed, monthlyLimit)} ${formatNumber(monthlyUsed)} / ${formatNumber(monthlyLimit)} (${monthlyPct}%)`
+    );
+    console.log(
+      `${chalk7.bold("Resets:".padEnd(12))}Daily in ${timeUntilDailyReset()} | Monthly in ${daysUntilMonthlyReset()} days`
+    );
+  });
+}
+
+// src/commands/upgrade.ts
+import chalk8 from "chalk";
+import open from "open";
+var PLANS = [
+  { name: "Community", price: "Free", daily: 100, monthly: 3e3 },
+  { name: "Starter", price: "$5/mo", daily: 300, monthly: 9e3 },
+  { name: "Supporter", price: "$9/mo", daily: 1e3, monthly: 3e4 },
+  { name: "Professional", price: "$29/mo", daily: 3300, monthly: 1e5 },
+  { name: "Business", price: "$79/mo", daily: 25e3, monthly: 75e4 }
+];
+function registerUpgradeCommand(program2) {
+  program2.command("upgrade").description("View plans and open pricing page").action(async (_options, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const flags = {
+      json: globalOpts.json ?? false,
+      quiet: globalOpts.quiet ?? false,
+      noFooter: globalOpts.footer === false
+    };
+    let usage = null;
+    let currentPlan;
+    const key = getApiKey();
+    if (key) {
+      const spinner = await createSpinner("Fetching current plan...", flags);
+      const result = await validateKey(key);
+      spinner.stop();
+      if (result.valid && result.usage) {
+        usage = result.usage;
+        currentPlan = getTierName(result.usage.dailyLimit);
+      }
+    }
+    if (flags.json) {
+      const output = { plans: PLANS };
+      if (currentPlan) output.currentPlan = currentPlan;
+      process.stdout.write(JSON.stringify(output) + "\n");
+      return;
+    }
+    if (currentPlan) {
+      console.log(`Current plan: ${chalk8.bold(currentPlan)}
+`);
+    }
+    console.log("Available plans:\n");
+    printTable(
+      ["Plan", "Price", "Daily", "Monthly"],
+      PLANS.map((p) => [
+        p.name,
+        p.price,
+        p.daily.toLocaleString("en-US"),
+        p.monthly.toLocaleString("en-US")
+      ])
+    );
+    printUsageFooter(usage, flags);
+    console.log(`
+${chalk8.dim("Opening pricing page...")}`);
+    await open("https://app.countrystatecity.in/pricing");
+  });
+}
+
+// src/commands/generate.ts
+import chalk9 from "chalk";
+import { mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+
+// src/templates/react-dropdown.ts
+function generateCountryDropdown(countries, tsx) {
+  const ext = tsx ? "tsx" : "jsx";
+  const dataJson = countries.map(
+    (c) => `  { id: ${c.id}, name: ${JSON.stringify(c.name)}, iso2: ${JSON.stringify(c.iso2)}, phonecode: ${JSON.stringify(c.phonecode)}, emoji: ${JSON.stringify(c.emoji)} }`
+  ).join(",\n");
+  return `// CountrySelect.${ext}
+// Generated by @countrystatecity/cli
+// Data: ${countries.length} countries from countrystatecity.in
+
+import { useState } from 'react';
+${tsx ? `
+interface Country {
+  id: number;
+  name: string;
+  iso2: string;
+  phonecode: string;
+  emoji: string;
+}
+
+interface CountrySelectProps {
+  value?: string;
+  onChange?: (iso2: string, country: Country) => void;
+  placeholder?: string;
+  className?: string;
+  disabled?: boolean;
+}
+` : ""}
+const countries${tsx ? ": Country[]" : ""} = [
+${dataJson}
+];
+
+export default function CountrySelect(${tsx ? `{
+  value,
+  onChange,
+  placeholder = "Select a country",
+  className = "",
+  disabled = false,
+}: CountrySelectProps` : `{
+  value,
+  onChange,
+  placeholder = "Select a country",
+  className = "",
+  disabled = false,
+}`}) {
+  const [internalSelected, setInternalSelected] = useState(value ?? "");
+  const selected = value ?? internalSelected;
+
+  const handleChange = (e${tsx ? ": React.ChangeEvent<HTMLSelectElement>" : ""}) => {
+    const iso2 = e.target.value;
+    setInternalSelected(iso2);
+    const country = countries.find(c => c.iso2 === iso2);
+    if (onChange && country) onChange(iso2, country);
+  };
+
+  return (
+    <select
+      value={selected}
+      onChange={handleChange}
+      className={className}
+      disabled={disabled}
+    >
+      <option value="">{placeholder}</option>
+      {countries.map((c) => (
+        <option key={c.iso2} value={c.iso2}>
+          {c.emoji} {c.name}
+        </option>
+      ))}
+    </select>
+  );
+}
+`;
+}
+function generateStateDropdown(states, countryCode, tsx) {
+  const ext = tsx ? "tsx" : "jsx";
+  const dataJson = states.map(
+    (s) => `  { id: ${s.id}, name: ${JSON.stringify(s.name)}, iso2: ${JSON.stringify(s.iso2)} }`
+  ).join(",\n");
+  return `// StateSelect.${ext}
+// Generated by @countrystatecity/cli
+// Data: ${states.length} states for ${countryCode} from countrystatecity.in
+
+import { useState } from 'react';
+${tsx ? `
+interface State {
+  id: number;
+  name: string;
+  iso2: string;
+}
+
+interface StateSelectProps {
+  countryCode?: string;
+  value?: string;
+  onChange?: (iso2: string, state: State) => void;
+  placeholder?: string;
+  className?: string;
+  disabled?: boolean;
+}
+` : ""}
+const states${tsx ? ": State[]" : ""} = [
+${dataJson}
+];
+
+export default function StateSelect(${tsx ? `{
+  countryCode = "${countryCode}",
+  value,
+  onChange,
+  placeholder = "Select a state",
+  className = "",
+  disabled = false,
+}: StateSelectProps` : `{
+  countryCode = "${countryCode}",
+  value,
+  onChange,
+  placeholder = "Select a state",
+  className = "",
+  disabled = false,
+}`}) {
+  const [internalSelected, setInternalSelected] = useState(value ?? "");
+  const selected = value ?? internalSelected;
+
+  const handleChange = (e${tsx ? ": React.ChangeEvent<HTMLSelectElement>" : ""}) => {
+    const iso2 = e.target.value;
+    setInternalSelected(iso2);
+    const state = states.find(s => s.iso2 === iso2);
+    if (onChange && state) onChange(iso2, state);
+  };
+
+  return (
+    <select
+      value={selected}
+      onChange={handleChange}
+      className={className}
+      disabled={disabled}
+      data-country={countryCode}
+    >
+      <option value="">{placeholder}</option>
+      {states.map((s) => (
+        <option key={s.iso2} value={s.iso2}>
+          {s.name}
+        </option>
+      ))}
+    </select>
+  );
+}
+`;
+}
+function generateCityDropdown(cities, countryCode, stateCode, tsx) {
+  const ext = tsx ? "tsx" : "jsx";
+  const dataJson = cities.map((c) => `  { id: ${c.id}, name: ${JSON.stringify(c.name)} }`).join(",\n");
+  return `// CitySelect.${ext}
+// Generated by @countrystatecity/cli
+// Data: ${cities.length} cities for ${countryCode}/${stateCode} from countrystatecity.in
+
+import { useState } from 'react';
+${tsx ? `
+interface City {
+  id: number;
+  name: string;
+}
+
+interface CitySelectProps {
+  countryCode?: string;
+  stateCode?: string;
+  value?: string;
+  onChange?: (name: string, city: City) => void;
+  placeholder?: string;
+  className?: string;
+  disabled?: boolean;
+}
+` : ""}
+const cities${tsx ? ": City[]" : ""} = [
+${dataJson}
+];
+
+export default function CitySelect(${tsx ? `{
+  countryCode = "${countryCode}",
+  stateCode = "${stateCode}",
+  value,
+  onChange,
+  placeholder = "Select a city",
+  className = "",
+  disabled = false,
+}: CitySelectProps` : `{
+  countryCode = "${countryCode}",
+  stateCode = "${stateCode}",
+  value,
+  onChange,
+  placeholder = "Select a city",
+  className = "",
+  disabled = false,
+}`}) {
+  const [internalSelected, setInternalSelected] = useState(value ?? "");
+  const selected = value ?? internalSelected;
+
+  const handleChange = (e${tsx ? ": React.ChangeEvent<HTMLSelectElement>" : ""}) => {
+    const name = e.target.value;
+    setInternalSelected(name);
+    const city = cities.find(c => c.name === name);
+    if (onChange && city) onChange(name, city);
+  };
+
+  return (
+    <select
+      value={selected}
+      onChange={handleChange}
+      className={className}
+      disabled={disabled}
+      data-country={countryCode}
+      data-state={stateCode}
+    >
+      <option value="">{placeholder}</option>
+      {cities.map((c) => (
+        <option key={c.id} value={c.name}>
+          {c.name}
+        </option>
+      ))}
+    </select>
+  );
+}
+`;
+}
+
+// src/templates/prisma-seed.ts
+function generateCountrySeed(countries) {
+  const dataJson = countries.map(
+    (c) => `  { name: ${JSON.stringify(c.name)}, iso2: ${JSON.stringify(c.iso2)}, iso3: ${JSON.stringify(c.iso3)}, phonecode: ${JSON.stringify(c.phonecode)}, capital: ${JSON.stringify(c.capital || "")}, currency: ${JSON.stringify(c.currency)} }`
+  ).join(",\n");
+  return `// seed-countries.ts
+// Generated by @countrystatecity/cli
+// Data: ${countries.length} countries from countrystatecity.in
+
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+const countries = [
+${dataJson}
+];
+
+async function main() {
+  console.log(\`Seeding \${countries.length} countries...\`);
+  await prisma.country.createMany({
+    data: countries,
+    skipDuplicates: true,
+  });
+  console.log('Done.');
+}
+
+main()
+  .catch(console.error)
+  .finally(() => prisma.$disconnect());
+`;
+}
+function generateStateSeed(states, countryCode) {
+  const dataJson = states.map(
+    (s) => `  { name: ${JSON.stringify(s.name)}, iso2: ${JSON.stringify(s.iso2)}, countryCode: ${JSON.stringify(s.country_code)} }`
+  ).join(",\n");
+  return `// seed-states.ts
+// Generated by @countrystatecity/cli
+// Data: ${states.length} states for ${countryCode} from countrystatecity.in
+
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+const states = [
+${dataJson}
+];
+
+async function main() {
+  console.log(\`Seeding \${states.length} states...\`);
+  await prisma.state.createMany({
+    data: states,
+    skipDuplicates: true,
+  });
+  console.log('Done.');
+}
+
+main()
+  .catch(console.error)
+  .finally(() => prisma.$disconnect());
+`;
+}
+function generateCitySeed(cities, countryCode, stateCode) {
+  const dataJson = cities.map((c) => `  { name: ${JSON.stringify(c.name)} }`).join(",\n");
+  return `// seed-cities.ts
+// Generated by @countrystatecity/cli
+// Data: ${cities.length} cities for ${countryCode}/${stateCode} from countrystatecity.in
+
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+const cities = [
+${dataJson}
+];
+
+async function main() {
+  console.log(\`Seeding \${cities.length} cities...\`);
+  await prisma.city.createMany({
+    data: cities,
+    skipDuplicates: true,
+  });
+  console.log('Done.');
+}
+
+main()
+  .catch(console.error)
+  .finally(() => prisma.$disconnect());
+`;
+}
+
+// src/commands/generate.ts
+function enforceTierGate(usage, spinner) {
+  if (!usage || usage.dailyLimit < 1e3) {
+    spinner.fail("Tier check failed.");
+    console.log(
+      chalk9.yellow("The generate command requires a Supporter plan or above ($9/mo).")
+    );
+    if (usage) {
+      const tierName = usage.dailyLimit <= 100 ? "Community (Free)" : "Starter ($5/mo)";
+      console.log(`Your current plan: ${chalk9.bold(tierName)}
+`);
+    } else {
+      console.log(chalk9.dim("Could not verify your plan. Ensure usage headers are available.\n"));
+    }
+    console.log(chalk9.dim("Run `csc upgrade` to unlock code generation."));
+    process.exit(1);
+  }
+}
+function registerGenerateCommands(program2) {
+  const generate = program2.command("generate").description("Generate code from API data");
+  generate.command("dropdown").description("Generate a dropdown/select component").requiredOption("-e, --entity <type>", "Entity type: countries, states, or cities").requiredOption("-f, --format <format>", "Output format: react").option("-c, --country <iso2>", "Country ISO2 code (required for states/cities)").option("-s, --state <iso2>", "State ISO2 code (required for cities)").option("-o, --output <dir>", "Output directory", process.cwd()).option("--typescript", "Generate TypeScript (.tsx)", true).option("--no-typescript", "Generate JavaScript (.jsx)").action(
+    async (options, cmd) => {
+      const globalOpts = cmd.optsWithGlobals();
+      const flags = {
+        json: globalOpts.json ?? false,
+        quiet: globalOpts.quiet ?? false,
+        noFooter: globalOpts.footer === false
+      };
+      if (options.format !== "react") {
+        process.stderr.write(chalk9.red(`Unsupported format: ${options.format}`) + "\n");
+        process.stderr.write(chalk9.dim("Supported formats: react") + "\n");
+        process.exit(1);
+      }
+      const spinner = await createSpinner("Fetching data...", flags);
+      const tsx = options.typescript;
+      const ext = tsx ? "tsx" : "jsx";
+      let content;
+      let filename;
+      let fetchUsage = null;
+      if (options.entity === "countries") {
+        const { data, usage } = await get("/countries");
+        fetchUsage = usage;
+        enforceTierGate(usage, spinner);
+        content = generateCountryDropdown(data, tsx);
+        filename = `CountrySelect.${ext}`;
+      } else if (options.entity === "states") {
+        if (!options.country) {
+          spinner.fail("Country code required for states.");
+          process.stderr.write(chalk9.dim("Use --country IN") + "\n");
+          process.exit(1);
+        }
+        const code = options.country.toUpperCase();
+        const { data, usage } = await get(`/countries/${code}/states`);
+        fetchUsage = usage;
+        enforceTierGate(usage, spinner);
+        content = generateStateDropdown(data, code, tsx);
+        filename = `StateSelect.${ext}`;
+      } else if (options.entity === "cities") {
+        if (!options.country || !options.state) {
+          spinner.fail("Country and state codes required for cities.");
+          process.stderr.write(chalk9.dim("Use --country IN --state MH") + "\n");
+          process.exit(1);
+        }
+        const countryCode = options.country.toUpperCase();
+        const stateCode = options.state.toUpperCase();
+        const { data, usage } = await get(
+          `/countries/${countryCode}/states/${stateCode}/cities`
+        );
+        fetchUsage = usage;
+        enforceTierGate(usage, spinner);
+        content = generateCityDropdown(data, countryCode, stateCode, tsx);
+        filename = `CitySelect.${ext}`;
+      } else {
+        spinner.fail(`Unknown entity: ${options.entity}`);
+        process.stderr.write(chalk9.dim("Supported entities: countries, states, cities") + "\n");
+        process.exit(1);
+      }
+      try {
+        await mkdir(options.output, { recursive: true });
+        const filepath = join(options.output, filename);
+        await writeFile(filepath, content, "utf-8");
+        spinner.succeed(`Generated ${chalk9.bold(filepath)}`);
+      } catch (err) {
+        spinner.fail("Failed to write output file.");
+        process.stderr.write(chalk9.red(String(err)) + "\n");
+        process.exit(1);
+      }
+      printUsageFooter(fetchUsage, flags);
+    }
+  );
+  generate.command("seed").description("Generate a database seed file").requiredOption("-e, --entity <type>", "Entity type: countries, states, or cities").requiredOption("-f, --format <format>", "Output format: prisma").option("-c, --country <iso2>", "Country ISO2 code (for states/cities)").option("-s, --state <iso2>", "State ISO2 code (for cities)").option("-o, --output <dir>", "Output directory", process.cwd()).action(
+    async (options, cmd) => {
+      const globalOpts = cmd.optsWithGlobals();
+      const flags = {
+        json: globalOpts.json ?? false,
+        quiet: globalOpts.quiet ?? false,
+        noFooter: globalOpts.footer === false
+      };
+      if (options.format !== "prisma") {
+        process.stderr.write(chalk9.red(`Unsupported format: ${options.format}`) + "\n");
+        process.stderr.write(chalk9.dim("Supported formats: prisma") + "\n");
+        process.exit(1);
+      }
+      const spinner = await createSpinner("Fetching data...", flags);
+      let content;
+      let filename;
+      let fetchUsage = null;
+      if (options.entity === "countries") {
+        const { data, usage } = await get("/countries");
+        fetchUsage = usage;
+        enforceTierGate(usage, spinner);
+        content = generateCountrySeed(data);
+        filename = "seed-countries.ts";
+      } else if (options.entity === "states") {
+        if (!options.country) {
+          spinner.fail("Country code required for states.");
+          process.stderr.write(chalk9.dim("Use --country IN") + "\n");
+          process.exit(1);
+        }
+        const code = options.country.toUpperCase();
+        const { data, usage } = await get(`/countries/${code}/states`);
+        fetchUsage = usage;
+        enforceTierGate(usage, spinner);
+        content = generateStateSeed(data, code);
+        filename = "seed-states.ts";
+      } else if (options.entity === "cities") {
+        if (!options.country || !options.state) {
+          spinner.fail("Country and state codes required for cities.");
+          process.stderr.write(chalk9.dim("Use --country IN --state MH") + "\n");
+          process.exit(1);
+        }
+        const countryCode = options.country.toUpperCase();
+        const stateCode = options.state.toUpperCase();
+        const { data, usage } = await get(
+          `/countries/${countryCode}/states/${stateCode}/cities`
+        );
+        fetchUsage = usage;
+        enforceTierGate(usage, spinner);
+        content = generateCitySeed(data, countryCode, stateCode);
+        filename = "seed-cities.ts";
+      } else {
+        spinner.fail(`Unknown entity: ${options.entity}`);
+        process.stderr.write(chalk9.dim("Supported entities: countries, states, cities") + "\n");
+        process.exit(1);
+      }
+      try {
+        await mkdir(options.output, { recursive: true });
+        const filepath = join(options.output, filename);
+        await writeFile(filepath, content, "utf-8");
+        spinner.succeed(`Generated ${chalk9.bold(filepath)}`);
+      } catch (err) {
+        spinner.fail("Failed to write output file.");
+        process.stderr.write(chalk9.red(String(err)) + "\n");
+        process.exit(1);
+      }
+      printUsageFooter(fetchUsage, flags);
+    }
+  );
+}
+
+// src/commands/explore.ts
+import select from "@inquirer/select";
+import search2 from "@inquirer/search";
+var ACTION_BACK = "back";
+async function promptCountry2(countries) {
+  return search2({
+    message: "Select a country",
+    source: (input) => {
+      const query = (input ?? "").toLowerCase();
+      return Promise.resolve(
+        countries.filter(
+          (c) => c.name.toLowerCase().includes(query) || c.iso2.toLowerCase().includes(query)
+        ).map((c) => ({
+          name: `${c.emoji}  ${c.name} (${c.iso2})`,
+          value: c.iso2
+        }))
+      );
+    }
+  });
+}
+async function promptState2(states) {
+  return search2({
+    message: "Select a state",
+    source: (input) => {
+      const query = (input ?? "").toLowerCase();
+      return Promise.resolve(
+        states.filter(
+          (s) => s.name.toLowerCase().includes(query) || (s.iso2 ?? "").toLowerCase().includes(query)
+        ).map((s) => ({ name: s.name, value: s.iso2 ?? "" }))
+      );
+    }
+  });
+}
+async function promptAction(countryIso, stateName) {
+  return select({
+    message: `Actions for ${countryIso} / ${stateName}`,
+    choices: [
+      { name: "View cities", value: "cities" },
+      { name: "View country details", value: "country-detail" },
+      { name: "View state details", value: "state-detail" },
+      { name: "Generate dropdown (hint)", value: "generate-dropdown" },
+      { name: "Generate seed (hint)", value: "generate-seed" },
+      { name: "Go back", value: ACTION_BACK }
+    ]
+  });
+}
+async function handleViewCities(countryIso, stateIso) {
+  const { data: cities, usage } = await get(
+    `/countries/${countryIso}/states/${stateIso}/cities`
+  );
+  if (cities.length === 0) {
+    stderr("No cities found for this state.");
+    return usage;
+  }
+  const rows = cities.map((c) => [String(c.id), c.name]);
+  printTable(["ID", "Name"], rows);
+  return usage;
+}
+async function handleCountryDetail(countryIso) {
+  const { data, usage } = await get(`/countries/${countryIso}`);
+  printJson(data);
+  return usage;
+}
+async function handleStateDetail(countryIso, stateIso) {
+  const { data, usage } = await get(
+    `/countries/${countryIso}/states/${stateIso}`
+  );
+  printJson(data);
+  return usage;
+}
+function handleGenerateDropdown(countryIso) {
+  stderr(`Run: csc generate dropdown -e states -f react -c ${countryIso}`);
+}
+function handleGenerateSeed(countryIso) {
+  stderr(`Run: csc generate seed -e states -f prisma -c ${countryIso}`);
+}
+async function runExploreSession(flags) {
+  const { data: countries, usage: countriesUsage } = await get("/countries");
+  let latestUsage = countriesUsage;
+  const countryIso = await promptCountry2(countries);
+  const { data: states, usage: statesUsage } = await get(
+    `/countries/${countryIso}/states`
+  );
+  latestUsage = statesUsage ?? latestUsage;
+  if (states.length === 0) {
+    stderr(`No states found for ${countryIso}.`);
+    return latestUsage;
+  }
+  const stateIso = await promptState2(states);
+  const selectedState = states.find((s) => s.iso2 === stateIso);
+  const stateName = selectedState?.name ?? stateIso;
+  let running = true;
+  while (running) {
+    const action = await promptAction(countryIso, stateName);
+    if (action === ACTION_BACK) {
+      running = false;
+      break;
+    }
+    if (action === "cities") {
+      const usage = await handleViewCities(countryIso, stateIso);
+      latestUsage = usage ?? latestUsage;
+    } else if (action === "country-detail") {
+      const usage = await handleCountryDetail(countryIso);
+      latestUsage = usage ?? latestUsage;
+    } else if (action === "state-detail") {
+      const usage = await handleStateDetail(countryIso, stateIso);
+      latestUsage = usage ?? latestUsage;
+    } else if (action === "generate-dropdown") {
+      handleGenerateDropdown(countryIso);
+    } else if (action === "generate-seed") {
+      handleGenerateSeed(countryIso);
+    }
+  }
+  return latestUsage;
+}
+function registerExploreCommand(program2) {
+  program2.command("explore").description("Interactive geographic data browser").action(async (_options, cmd) => {
+    if (!process.stdin.isTTY) {
+      stderr("Error: `csc explore` requires an interactive terminal (TTY).");
+      stderr("Use `csc search` for non-interactive workflows.");
+      process.exit(1);
+    }
+    const globalOpts = cmd.optsWithGlobals();
+    const flags = {
+      json: globalOpts.json ?? false,
+      quiet: globalOpts.quiet ?? false,
+      noFooter: globalOpts.footer === false
+    };
+    const usage = await runExploreSession(flags);
+    printUsageFooter(usage, flags);
+  });
+}
+
+// src/commands/export.ts
+import chalk10 from "chalk";
+import open2 from "open";
+var EXPORT_URL = "https://export.countrystatecity.in";
+function registerExportCommand(program2) {
+  program2.command("export").description("Open the export tool in your browser").action(async function() {
+    const globals = this.optsWithGlobals();
+    if (globals.json) {
+      console.log(JSON.stringify({ url: EXPORT_URL }));
+      return;
+    }
+    console.log(chalk10.dim("Opening the CountryStateCity export tool..."));
+    console.log(chalk10.dim(`URL: ${EXPORT_URL}`));
+    await open2(EXPORT_URL);
+  });
+}
+
+// src/lib/branding.ts
+import chalk11 from "chalk";
+var VERSION = "v0.1.1";
+var GRADIENT_COLORS = [
+  "#2296f3",
+  // row 1 — blue
+  "#2ba8e8",
+  // row 2 — light blue
+  "#4dbe9e",
+  // row 3 — teal
+  "#8ecf5e",
+  // row 4 — lime-green
+  "#cddc39"
+  // row 5 — lime
+];
+var ASCII_ROWS = [
+  "   \u2588\u2588\u2588\u2588\u2588\u2588 \u2588\u2588\u2588\u2588\u2588\u2588\u2588  \u2588\u2588\u2588\u2588\u2588\u2588",
+  "  \u2588\u2588      \u2588\u2588      \u2588\u2588",
+  "  \u2588\u2588      \u2588\u2588\u2588\u2588\u2588\u2588\u2588 \u2588\u2588",
+  "  \u2588\u2588           \u2588\u2588 \u2588\u2588",
+  "   \u2588\u2588\u2588\u2588\u2588\u2588 \u2588\u2588\u2588\u2588\u2588\u2588\u2588  \u2588\u2588\u2588\u2588\u2588\u2588"
+];
+function getAsciiArt() {
+  const coloredRows = ASCII_ROWS.map(
+    (row, index) => chalk11.hex(GRADIENT_COLORS[index])(row)
+  );
+  const subtitle = chalk11.dim("  Country State City CLI ") + chalk11.dim(VERSION);
+  return coloredRows.join("\n") + "\n\n" + subtitle;
+}
+function formatCommand(name, description) {
+  const paddedName = name.padEnd(12);
+  return `  ${chalk11.hex("#2296f3")(paddedName)}${chalk11.dim(description)}`;
+}
+function formatFlag(flag, description) {
+  const paddedFlag = flag.padEnd(16);
+  return `  ${paddedFlag}${chalk11.dim(description)}`;
+}
+function getBrandedHelp() {
+  const sectionHeader = (title) => chalk11.hex("#f97316")(title);
+  const commands = [
+    ["auth", "Save or remove your API key"],
+    ["search", "Search countries, states, or cities by name"],
+    ["get", "Fetch a specific country, state, or city by ISO code"],
+    ["explore", "Interactively browse geographic data"],
+    ["usage", "Show your current API usage and tier"],
+    ["upgrade", "View plans and open the pricing page"],
+    ["generate", "Generate dropdown or seed data for a framework"],
+    ["export", "Export geographic data to JSON or CSV"]
+  ];
+  const flags = [
+    ["--json", "Output raw JSON instead of formatted tables"],
+    ["--quiet", "Suppress all decorative output"],
+    ["--no-footer", "Hide the usage footer after each command"]
+  ];
+  const lines = [
+    getAsciiArt(),
+    "",
+    sectionHeader("COMMANDS"),
+    "",
+    ...commands.map(([name, desc]) => formatCommand(name, desc)),
+    "",
+    sectionHeader("GLOBAL FLAGS"),
+    "",
+    ...flags.map(([flag, desc]) => formatFlag(flag, desc)),
+    "",
+    chalk11.dim("Run csc <command> --help for details")
+  ];
+  return lines.join("\n");
+}
+
+// src/lib/root-help.ts
+var ROOT_COMMANDS = /* @__PURE__ */ new Set([
+  "auth",
+  "search",
+  "get",
+  "usage",
+  "upgrade",
+  "generate",
+  "explore",
+  "export"
+]);
+function isRootHelpRequested(argv) {
+  const args = argv.slice(2);
+  if (args.length === 0) {
+    return true;
+  }
+  const helpRequested = args.includes("-h") || args.includes("--help");
+  if (!helpRequested) {
+    return false;
+  }
+  const commandArg = args.find((arg) => !arg.startsWith("-"));
+  return commandArg === void 0 || !ROOT_COMMANDS.has(commandArg);
+}
+function shouldShowBrandedHelp(argv) {
+  const args = argv.slice(2);
+  return !args.includes("--json") && !args.includes("-q") && !args.includes("--quiet");
+}
+
+// src/index.ts
+function showBrandedHelpAndExit() {
+  process.stdout.write(getBrandedHelp() + "\n");
+  process.exit(0);
+}
+var program = new Command();
+program.addHelpCommand(false);
+program.name("csc").description("Official CLI for the Country State City API").version("0.1.1").helpOption("-h, --help", "Display help for csc").option("--json", "Output raw JSON instead of formatted tables", false).option("-q, --quiet", "Suppress all decorative output", false).option("--no-footer", "Hide the usage footer after each command");
+registerAuthCommands(program);
+registerSearchCommands(program);
+registerGetCommands(program);
+registerUsageCommand(program);
+registerUpgradeCommand(program);
+registerGenerateCommands(program);
+registerExploreCommand(program);
+registerExportCommand(program);
+if (isRootHelpRequested(process.argv) && shouldShowBrandedHelp(process.argv)) {
+  showBrandedHelpAndExit();
+}
+program.parse();