Shovels | Shovels CLI: Construction Data Straight From Your Terminal

Shovels is SOC 2® Type II certified

Shovels meets enterprise security and compliance requirements. Our SOC 2 Type II certification reflects controls independently audited over a sustained period, not just a point-in-time snapshot.

AGENT-FIRST BY DESIGN

Permits, contractors, and addresses. No integration required.

01

Query everything with one open-source binary

No SDKs, no dependencies, no config files. Download one file and query permits, contractors, and addresses in seconds.

macOS, Linux, and Windows
Open source (MIT, Go) with checksum-verified installs
--limit all handles cursors, page sizes, and rate-limit retries

permits search

$ shovels permits search \
    --geo-id 33139 \          # Miami Beach, FL
    --permit-from 2024-01-01 \
    --permit-to 2024-12-31 \
    --tags roofing --include-count \
    --limit 1 | jq '.meta.total_count.value'
490

02

Plug directly into your AI agents

Claude Code, Codex, Cursor, or your own agents shell out to shovels and get structured data back. No MCP headaches, no context bloat, no credential juggling.

JSON to stdout, always; errors to stderr
--help text written for LLMs: specific, example-rich, jargon-free
Meaningful exit codes: 0 = success, 2 = auth error, 3 = rate limited

claude code

# Your AI agent runs this:
$ shovels permits search --help
...
# Reads the help, builds the query:
$ shovels permits search \
    --geo-id 94110 \          # San Francisco, CA
    --permit-from 2024-06-01 \
    --tags roofing \
    --property-type residential \
    --limit 20
# Parses the JSON, reasons about the results...

03

Pipe it, chain it, script it

JSON output composes with jq, cron, and everything else in your stack. Build workflows that would take weeks in a GUI.

Build a solar contractor CSV in one line
Monitor new permits in your market on a cron job
Resolve addresses to geo_ids mid-pipeline

build CSV

$ shovels contractors search --geo-id CA \
    --permit-from 2024-01-01 --permit-to 2024-12-31 \
    --tags solar --limit all \
    | jq -r '.data[] | [.name, .phone, .permit_count] | @csv' \
    > solar_contractors_ca.csv

04

Move faster with reliability built in

The CLI handles the operational plumbing, so jobs run unattended and your agent always knows the cost.

--limit all manages cursors, page sizes, and the 100K-record ceiling
Auto-retry on rate limits with backoff + jitter; respects Retry-After
Every response reports credits_used and credits_remaining

Pagination handled

--limit all manages cursors, page sizes, and the 100K-record ceiling

Auto-retry on rate limits

Backoff + jitter; respects Retry-After

Credit tracking

Every response reports credits_used and credits_remaining

See it across the whole dataset

count permits

$ shovels permits search --geo-id 33139 \
    --permit-from 2024-01-01 --permit-to 2024-12-31 \
    --tags roofing --include-count --limit 1 \
    | jq '.meta.total_count.value'
490

contractor permits

$ shovels contractors permits 03xTGkafsf \  # Cosmic Solar Inc.
    --limit all | jq '.data | length'
2056

export CSV

$ shovels contractors search --geo-id 78701 \  # Austin, TX
    --tags electrical --limit 100 \
    | jq -r '.data[] | [.name, .permit_count] | @csv'
"KENNETH TUMLINSON",554
"JOSEPH H MARTINEZ",85
...

resolve address

$ shovels addresses search \
    -q "1600 Pennsylvania Ave" \
    | jq '.data[0] | {name, geo_id}'
{
  "name": "1600 Pennsylvania Ave Nw, Washington, DC",
  "geo_id": "Kw5MGExoU6Y"
}

WHY NOT JUST CURL?

Because pagination shouldn't be your problem

✕ With curl — 15+ lines, manual pagination

cursor=""
while true; do
  resp=$(curl -s -H "X-API-Key: $KEY" \
    "https://api.shovels.ai/v2/permits/search\
?geo_id=92024&permit_from=2024-01-01\
&permit_to=2024-12-31&cursor=$cursor")
  echo "$resp" | jq '.items[]'
  cursor=$(echo "$resp" | jq -r '.next_cursor')
  [ "$cursor" = "null" ] && break
done

✓ With shovels — one command, all records

shovels permits search \
  --geo-id 92024 \
  --permit-from 2024-01-01 \
  --permit-to 2024-12-31 \
  --limit all

The CLI handles auth headers, cursor pagination, rate-limit retries, and credit tracking. Just say how many records you want.

Building an application?

The CLI is built on the Shovels API. For full REST access and integration into your product, use our API directly.

Learn more about our API

How it works

Up and running in seconds

01

Install

One line, checksum-verified, no runtime to install.

install

$ curl -LsSf https://shovels.ai/install.sh | sh
Installed shovels (sha256 verified)

02

Set your API key

Grab a key from your Shovels account dashboard.

auth

$ export SHOVELS_API_KEY=your-key

03

Run your first query

JSON results, instantly.

query

$ shovels permits search --geo-id 92024 \
    --permit-from 2025-01-01
{ "meta": { "count": 138 }, ... }

Frequently asked questions

What is the Shovels CLI?

The Shovels CLI is a command-line interface for the Shovels construction data API. It's a single open-source binary that lets you query building permits, contractors, and addresses directly from your terminal, returning clean JSON every time. It was designed from the ground up for AI agents, scripts, and data pipelines.

What platforms does the CLI support?

The CLI runs on macOS, Linux, and Windows. The install script downloads the binary from GitHub Releases and verifies its SHA256 checksum before anything touches your system, so you always know exactly what you're installing.

How do AI agents use the CLI?

AI agents like Claude Code, Codex, and Cursor simply shell out to the shovels command. They read the LLM-friendly --help text to construct the right command, parse the JSON that comes back on stdout, and branch on meaningful exit codes. There's no MCP server to configure and no credential juggling involved.

How does pricing work?

The CLI authenticates with your Shovels API key and draws from the same credit balance as the API. Every response includes credits_used and credits_remaining fields, so you—or your agent—always know exactly what a query cost and how much you have left.

Is the CLI open source?

Yes, the CLI is fully open source under the MIT license. It's written in Go using the Cobra framework, and the complete source code is available on GitHub—we welcome issues, feedback, and contributions.

How is the CLI different from the API?

They share the same data and the same credits, so the difference comes down to ergonomics. The CLI handles auth headers, cursor pagination, rate-limit retries, and credit tracking for you, which makes it ideal for terminal work and AI agents. If you're building Shovels data into an application, the API gives you direct REST access.

Get started in 10 seconds

Install the CLI, set your API key, and run your first query.

Get your API key

Construction data straight from your terminal