Skip to main content
The Shovels CLI is a single-binary command-line tool for querying U.S. building permit and contractor data. It outputs JSON to stdout, handles pagination automatically, and retries on rate limits. No runtime dependencies required.
CLI vs. API vs. Online: The CLI wraps the same Shovels REST API but handles auth headers, cursor pagination, rate-limit retries, and credit tracking for you. Use it from your terminal, in shell scripts, or from AI agents.

​
Install

Run the install script to download the latest release: 
curl -LsSf https://shovels.ai/install.sh | sh
The script detects your OS and architecture, downloads the correct binary from GitHub Releases, verifies the SHA256 checksum, and installs to ~/.shovels/bin.
Add ~/.shovels/bin to your PATH if the installer doesn’t do it automatically. For most shells, add export PATH="$HOME/.shovels/bin:$PATH" to your shell profile.
Verify the installation: 
shovels version

​
Configure Your API Key

You need a Shovels API key. If you don’t have one, create a free account to get a key with 250 free requests. There are two ways to provide your API key:

​
Option A: Environment variable

export SHOVELS_API_KEY=your-api-key

​
Option B: Config file (persistent)

shovels config set api-key your-api-key
This saves your key to ~/.config/shovels/config.yaml so you don’t need to export it every session. Confirm your config is set: 
shovels config show

​
Run Your First Query

Search for solar permits in Encinitas, CA (ZIP 92024) from 2024: 
shovels permits search \
  --geo-id 92024 \
  --permit-from 2024-01-01 \
  --permit-to 2024-12-31 \
  --tags solar \
  --limit 5
You’ll see JSON output like this: 
{
  "data": [
    {
      "id": "...",
      "description": "INSTALL ROOF MOUNTED SOLAR PV SYSTEM...",
      "status": "final",
      "tags": ["solar"],
      "address": {
        "street": "123 Main St",
        "city": "Encinitas",
        "state": "CA",
        "zip_code": "92024"
      }
    }
  ],
  "meta": {
    "count": 5,
    "has_more": true,
    "credits_used": 1,
    "credits_remaining": 249
  }
}
Every response includes a meta object with credit tracking so you always know your usage.

​
Understanding geo_id

Most search commands require a --geo-id flag. A geo_id can be:
  • A ZIP code — Use it directly (e.g., 92024)
  • A state — Use the 2-letter code (e.g., CA)
  • A city, county, or jurisdiction — Use the base64-encoded ID from a search
To find a geo_id for a city: 
shovels cities search -q "Miami Beach"

{
  "data": [
    {
      "geo_id": "Q2l0eXxGTHxNaWFtaSBCZWFjaA",
      "name": "Miami Beach, FL"
    }
  ]
}
Use that geo_id in subsequent searches: 
shovels permits search \
  --geo-id Q2l0eXxGTHxNaWFtaSBCZWFjaA \
  --permit-from 2024-01-01 \
  --permit-to 2024-12-31 \
  --tags roofing

​
Explore More Commands

The CLI covers permits, contractors, addresses, and geographic lookups: 
# Search contractors by location and specialty
shovels contractors search \
  --geo-id 78701 \
  --permit-from 2024-01-01 \
  --permit-to 2024-12-31 \
  --tags electrical

# Look up a specific contractor's permits
shovels contractors permits CONTRACTOR_ID

# Search for an address
shovels addresses search -q "1600 Pennsylvania Ave"

# Check your API credit usage
shovels usage

# List available permit tags
shovels tags list
Every command has built-in help: 
shovels permits search --help

​
Pipe It

The CLI outputs JSON to stdout, so it works with jq and other Unix tools: 
# Count solar permits in a ZIP code
shovels permits search --geo-id 92024 \
  --permit-from 2024-01-01 --permit-to 2024-12-31 \
  --tags solar --include-count --limit 1 \
  | jq '.meta.total_count.value'

# Export contractor names and permit counts to CSV
shovels contractors search --geo-id CA \
  --permit-from 2024-01-01 --permit-to 2024-12-31 \
  --tags solar --limit 100 \
  | jq -r '.data[] | [.name, .permit_count] | @csv' \
  > solar_contractors.csv

​
Next Steps