Command-line interface for the countrycodes ISO 3166-1 lookup library.

Installation

Install as a command-line tool with uv:

uv tool install countrycodes-cli

Or install into the active Python environment:

python -m pip install countrycodes-cli

Requires Python 3.11 or newer. The library dependency is installed automatically.

Usage

Look up a country by code or name:

countrycodes lookup US
countrycodes lookup "United Kingdom"
countrycodes lookup +1
countrycodes lookup Untied --limit 3

Lookups are displayed as a table by default. Choose JSON output or list all countries:

countrycodes lookup GBR --format json
countrycodes list
countrycodes list --format json

The --limit option controls the maximum number of matches shown for a lookup (default: 5), including countries sharing a dial code. When the text output is truncated, the CLI notes that it is showing only the top matches. JSON lookup output is a single record for one match or an array for multiple matches. The default list is rendered as a table sorted by alpha-2 code, with a row number, and JSON list output is an unnumbered array. Text tables show a country's common name when available, falling back to its source name. Country records include the international dial code when available. Fuzzy text lookup tables include a combined word-level and full displayed-name similarity percentage for each result. Fuzzy matching uses transposition-aware edit-distance scoring. Country name data is retained as provided by its source; inclusion does not imply endorsement of any political position.

See all options with:

countrycodes --help

License

The CLI code is licensed under BSD 3-Clause. The separately distributed countrycodes library includes ISO registry data under LGPL-2.1-or-later and continent assignments from GeoNames under CC BY 4.0; installing the CLI installs that library as a dependency.