liq

liq is a Go CLI for LocationIQ geocoding and routing APIs.

It is designed around machine-readable output by default, so it works well in shells, scripts, and LLM skills.

Disclaimer

Contains AI-generated code.

Current Scope

Implemented commands:

• search
• reverse
• autocomplete
• timezone
• balance
• directions
• matrix
• nearest
• match
• optimize
• config init
• config show
• version

Install

Build the binary in the repo root:

go build ./cmd/liq

Install it into your local Go bin directory:

go install ./cmd/liq

If $(go env GOPATH)/bin is already on your PATH, you can then run:

liq version

If you do not want to install it globally, you can run the repo-local binary directly after building:

./liq version

Build

Rebuild the repo-local binary at any time with:

go build ./cmd/liq

Test

Run the full test suite with:

go test ./...

If your environment has a read-only default Go build cache, use a writable cache directory:

GOCACHE=/tmp/liq-gocache go test ./...

Skills

This repo includes a bundled skill at:

skills/liq

The skill uses the local CLI and is designed to return JSON by default through the wrapper script:

./skills/liq/scripts/run-liq.sh --output json balance
./skills/liq/scripts/run-liq.sh --output json search "Empire State Building"
./skills/liq/scripts/run-liq.sh --output json directions --coord -73.985428,40.748817 --coord -73.9934,40.7505

If you want your local tooling to discover the skill outside this repo, install it into your skills directory by copying or linking it:

mkdir -p ~/.codex/skills
ln -s "$(pwd)/skills/liq" ~/.codex/skills/liq

If you prefer copying instead of linking:

mkdir -p ~/.codex/skills
cp -R skills/liq ~/.codex/skills/liq

After that, the skill can be invoked as $liq.

For Anthropic Claude workflows, use the same local skill folder or call the wrapper directly:

./skills/liq/scripts/run-liq.sh --output json <command> ...

Configuration

Configuration precedence:

1. Command-line flags
2. Environment variables
3. Config file
4. Defaults

Environment variables:

• LIQ_API_KEY
• LIQ_REGION
• LIQ_OUTPUT
• LIQ_TIMEOUT
• LIQ_CONFIG_FILE

Generate a starter config:

liq config init

Show the effective config:

liq config show

Default config path:

~/.config/liq/config.toml

Global Flags

• --api-key <value>
• --region <us1|eu1>
• --output <json|pretty|table|raw>
• --timeout <duration>
• --base-url <url>
• --no-color

Examples

Forward geocoding:

liq search "Empire State Building"
liq search --street "350 5th Ave" --city "New York" --country "US"
liq --output table search "Chennai Central"

Reverse geocoding:

liq reverse --lat 40.7484 --lon -73.9857

Autocomplete:

liq autocomplete "Empire" --limit 5

Timezone:

liq timezone --lat 37.774929 --lon -122.419416 --timestamp 1718355600

Routing:

liq directions --coord -73.985428,40.748817 --coord -73.9934,40.7505
liq matrix --coord -0.127627,51.503355 --coord -0.087199,51.509562 --coord -0.076134,51.508037
liq nearest --coord -73.985428,40.748817
liq match --coord -73.985428,40.748817 --coord -73.99,40.75 --timestamp 1718355600 --timestamp 1718355660
liq optimize --coord -0.127627,51.503355 --coord -0.087199,51.509562 --coord -0.076134,51.508037

Output Modes

• json: compact JSON
• pretty: indented JSON
• table: concise human-readable summary
• raw: raw response body

Notes

• Geocoding commands use lat and lon flags where appropriate.
• Routing commands require coordinates in lon,lat order.
• The CLI validates common swapped-coordinate mistakes before making the request.