Geocodio CLI

The Geocodio CLI gives you direct access to the Geocodio API from your terminal. Instead of writing code or uploading spreadsheets through the dashboard, you can geocode addresses, look up coordinates, calculate driving distances, and process large CSV files with a single command.

It’s built for developers, data engineers, and analysts who want to work with location data without leaving the command line.

The CLI ships with a skill that teaches AI coding assistants how to use Geocodio. It works with Claude Code, Cursor, Amp, Codex, and anything else that supports skills.

The CLI is open source and available on GitHub.

Installation

Run the install script to download the latest release for your platform:

curl -fsSL https://raw.githubusercontent.com/geocodio/geocodio-cli/main/install.sh | sh

Or install with Go:

go install github.com/geocodio/geocodio-cli/cmd/geocodio@latest

Pre-built binaries for Linux, macOS, and Windows are also available on the GitHub releases page.

Setup

All commands require a Geocodio API key. Generate one for free from the Geocodio Dashboard — no credit card required.

Set your API key as an environment variable:

export GEOCODIO_API_KEY=your-api-key

Add this line to your shell profile (~/.bashrc, ~/.zshrc, etc.) so it persists across sessions. You can also pass the key directly with --api-key on any command.

What the CLI Can Do

The Geocodio CLI supports all major Geocodio features:

• Geocode addresses to get coordinates, formatted addresses, and data appends

• Reverse geocode coordinates to get addresses

• Calculate distances between locations (driving or straight-line)

• Build distance matrices between multiple origins and destinations

• Run async distance jobs for large-scale calculations

• Process spreadsheets (CSV and Excel) in batch

All of the data append fields available through the API work with the CLI, including Census data, Congressional districts, timezones, school districts, and more.

Geocode an Address

geocodio geocode "1600 Pennsylvania Ave NW, Washington DC"

Add data appends with the --fields flag:

geocodio geocode "30 Rockefeller Plaza, New York NY" --fields timezone,cd

Use the --country flag to disambiguate between US and Canadian addresses:

geocodio geocode "Ottawa, Ontario" --country CA

Batch Geocode from a File

Create a text file with one address per line, then:

geocodio geocode --batch addresses.txt

The batch endpoint accepts up to 10,000 addresses per request.

Reverse Geocode Coordinates

geocodio reverse "38.8976,-77.0365"

Batch reverse geocoding works the same way — create a file with one lat,lng pair per line:

geocodio reverse --batch coordinates.txt

Get only data appends for coordinates without reverse geocoding an address:

geocodio reverse "38.8976,-77.0365" --skip-geocoding --fields timezone,cd

Calculate Distances

From one origin to one or more destinations:

geocodio distance "Washington DC" "New York" "Boston" "Philadelphia"

Use --mode driving for driving distance and duration, or --mode straightline for straight-line distance. Use --units km for kilometers.

Distance Matrix

Calculate distances between multiple origins and multiple destinations:

geocodio distance-matrix --origins origins.txt --destinations destinations.txt

Async Distance Jobs

For large distance calculations, create a background job and check on it later:

geocodio distance-jobs create --name "Warehouse routing" --origins origins.txt --destinations destinations.txt --watch

The --watch flag shows a progress bar until the job completes. List, check status, download results, or delete jobs with the distance-jobs subcommands.

Process Spreadsheets

Upload a CSV or Excel file for batch geocoding:

geocodio lists upload data.csv --direction forward --format "{{A}}, {{B}}, {{C}}"

The --format flag maps your columns to address components. {{A}} is the first column, {{B}} is the second, and so on.

Watch progress, then download results:

geocodio lists status 12345 --watch
geocodio lists download 12345 --output geocoded.csv

Output Formats

The CLI supports three output formats:

• Human-readable (default): Colored, formatted output for your terminal

• JSON (--json): Full API response for scripting and piping to tools like jq

• Agent (--agent): Clean markdown tables for AI coding assistants and LLMs

Use the CLI in Your Workflows

The Geocodio CLI fits naturally into automated pipelines — ETL jobs, cron jobs, CI/CD builds, and shell scripts. Chain commands together with pipes and file redirects, or schedule regular batch processing of new addresses.

AI Coding Assistant Integration

The Geocodio CLI includes a skill file that teaches AI coding assistants how to use it. Once installed, assistants like Claude Code, Cursor, Amp, and Codex can geocode addresses, calculate distances, and process spreadsheets on your behalf.

npx skills add geocodio/geocodio-cli

The skill activates automatically when you ask your assistant to work with addresses or location data.

Migrating from v1.x

If you used the previous version of the CLI, here are the key changes in v2.0:

• Spreadsheet commands are now grouped under geocodio lists

• The --direction flag (forward or reverse) is now required when uploading spreadsheets

• --follow has been renamed to --watch

• --apikey has been renamed to --api-key

• New commands: geocode, reverse, distance, distance-matrix, and distance-jobs

# Old (v1.x)
$ ./geocodio create sample_list.csv "{{A}} {{B}} {{C}} {{D}}" --fields=cd
$ ./geocodio status 12345
$ ./geocodio download 12345 > output.csv

# New (v2.x)
$ geocodio lists upload sample_list.csv --direction forward --format "{{A}} {{B}}, {{C}} {{D}}" --fields cd
$ geocodio lists status 12345
$ geocodio lists download 12345 --output output.csv

See the full migration guide on GitHub.

Troubleshooting

"API key required": Set GEOCODIO_API_KEY as an environment variable or pass --api-key on the command.

"batch size exceeds maximum of 10,000": Split your file into smaller chunks. The batch endpoints accept up to 10,000 items per request.

"invalid coordinate format": Reverse geocoding expects lat,lng format. Latitude comes first.

Debugging: Use --debug to see full HTTP request and response details.

Open Source

The Geocodio CLI is open source under the MIT license. Contributions, issues, and feature requests are welcome on GitHub.