@countrystatecity/cli

Official CLI for the Country State City API — search, explore, and generate code from geographic data.

npm install -g @countrystatecity/cli

Quick Start

# 1. Get your free API key at https://app.countrystatecity.in
csc auth login

# 2. Search countries
csc search countries

# 3. Get country details
csc get country IN

Commands

Authentication

csc auth login                # Interactive login with API key
csc auth login --key <KEY>    # Login with key directly
csc auth status               # Check current auth status
csc auth logout               # Remove stored API key

Search

# List all countries
csc search countries
csc search countries --filter "united"
csc search countries --json

# List states for a country
csc search states --country IN
csc search states -c US --filter "new"

# List cities for a state
csc search cities --country IN --state MH
csc search cities -c US -s CA --json

# Global search (matches country names)
csc search india

Get Details

# Detailed country info (timezones, coordinates, currency, etc.)
csc get country IN
csc get country US --json

# Detailed state info
csc get state IN MH

Usage & Billing

# View API usage with progress bars
csc usage

# View plans and open pricing page
csc upgrade

Code Generation

Generate ready-to-use components and seed files from live API data.

Requires Supporter plan or above ($9/mo). Run csc upgrade to view plans.

# Generate a React dropdown component
csc generate dropdown --entity countries --format react
csc generate dropdown -e states -f react --country IN
csc generate dropdown -e cities -f react -c IN -s MH

# Generate a Prisma seed file
csc generate seed --entity countries --format prisma
csc generate seed -e states -f prisma --country IN
csc generate seed -e cities -f prisma -c IN -s MH

# Options
--output <dir>     # Output directory (default: current directory)
--no-typescript    # Generate .jsx instead of .tsx

Example: Generated Country Dropdown

// CountrySelect.tsx — generated by csc
import { useState } from 'react';

const countries = [
  { id: 101, name: "India", iso2: "IN", phonecode: "91", emoji: "🇮🇳" },
  // ... 250 countries embedded
];

export default function CountrySelect({ value, onChange, placeholder, className, disabled }) {
  // Full select component with onChange handler
}

Example: Generated Prisma Seed

// seed-countries.ts — generated by csc
import { PrismaClient } from '@prisma/client';
const prisma = new PrismaClient();

const countries = [
  { name: "India", iso2: "IN", iso3: "IND", phonecode: "91", capital: "New Delhi", currency: "INR" },
  // ... 250 countries
];

async function main() {
  await prisma.country.createMany({ data: countries, skipDuplicates: true });
}

Tiers

| Feature | Community (Free) | Starter ($5/mo) | Supporter ($9/mo) | Professional ($29/mo) | Business ($79/mo) | |---------|------------------|-----------------|-------------------|----------------------|-------------------| | Search & Get | Yes | Yes | Yes | Yes | Yes | | Daily requests | 100 | 300 | 1,000 | 3,300 | 25,000 | | Monthly requests | 3,000 | 9,000 | 30,000 | 100,000 | 750,000 | | Code generation | No | No | Yes | Yes | Yes |

Links

• API Documentation
• Dashboard
• Pricing

License

MIT