CLI

Official CLI for the Country State City API — search, explore, and generate code from geographic data, right from your terminal. Get a free API key to start, then compare plans when you need more data, higher limits, fuzzy search, or autocomplete.

Like the TypeScript SDK — which the CLI is built on internally — this calls the live API, not a bundled snapshot. It needs an API key and is subject to your plan’s usage quotas. For offline/bundled data with no API key, see npm Packages.

Installation

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

Global Flags

These flags work on every command:

Flag	Short	Description
`--json`		Output raw JSON instead of formatted tables
`--quiet`	`-q`	Suppress all decorative output (spinners, tips)
`--no-footer`		Hide the API usage footer after each command

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

csc search countries
csc search countries --filter "united"
csc search states --country IN
csc search cities --country IN --state MH
csc search regions   # Requires Supporter+ plan
csc search india     # Global search — matches country names

Fuzzy, typo-tolerant search

Requires Professional+ plan.

Works two ways: Global, across a chosen entity type:

csc search "Mumbay" --type city --country IN --fuzzy

--type defaults to city if omitted. --country scopes results and isn’t used with --type country. Per-entity, reusing --filter’s value as the fuzzy query:

csc search countries --filter "Indea" --fuzzy
csc search states --country IN --filter "Maharastra" --fuzzy
csc search cities --country IN --filter "Mumbay" --fuzzy

--fuzzy requires --filter on these subcommands — the CLI exits with an error if you pass --fuzzy without it. On cities, --state is ignored when --fuzzy is set, since fuzzy search only scopes by country. Fuzzy results replace the usual per-entity table with a shared one:

Column	Meaning
Type	`country`, `state`, or `city`
Name	Matched name
Location	State + country for cities, country for states, blank for countries
ID	Record ID
Score	Match confidence — the API’s `match_score`, shown to 2 decimal places

`--fields` and `--sort`

Requires Supporter+ plan.

Available on search countries/states/cities — passed straight through to the API instead of the CLI always fetching full objects:

csc search cities --country IN --fields name,population --sort population:desc
csc search countries --fields name,iso2 --sort name:asc

When --fields narrows the response, output falls back to a generic table showing whatever columns actually came back — the CLI’s usual hardcoded columns (ISO2, Capital, Phone, and so on) may not all be present anymore.

Get Details

csc get country IN
csc get country US --json
csc get country           # Interactive — prompts to pick a country (TTY only)

csc get state IN MH
csc get state              # Interactive — prompts for country then state (TTY only)

Usage & Billing

csc usage
csc usage --json          # Returns { plan, price, daily, monthly }

csc upgrade
csc upgrade --json        # Returns { plans, currentPlan }

csc upgrade fetches live plan and pricing data from the API on every run, so what you see always matches the current pricing page — it isn’t a table baked into the CLI’s own code that can drift out of date.

Plan-Gated Features

Hitting a command your plan doesn’t include shows the specific plan you need and a direct upgrade link, not just a generic message:

Access denied — this endpoint requires a higher plan.
Requires: Professional plan or higher.
Run `csc upgrade` to view available plans: https://app.countrystatecity.in/pricing

Code Generation

Requires Supporter+ plan.

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

csc generate dropdown --entity countries --format react
csc generate dropdown -e states -f react --country IN
csc generate seed --entity countries --format prisma
csc generate seed -e states -f prisma --country IN

Live Location Components

These commands create live components that call the Autocomplete API as the user types. Unlike dropdown and seed, they do not download data when you generate the files, so the generator works offline.

The generated component needs a Professional or Business API plan when it runs. Get an API key or compare plans.

# Type-ahead search field
csc generate autocomplete --target nextjs         # server API route + client component (recommended)
csc generate autocomplete --target react-browser  # calls the API directly from the browser

# Cascading country → state → city picker
csc generate location-picker --target nextjs
csc generate location-picker --target react-browser

--target is required: nextjs or react-browser. --output <dir> defaults to the current directory. Both generators always produce TypeScript (.tsx) — there’s no --typescript/--no-typescript toggle like dropdown has.

Choosing a target

nextjs (recommended)
react-browser

Generates a server Route Handler (app/api/csc-search/route.ts) that holds CSC_API_KEY server-side and proxies to the Autocomplete API — the key never reaches the browser. autocomplete and location-picker share this same route file when both are generated with nextjs.

No server — the generated component calls the API directly from the browser via the SDK, so the key ships in your JavaScript bundle.

Before using a react-browser-generated component, create an API key in your CSC dashboard restricted to your site’s origin(s). Never use an unrestricted/server key here — it would be visible in the browser and every outgoing request. The CLI prints this warning before writing any files, and it’s repeated in both the generated component’s header comment and the generated README, so it survives past the initial run.

What gets generated

Every run also writes an .env.example and a short README:

Command	Files
`autocomplete --target nextjs`	`app/api/csc-search/route.ts`, `components/LocationAutocomplete.tsx`, `.env.example`, `CSC-AUTOCOMPLETE-README.md`
`autocomplete --target react-browser`	`components/LocationAutocomplete.tsx`, `.env.example`, `CSC-AUTOCOMPLETE-README.md`
`location-picker --target nextjs`	`app/api/csc-search/route.ts`, `components/LocationPicker.tsx`, `.env.example`, `CSC-LOCATION-PICKER-README.md`
`location-picker --target react-browser`	`components/LocationPicker.tsx`, `.env.example`, `CSC-LOCATION-PICKER-README.md`

.env.example uses a placeholder, never a real key — CSC_API_KEY=YOUR_API_KEY_HERE for nextjs, VITE_CSC_API_KEY=YOUR_API_KEY_HERE for react-browser. For safety, the command stops before writing anything if one of these files already exists. It never replaces your existing files.

Behavior

Both components share the same search-field logic:

Debounced input (~250ms), 2-character minimum before searching
Cancels the previous in-flight request when new input arrives, so a slow response never overwrites a newer one
Five distinct states — loading, empty, plan-restricted, rate-limited, network-error — each with its own message, not one generic error
Full keyboard support: ArrowUp/ArrowDown to move, Enter to select the highlighted result, Escape or Tab to close
ARIA combobox pattern (role="combobox", aria-expanded, aria-controls, aria-autocomplete, aria-activedescendant) for screen readers

Selections carry stable identifiers (id, iso2, country_code, state_code, depending on entity) alongside the display label. Use the identifiers for anything programmatic — storing a selection, filtering a follow-up request, and so on. label is for display only.

location-picker cascades three fields — country, then state, then city. The state field is disabled until a country is picked; the city field is disabled until a state is picked. Selecting a country clears both state and city; selecting a state clears only city:

export interface LocationPickerValue {
  country: IAutocompleteResult | null;
  state: IAutocompleteResult | null;
  city: IAutocompleteResult | null;
}

autocomplete reports its selection via onSelect?: (result: IAutocompleteResult) => void. location-picker reports the whole cascade via onChange?: (value: LocationPickerValue) => void, called after every level changes.

Interactive Explorer

csc explore

Pick a country, then a state, then an action — view cities, view full details, or get the equivalent csc generate command to copy-paste.

Requires an interactive terminal (TTY). Use csc search for scripts.

Export

csc export           # Opens the online bulk export tool in your browser
csc export --json    # Returns the export URL as JSON, useful for scripts

API Documentation

Countries Endpoints

States Endpoints

Cities Endpoints

Regions Endpoints

Currency Endpoints

ISO Code Endpoints

Phone Endpoints

Timezone Endpoints

Search Endpoints

Meta Endpoints

SDKs & Examples

No-Code Integrations

Installation

Quick Start

Global Flags

Authentication

Search

Fuzzy, typo-tolerant search

`--fields` and `--sort`

Get Details

Usage & Billing

Plan-Gated Features

Code Generation

Live Location Components

Choosing a target

What gets generated

Behavior

Interactive Explorer

Export

Source

GitHub Repository

npm Package

​Installation

​Quick Start

​Global Flags

​Authentication

​Search

​Fuzzy, typo-tolerant search

​--fields and --sort

​Get Details

​Usage & Billing

​Plan-Gated Features

​Code Generation

​Live Location Components

​Choosing a target

​What gets generated

​Behavior

​Interactive Explorer

​Export

​Source

GitHub Repository

npm Package

Installation

Quick Start

Global Flags

Authentication

Search

Fuzzy, typo-tolerant search

`--fields` and `--sort`

Get Details

Usage & Billing

Plan-Gated Features

Code Generation

Live Location Components

Choosing a target

What gets generated

Behavior

Interactive Explorer

Export

Source