Building a Contractor Pipeline with the CLI

The Shovels CLI makes it easy to go from a broad market search to a targeted contractor list in a few commands. In this tutorial, we’ll find the top solar contractors in a California ZIP code, inspect their permit history, and export the results to CSV. This is a common workflow for sales teams, market researchers, and AI agents building lead lists.

Step-by-Step Recipe

Set Up the CLI

If you haven’t already, install the CLI and configure your API key:

curl -LsSf https://shovels.ai/install.sh | sh
shovels config set api-key YOUR_API_KEY

Verify it works:

shovels version

For detailed setup instructions, see the CLI Quickstart Guide.

Find Your Target Market

If you know your ZIP code, you can use it directly as a --geo-id. If you need to find a city or county geo_id, search for it:

shovels cities search -q "Encinitas"

{
  "data": [
    {
      "geo_id": "Q2l0eXxDQXxFbmNpbml0YXM",
      "name": "Encinitas, CA"
    }
  ]
}

For this tutorial, we’ll use ZIP code 92024 (Encinitas, CA).

Search for Contractors

Search for solar contractors active in 2024:

shovels contractors search \
  --geo-id 92024 \
  --permit-from 2024-01-01 \
  --permit-to 2024-12-31 \
  --tags solar \
  --limit 20

This returns up to 20 contractors with their names, contact info, permit counts, and ratings.

Add --include-count with --limit 1 to see the total number of matching contractors before fetching the full list.

Inspect a Contractor's Permits

Pick a contractor ID from the results and view their permit history:

shovels contractors permits CONTRACTOR_ID --limit 10

This returns individual permits with descriptions, dates, job values, and addresses.To see monthly performance metrics:

shovels contractors metrics CONTRACTOR_ID \
  --metric-from 2024-01-01 \
  --metric-to 2024-12-31 \
  --property-type residential \
  --tag solar

Export to CSV

Use jq to transform the JSON output into CSV:

shovels contractors search \
  --geo-id 92024 \
  --permit-from 2024-01-01 \
  --permit-to 2024-12-31 \
  --tags solar \
  --limit all \
  | jq -r '["Name","Phone","Email","Permits","Avg Job Value"],
           (.data[] | [.name, .primary_phone, .primary_email,
            .permit_count, .avg_job_value]) | @csv' \
  > solar_contractors_encinitas.csv

This creates a CSV with headers, ready for a spreadsheet or CRM import.

Expand to a Broader Area (Optional)

Scale up by searching at the state level:

shovels contractors search \
  --geo-id CA \
  --permit-from 2024-01-01 \
  --permit-to 2024-12-31 \
  --tags solar \
  --min-permits 10 \
  --limit all \
  | jq -r '["Name","Phone","Permits"],
           (.data[] | [.name, .primary_phone, .permit_count]) | @csv' \
  > solar_contractors_ca.csv

Use --min-permits to filter for contractors with a track record.

Adjusting Your Search

If your results are too broad or too narrow, here are some adjustments:

Too many results: Add --min-permits, --min-job-value, or narrow the --geo-id to a smaller area
Too few results: Expand the date range, use a broader geo_id (county or state), or remove tag filters
Wrong specialty: Use shovels tags list to see all available tags and pick the right one
Need specific contractors: Add --contractor-name or --contractor-license to filter by known details

Additional Help

If you run into issues, check the CLI error codes guide or reach out to support@shovels.ai. Happy Digging!

Shovels Online

Shovels API

Shovels CLI

Tutorials

Troubleshooting

Platform Reference

Shovels Foundations

Building a Contractor Pipeline with the CLI

Step-by-Step Recipe

Set Up the CLI

Find Your Target Market

Search for Contractors

Inspect a Contractor's Permits

Export to CSV

Expand to a Broader Area (Optional)

Adjusting Your Search

Additional Help

​ Step-by-Step Recipe

Set Up the CLI

Find Your Target Market

Search for Contractors

Inspect a Contractor's Permits

Export to CSV

Expand to a Broader Area (Optional)

​Adjusting Your Search

​Additional Help

Step-by-Step Recipe

Adjusting Your Search

Additional Help