Skip to content

gbgplc/lqt

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

26 Commits
.github/ISSUE_TEMPLATE
.github/ISSUE_TEMPLATE
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
loqate.png
loqate.png
 
 

Repository files navigation

Loqate CLI

Loqate CLI

Verify addresses, emails, and phone numbers against Loqate's APIs.
Get confidence scores, policy-aware recommendations, and full auditability — in one command.
Real-time verification decisioning for agents that need to know whether contact data is good enough for the job.
Part of GBG Reach.

lqt verify  ·  lqt parse  ·  lqt mcp

Install

macOS

# Apple Silicon (M1/M2/M3/M4)
curl -sL https://github.com/gbgplc/lqt/releases/latest/download/lqt_darwin_arm64.tar.gz | tar xz
sudo mv lqt /usr/local/bin/

# Intel
curl -sL https://github.com/gbgplc/lqt/releases/latest/download/lqt_darwin_amd64.tar.gz | tar xz
sudo mv lqt /usr/local/bin/

Linux

# x86_64
curl -sL https://github.com/gbgplc/lqt/releases/latest/download/lqt_linux_amd64.tar.gz | tar xz
sudo mv lqt /usr/local/bin/

# ARM64
curl -sL https://github.com/gbgplc/lqt/releases/latest/download/lqt_linux_arm64.tar.gz | tar xz
sudo mv lqt /usr/local/bin/

Windows

  1. Download lqt_windows_amd64.zip from the latest release
  2. Extract lqt.exe
  3. Move it to a directory on your PATH, or run it directly

Verify Installation

lqt version

All Downloads

See Releases for all versions and platforms. Each release includes SHA-256 checksums.

Platform Archive
macOS (Apple Silicon) lqt_*_darwin_arm64.tar.gz
macOS (Intel) lqt_*_darwin_amd64.tar.gz
Linux (x86_64) lqt_*_linux_amd64.tar.gz
Linux (ARM64) lqt_*_linux_arm64.tar.gz
Windows (x86_64) lqt_*_windows_amd64.zip

Quick Start

API Keys

You need a Loqate API key for verification. Optionally, an Anthropic API key for the parse command.

macOS / Linux:

export LOQATE_API_KEY=your-key-here

# Optional — for lqt parse
export ANTHROPIC_API_KEY=your-key-here

Windows (PowerShell):

$env:LOQATE_API_KEY="your-key-here"

# Optional — for lqt parse
$env:ANTHROPIC_API_KEY="your-key-here"

Your First Verification

macOS / Linux:

# Verify an address
lqt verify --address "125 Summer Street, Boston, MA 02110, US"

# Verify address + email + phone with a policy
lqt verify -a "10 Downing St, London, GB" \
           -e "pm@gov.uk" \
           -p "+442071234567" \
           --policy shipping

# Parse and standardize without calling Loqate (uses Claude)
lqt parse --address "125 summer street boston ma 02110 us"

Windows (PowerShell):

# Verify an address
.\lqt.exe verify --address "125 Summer Street, Boston, MA 02110, US"

# Verify address + email + phone with a policy
.\lqt.exe verify -a "10 Downing St, London, GB" -e "pm@gov.uk" -p "+442071234567" --policy shipping

# Parse and standardize without calling Loqate (uses Claude)
.\lqt.exe parse --address "125 summer street boston ma 02110 us"

Commands

verify

Verify addresses, emails, and/or phone numbers against Loqate's APIs. Returns a confidence score and a policy-driven recommendation (accept, review, or reject).

lqt verify [flags]

Flags:

Flag Short Description
--address -a Full address to verify
--locality City/town
--admin-area State/province
--postcode Postal/ZIP code
--country -c ISO 2-letter country code
--email -e Email address to verify
--phone -p Phone number (E.164 format)
--key -k Loqate API key (overrides env)
--policy Policy name: strict, shipping, standard, permissive
--policy-file Path to custom policy JSON file
--batch -b CSV/TSV/pipe-delimited file path (or - for stdin)
--delimiter -d Batch delimiter: comma, tab, pipe (auto-detected if omitted)
--output -o Output format: json, jsonl, table
--summary -s Show batch summary statistics
--field Extra Loqate input field Key=Value (repeatable)
--option Loqate API option Key=Value (repeatable, dot notation for nesting)
--jsonl JSON Lines output (one object per line)
--no-color Disable color output
--verify-url Custom address verification endpoint URL (overrides LOQATE_VERIFY_URL env var)
--verify-key Custom address verification API key (overrides LOQATE_VERIFY_KEY env var). When set, --key is not required for address-only verification.
--verbose -v Show reasoning log

Examples:

# Simple address verification
lqt verify -a "1600 Amphitheatre Parkway, Mountain View, CA 94043, US"

# Multi-field verification with strict policy
lqt verify -a "221B Baker St, London, GB" \
           -e "sherlock@example.com" \
           -p "+442071234567" \
           --policy strict

# JSON output for piping to other tools
lqt verify -a "10 Downing St, London, GB" -o json | jq '.address.confidence'

# Extended input fields
lqt verify -a "125 Summer St" --field Organization="Acme Corp" --field Building="Suite 200"

# API options (dot notation for nesting)
lqt verify -a "125 Summer St, Boston, MA 02110, US" --option GeoCode=true

Full list of input fields and API options: Loqate International Batch Cleanse API

parse

Parse and standardize contact data using Claude (Haiku). Extracts address components, validates email syntax, and normalizes phone numbers with awareness of 250+ country-specific postal formats. No Loqate API calls — no credits spent.

lqt parse [flags]

Flags:

Flag Short Description
--address -a Full address to parse
--email -e Email address to validate
--phone -p Phone number to normalize
--country -c ISO 2-letter country code hint
--batch -b CSV/TSV/pipe-delimited file path (or - for stdin)
--delimiter -d Batch delimiter: comma, tab, pipe (auto-detected if omitted)
--output -o Output format: json, jsonl, table
--jsonl JSON Lines output
--no-color Disable color output
--anthropic-key Anthropic API key (overrides env)

Examples:

# Parse a messy address into structured components
lqt parse -a "125 summer street boston ma 02110 us"

# Parse address + validate email + normalize phone
lqt parse -a "10 downing st london" -e "test@mailinator.com" -p "02071234567"

# Batch parse from CSV
lqt parse --batch messy-data.csv --output json

policy

List, inspect, and validate verification policies.

lqt policy list                  # List all built-in policies
lqt policy show <name>           # Show full JSON for a policy
lqt policy validate <file>       # Validate a custom policy JSON file

mcp

Start an MCP (Model Context Protocol) server. Exposes LQT as tools for AI agents.

lqt mcp                    # Stdio transport (launched by clients)
lqt mcp --http :8080       # HTTP transport (deployed as a service)
lqt mcp --smoke-test       # Verify the server starts correctly and exit

Flags:

Flag Default Description
--http Listen address (e.g. :8080, 127.0.0.1:8080)
--rate-limit 10 Max requests/sec per IP (0 to disable)
--rate-burst 20 Max burst size for rate limiter
--smoke-test Self-test the MCP server (checks tools and prompts register) and exit
--disable-custom-endpoint Block per-request custom verify endpoint fields

Policies

Policies control what gets accepted, reviewed, or rejected. Every verification runs through a policy — there are no hardcoded thresholds.

Policy Addr Confidence Match Level Email Confidence Phone Required Use Case
strict 0.90 premise 0.85 yes KYC, fraud prevention, regulated
shipping 0.70 street 0.50 no Physical delivery, ecommerce
standard 0.55 street 0.45 no General verification (default)
permissive 0.30 locality 0.30 no Lead capture, early funnel

Custom Policies

Create a JSON file:

{
  "name": "my-custom-policy",
  "description": "Tuned for my use case",
  "address": {
    "min_confidence": 0.65,
    "min_match_level": "street",
    "reject_verification_status": ["U", "R"]
  },
  "email": {
    "min_confidence": 0.50,
    "allow_catch_all": true,
    "reject_disposable": true
  },
  "phone": {
    "min_confidence": 0.40,
    "required": false
  }
}
lqt policy validate my-policy.json    # Validate first
lqt verify -a "..." --policy-file my-policy.json

Batch Processing

Process files with address, email, and phone columns. Supports comma, tab, and pipe delimited input.

# CSV (auto-detected)
lqt verify --batch addresses.csv --policy shipping -o json > results.json

# Tab-delimited
lqt verify --batch addresses.tsv -o json

# Pipe-delimited
lqt verify --batch addresses.txt --delimiter pipe -o json

# From stdin
cat addresses.csv | lqt verify --batch - --policy standard

# With summary statistics
lqt verify --batch addresses.csv --summary

Windows (PowerShell):

.\lqt.exe verify --batch addresses.csv --policy shipping -o json > results.json
Get-Content addresses.csv | .\lqt.exe verify --batch - --policy standard

Delimiters

Auto-detected from the first line. Override explicitly with --delimiter:

Value Aliases Description
comma csv Comma-separated (default)
tab tsv Tab-separated
pipe Pipe-separated

Supported Columns

Use a single address column or structured fields — or both. All column names are case-insensitive. Every field from the Loqate International Batch Cleanse API is supported.

Address lines:

Field Accepted column names
Address (line 1) address, address1, street, address_line_1
Address lines 2-8 address2-address8, address_line_2-address_line_8
Delivery address deliveryaddress, delivery_address
Delivery lines 1-8 deliveryaddress1-deliveryaddress8, delivery_address_1-delivery_address_8

Geography:

Field Accepted column names
City city, locality, town
State/Province state, admin_area, province, region, administrative_area
County county, sub_admin_area, sub_administrative_area
Postal code postcode, postal_code, zip, zipcode
Country country, country_code

Street / building / premise:

Field Accepted column names
Street name thoroughfare, street_name
Building building, building_name
House number premise, house_number, building_number
Apartment/Suite sub_building, apartment, suite, unit, flat

Organization / postal:

Field Accepted column names
Organization organization, organisation, company, company_name
PO Box post_box, postbox, po_box, pobox

Contact / person:

Field Accepted column names
First name forename, first_name
Last name surname, last_name
Full name full_name, name

Non-address fields:

Field Accepted column names
Email email, email_address
Phone phone, telephone, phone_number, mobile

Example CSV

address,email,phone,country
"125 Summer St, Boston, MA 02110",user@example.com,+16175551234,US
"10 Downing St, London",pm@gov.uk,+442071234567,GB

MCP Integration

The lqt mcp command exposes LQT as tools for AI agents via the Model Context Protocol. Connecting the MCP server also provides a built-in usage guide prompt that teaches the AI how to use the tools effectively.

Claude Code / Cursor

Add to your project's .mcp.json:

{
  "mcpServers": {
    "loqate": {
      "command": "lqt",
      "args": ["mcp"],
      "env": {
        "LOQATE_API_KEY": "your-key-here",
        "ANTHROPIC_API_KEY": "your-key-here"
      }
    }
  }
}

Claude Desktop

Add to Claude Desktop's MCP settings:

{
  "mcpServers": {
    "lqt": {
      "command": "/usr/local/bin/lqt",
      "args": ["mcp"],
      "env": {
        "LOQATE_API_KEY": "your-key-here",
        "ANTHROPIC_API_KEY": "your-key-here"
      }
    }
  }
}

Remote HTTP

Deploy lqt mcp --http as a service:

{
  "mcpServers": {
    "loqate": {
      "url": "https://lqt.your-company.com/mcp"
    }
  }
}

In HTTP mode, clients can pass API keys per-request via the key field in tool arguments.

Hosted deployments may disable custom verify endpoints for security. If you receive a CUSTOM_ENDPOINT_DISABLED error, use the server's default endpoint — do not pass verify_url or verify_key in your tool arguments.

Available Tools

9 tools in stdio mode, 6 in HTTP mode (tools marked stdio mode only are not available over HTTP).

Tool Description
verify_address Verify an address with confidence score and recommendation
verify_email Verify an email with risk level and recommendation
verify_phone Verify a phone number with type/carrier and recommendation
verify_contact Verify all fields together with overall recommendation
parse_address Parse and standardize an address via Claude (stdio mode only)
list_policies List available decisioning policies
show_policy Show details for a specific policy
set_policy Register a custom policy (stdio mode only)
recommend_policy Get a recommended policy for your use case (stdio mode only)

Exit Codes

Designed for scripting and CI/CD:

Code Meaning
0 ACCEPT — all fields passed verification
1 REVIEW — manual review recommended
2 REJECT — verification failed
3 ERROR — missing key, invalid input, API failure

macOS / Linux:

lqt verify -a "125 Summer St, Boston, MA 02110, US" --policy shipping -o json
case $? in
  0) echo "Ship it" ;;
  1) echo "Queue for review" ;;
  2) echo "Bad address" ;;
  3) echo "Something broke" ;;
esac

Windows (PowerShell):

.\lqt.exe verify -a "125 Summer St, Boston, MA 02110, US" --policy shipping -o json
switch ($LASTEXITCODE) {
  0 { Write-Host "Ship it" }
  1 { Write-Host "Queue for review" }
  2 { Write-Host "Bad address" }
  3 { Write-Host "Something broke" }
}

API Keys

Loqate API Key (for verify)

macOS / Linux:

# Environment variable
export LOQATE_API_KEY=your-key-here

# Key file (add to .gitignore)
echo "your-key-here" > .loqate-key

# Per-command flag
lqt verify -a "..." --key your-key-here

Windows (PowerShell):

# Current session
$env:LOQATE_API_KEY="your-key-here"

# Persistent (survives restarts)
[System.Environment]::SetEnvironmentVariable("LOQATE_API_KEY", "your-key-here", "User")

# Per-command flag
.\lqt.exe verify -a "..." --key your-key-here

Anthropic API Key (for parse)

macOS / Linux:

export ANTHROPIC_API_KEY=your-key-here

Windows (PowerShell):

$env:ANTHROPIC_API_KEY="your-key-here"

Resolution order: flag > environment variable > key file

Custom Verify Endpoint (optional)

If you need to route address verification through a different endpoint (e.g., an on-premises or partner-hosted Loqate instance):

macOS / Linux:

# Environment variables
export LOQATE_VERIFY_URL=https://custom-verify.example.com/v1/batch
export LOQATE_VERIFY_KEY=your-custom-key

# Or use flags (override env vars)
lqt verify -a "..." --verify-url https://custom-verify.example.com/v1/batch --verify-key your-custom-key

Windows (PowerShell):

$env:LOQATE_VERIFY_URL="https://custom-verify.example.com/v1/batch"
$env:LOQATE_VERIFY_KEY="your-custom-key"

Resolution order: flag > environment variable > default Loqate endpoint

When --verify-key is set, the standard --key / LOQATE_API_KEY is not required for address-only verification. If you also verify email (-e) or phone (-p), the standard key is still needed for those.

These flags only affect address verification. Email and phone always use the standard Loqate endpoints.

In MCP mode, clients can pass verify_url and verify_key per-request in verify_address and verify_contact tool inputs.

Support

When reporting a bug, please include:

  • lqt version (lqt --version)
  • OS and architecture (e.g., macOS ARM64, Linux x86_64)
  • The command you ran (redact any API keys)
  • Expected vs actual behavior

Built by GBG.

About

Reach - GBG for Agents

Resources

Readme

License

View license
Activity
Custom properties

Stars

2 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases 11

lqt v0.6.2 Latest
May 7, 2026
+ 10 releases

Packages

 
 
 

Contributors