Shovels CLI Quickstart Guide

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.

Choose your environment to get started:

Terminal / Local
Claude Cowork

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

Verify the Setup

Check that the CLI can connect to the API and authenticate:

shovels usage

You should see a JSON response with your credit usage, confirming the CLI is installed and configured correctly.

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

CLI installation options — Platform-specific details and version pinning
CLI commands overview — Full list of commands and flags
Output format and pagination — Understanding responses and --limit all
Scripting and AI agents — Composing the CLI into workflows
CLI error codes — Exit codes and troubleshooting

Overview

You can set up the Shovels CLI inside Claude Cowork and query building permit data directly from your workspace — no command-line experience required. Just add one file to your Cowork folder and Claude handles the rest.

What You’ll Need

Download the Shovels CLI binary — Go to github.com/ShovelsAI/shovels-cli/releases/latest and download the linux_arm64 release (the file ending in .tar.gz). Save it to your Cowork folder.You’ll also need your Shovels API key handy. If you don’t have one, create a free account to get a key with 250 free requests.

Only the linux_arm64 binary works in Cowork. The Cowork environment runs on Linux (arm64 architecture), so make sure you download that specific version from the releases page — not the macOS, Windows, or amd64 versions.

Getting Started

Once the .tar.gz file is in your Cowork folder, just ask Claude:

“Set up the Shovels CLI for me.”

Claude will:

Find and extract the binary — Claude locates the archive in your folder, unpacks it, and installs the shovels binary to ~/.local/bin.
Ask for your API key — Claude will prompt you for your Shovels API key. Just paste it into the chat. Claude uses it to configure the CLI by running shovels config set api-key.
Verify everything works — Claude runs shovels usage to confirm the CLI can connect and authenticate. You should see a response with your credit usage, meaning you’re all set.

That’s it — you’re ready to start querying Shovels data. Try asking Claude something like “How many permits were pulled in Austin last month?” and it will use the CLI to find the answer.

Troubleshooting

If something doesn’t go as expected, tell Claude what happened and it can usually fix it. Common issues include:

CLI not found after install — Claude re-adds ~/.local/bin to the session’s PATH.
Permission error on the binary — Claude runs chmod +x to fix it.
401 Unauthorized error — Claude re-runs the config step with your API key.
No .tar.gz file found — Make sure you downloaded the linux_arm64 release and placed it in your Cowork folder.

Shovels Online

Shovels API

Shovels CLI

Tutorials

Troubleshooting

Platform Reference

Shovels Foundations

Install

Configure Your API Key

Option A: Environment variable

Option B: Config file (persistent)

Verify the Setup

Run Your First Query

Understanding geo_id

Explore More Commands

Pipe It

Next Steps

Overview

What You’ll Need

Getting Started

Troubleshooting

​Install

​Configure Your API Key

​Option A: Environment variable

​Option B: Config file (persistent)

​Verify the Setup

​Run Your First Query

​Understanding geo_id

​Explore More Commands

​Pipe It

​Next Steps

​Overview

​What You’ll Need

​Getting Started

​Troubleshooting

Install

Configure Your API Key

Option A: Environment variable

Option B: Config file (persistent)

Verify the Setup

Run Your First Query

Understanding geo_id

Explore More Commands

Pipe It

Next Steps

Overview

What You’ll Need

Getting Started

Troubleshooting