@countrystatecity/cli 0.1.4 → 0.1.6

package/README.md

@@ -55,18 +55,40 @@ csc search countries
 csc search countries --filter "united"
 csc search countries --json
 
+# List all states globally
+csc search states
+
 # List states for a country
 csc search states --country IN
 csc search states -c US --filter "new"
 
+# List all cities globally
+csc search cities
+
 # List all cities for a country
 csc search cities --country IN
-csc search cities --country IN --json
 
 # List cities for a specific state
 csc search cities --country IN --state MH
 csc search cities -c US -s CA --json
 
+# List all world regions
+csc search regions
+csc search regions --filter "asia"
+
+# List all currencies
+csc search currencies
+csc search currencies --filter "dollar"
+
+# List all timezones
+csc search timezones
+csc search timezones --country IN
+csc search timezones --filter "kolkata"
+
+# List all country phone codes
+csc search phonecodes
+csc search phonecodes --filter "india"
+
 # Global search (matches country names)
 csc search india
 ```
@@ -83,6 +105,10 @@ csc get country           # Interactive — prompts to pick a country (TTY only)
 csc get state IN MH
 csc get state IN MH --json
 csc get state             # Interactive — prompts for country then state (TTY only)
+
+# Detailed city info by ID
+csc get city IN MH 57589
+csc get city IN MH 57589 --json
 ```
 
 ### Usage & Billing

package/dist/index.js

@@ -417,15 +417,14 @@ function printDetail(label, value) {
 }
 
 // src/commands/search.ts
+function resolveFlags(cmd) {
+  const g = cmd.optsWithGlobals();
+  return { json: g.json ?? false, quiet: g.quiet ?? false, noFooter: g.footer === false };
+}
 function registerSearchCommands(program2) {
-  const search3 = program2.command("search").description("Search countries, states, and cities");
+  const search3 = program2.command("search").description("Search countries, states, cities, and more");
   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 flags = resolveFlags(cmd);
     const spinner = await createSpinner("Fetching countries...", flags);
     const { data, usage } = await get("/countries");
     spinner.stop();
@@ -437,40 +436,26 @@ function registerSearchCommands(program2) {
     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);
+      printTable(
+        ["ISO2", "ISO3", "Name", "Capital", "Phone", "Currency"],
+        countries.map((c) => [
+          c.iso2,
+          c.iso3,
+          c.name,
+          c.capital || "",
+          c.phonecode ? `+${c.phonecode.replace(/^\+/, "")}` : "",
+          c.currency || ""
+        ])
+      );
     }
     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`);
+  search3.command("states").description("List states for a country, or all states globally").option("-c, --country <iso2>", "Country ISO2 code (omit to get all states globally)").option("--filter <text>", "Filter by name").action(async (options, cmd) => {
+    const flags = resolveFlags(cmd);
+    const code = options.country?.toUpperCase();
+    const endpoint = code ? `/countries/${code}/states` : "/states";
+    const spinner = await createSpinner(code ? `Fetching states for ${code}...` : "Fetching all states...", flags);
+    const { data, usage } = await get(endpoint);
     spinner.stop();
     let states = data;
     if (options.filter) {
@@ -480,72 +465,142 @@ function registerSearchCommands(program2) {
     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);
+      printTable(
+        code ? ["ID", "Name", "ISO2", "Type"] : ["ID", "Name", "ISO2", "Type", "Country"],
+        states.map(
+          (s) => code ? [String(s.id), s.name, s.iso2 || "", s.type || ""] : [String(s.id), s.name, s.iso2 || "", s.type || "", s.country_code || ""]
+        )
+      );
     }
     printUsageFooter(usage, flags);
   });
-  search3.command("cities").description("List cities for a country or state").option("-c, --country <iso2>", "Country ISO2 code").option("-s, --state <iso2>", "State ISO2 code (omit to get all cities in the country)").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;
-        }
-      }
-      const stateCode = options.state?.toUpperCase();
-      let endpoint;
-      let spinnerText;
-      if (stateCode) {
-        endpoint = `/countries/${countryCode}/states/${stateCode}/cities`;
-        spinnerText = `Fetching cities for ${countryCode}/${stateCode}...`;
-      } else {
-        endpoint = `/countries/${countryCode}/cities`;
-        spinnerText = `Fetching all cities for ${countryCode}...`;
-      }
-      const spinner = await createSpinner(spinnerText, flags);
-      const { data, usage } = await get(endpoint);
-      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.command("cities").description("List cities globally, for a country, or 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 flags = resolveFlags(cmd);
+    const countryCode = options.country?.toUpperCase();
+    const stateCode = options.state?.toUpperCase();
+    let endpoint;
+    let spinnerText;
+    if (countryCode && stateCode) {
+      endpoint = `/countries/${countryCode}/states/${stateCode}/cities`;
+      spinnerText = `Fetching cities for ${countryCode}/${stateCode}...`;
+    } else if (countryCode) {
+      endpoint = `/countries/${countryCode}/cities`;
+      spinnerText = `Fetching all cities for ${countryCode}...`;
+    } else {
+      endpoint = "/cities";
+      spinnerText = "Fetching all cities...";
     }
-  );
+    const spinner = await createSpinner(spinnerText, flags);
+    const { data, usage } = await get(endpoint);
+    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 hasExtra = !countryCode;
+      printTable(
+        hasExtra ? ["ID", "Name", "State", "Country"] : ["ID", "Name"],
+        cities.map(
+          (c) => hasExtra ? [String(c.id), c.name, c.state_code || "", c.country_code || ""] : [String(c.id), c.name]
+        )
+      );
+    }
+    printUsageFooter(usage, flags);
+  });
+  search3.command("regions").description("List all world regions").option("--filter <text>", "Filter by name").action(async (options, cmd) => {
+    const flags = resolveFlags(cmd);
+    const spinner = await createSpinner("Fetching regions...", flags);
+    const { data, usage } = await get("/regions");
+    spinner.stop();
+    let regions = data;
+    if (options.filter) {
+      const term = options.filter.toLowerCase();
+      regions = regions.filter((r) => r.name.toLowerCase().includes(term));
+    }
+    if (flags.json) {
+      printJson(regions);
+    } else {
+      printTable(["ID", "Name"], regions.map((r) => [String(r.id), r.name]));
+    }
+    printUsageFooter(usage, flags);
+  });
+  search3.command("currencies").description("List all currencies").option("--filter <text>", "Filter by name or code").action(async (options, cmd) => {
+    const flags = resolveFlags(cmd);
+    const spinner = await createSpinner("Fetching currencies...", flags);
+    const { data, usage } = await get("/currencies");
+    spinner.stop();
+    let currencies = data;
+    if (options.filter) {
+      const term = options.filter.toLowerCase();
+      currencies = currencies.filter(
+        (c) => c.name.toLowerCase().includes(term) || (c.code || "").toLowerCase().includes(term)
+      );
+    }
+    if (flags.json) {
+      printJson(currencies);
+    } else {
+      printTable(
+        ["ID", "Name", "Symbol", "Code"],
+        currencies.map((c) => [String(c.id), c.name, c.symbol || "", c.code || ""])
+      );
+    }
+    printUsageFooter(usage, flags);
+  });
+  search3.command("timezones").description("List all timezones").option("-c, --country <iso2>", "Filter by country ISO2 code").option("--filter <text>", "Filter by zone name or abbreviation").action(async (options, cmd) => {
+    const flags = resolveFlags(cmd);
+    const spinner = await createSpinner("Fetching timezones...", flags);
+    const { data, usage } = await get("/timezones");
+    spinner.stop();
+    let timezones = data;
+    if (options.country) {
+      const code = options.country.toUpperCase();
+      timezones = timezones.filter((t) => (t.countryCode || "").toUpperCase() === code);
+    }
+    if (options.filter) {
+      const term = options.filter.toLowerCase();
+      timezones = timezones.filter(
+        (t) => t.zoneName.toLowerCase().includes(term) || t.abbreviation.toLowerCase().includes(term)
+      );
+    }
+    if (flags.json) {
+      printJson(timezones);
+    } else {
+      printTable(
+        ["Zone Name", "Abbreviation", "UTC Offset", "TZ Name"],
+        timezones.map((t) => [t.zoneName, t.abbreviation, t.gmtOffsetName || String(t.gmtOffset), t.tzName || ""])
+      );
+    }
+    printUsageFooter(usage, flags);
+  });
+  search3.command("phonecodes").description("List all country phone codes").option("--filter <text>", "Filter by country name or code").action(async (options, cmd) => {
+    const flags = resolveFlags(cmd);
+    const spinner = await createSpinner("Fetching phone codes...", flags);
+    const { data, usage } = await get("/phone-codes");
+    spinner.stop();
+    let phonecodes = data;
+    if (options.filter) {
+      const term = options.filter.toLowerCase();
+      phonecodes = phonecodes.filter(
+        (p) => p.name.toLowerCase().includes(term) || (p.iso2 || "").toLowerCase().includes(term)
+      );
+    }
+    if (flags.json) {
+      printJson(phonecodes);
+    } else {
+      printTable(
+        ["ISO2", "Name", "Phone Code"],
+        phonecodes.map((p) => [p.iso2 || "", p.name, `+${p.phonecode.replace(/^\+/, "")}`])
+      );
+    }
+    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 flags = resolveFlags(cmd);
     const spinner = await createSpinner("Searching...", flags);
     const { data, usage } = await get("/countries");
     spinner.stop();
@@ -556,15 +611,17 @@ function registerSearchCommands(program2) {
     } 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);
+      printTable(
+        ["ISO2", "ISO3", "Name", "Capital", "Phone", "Currency"],
+        matches.map((c) => [
+          c.iso2,
+          c.iso3,
+          c.name,
+          c.capital || "",
+          c.phonecode ? `+${c.phonecode.replace(/^\+/, "")}` : "",
+          c.currency || ""
+        ])
+      );
     }
     if (!flags.json) {
       process.stderr.write(
@@ -692,6 +749,34 @@ function registerGetCommands(program2) {
     }
     printUsageFooter(usage, flags);
   });
+  getCmd.command("city <country_iso2> <state_iso2> <city_id>").description("Get detailed city information by ID").action(async (countryIso2, stateIso2, cityId, options, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const flags = {
+      json: globalOpts.json ?? false,
+      quiet: globalOpts.quiet ?? false,
+      noFooter: globalOpts.footer === false
+    };
+    const countryCode = countryIso2.toUpperCase();
+    const stateCode = stateIso2.toUpperCase();
+    const spinner = await createSpinner(`Fetching city ${cityId}...`, flags);
+    const { data, usage } = await get(
+      `/countries/${countryCode}/states/${stateCode}/cities/${cityId}`
+    );
+    spinner.stop();
+    if (flags.json) {
+      printJson(data);
+    } else {
+      const city = data;
+      printDetail("City:", city.name);
+      printDetail("ID:", String(city.id));
+      printDetail("State:", city.state_code || stateCode);
+      printDetail("Country:", city.country_code || countryCode);
+      if (city.latitude && city.longitude) {
+        printDetail("Coordinates:", `${formatCoord(city.latitude)}, ${formatCoord(city.longitude)}`);
+      }
+    }
+    printUsageFooter(usage, flags);
+  });
 }
 
 // src/commands/usage.ts
@@ -1320,7 +1405,7 @@ async function promptCountry2(countries) {
     }
   });
 }
-async function promptState3(states) {
+async function promptState2(states) {
   return search2({
     message: "Select a state",
     source: (input) => {
@@ -1388,7 +1473,7 @@ async function runExploreSession(flags) {
     stderr(`No states found for ${countryIso}.`);
     return latestUsage;
   }
-  const stateIso = await promptState3(states);
+  const stateIso = await promptState2(states);
   const selectedState = states.find((s) => s.iso2 === stateIso);
   const stateName = selectedState?.name ?? stateIso;
   let running = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@countrystatecity/cli",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Official CLI for the Country State City API - search, explore, and generate code from geographic data",
   "files": [
     "dist",