What Commands Are Available in the CLI?

The CLI organizes commands into groups: permits, contractors, addresses, geographic lookups, tags, usage, and config. Every command outputs JSON to stdout and supports --help for detailed usage.

Command Reference

permits

Search and retrieve building permit data.

Subcommand	Description	Key Flags
`permits search`	Search permits by location, date, tags, and filters	`--geo-id` (required), `--permit-from` (required), `--permit-to` (required)
`permits get`	Retrieve 1-50 permits by ID	Positional IDs

Example: Search permits

shovels permits search \
  --geo-id 92024 \
  --permit-from 2024-01-01 \
  --permit-to 2024-12-31 \
  --tags solar \
  --property-type residential \
  --limit 50

contractors

Search contractors and access their permits, employees, and metrics.

Subcommand	Description	Key Flags
`contractors search`	Search contractors by location and filters	`--geo-id` (required)
`contractors get`	Retrieve 1-50 contractors by ID	Positional IDs
`contractors permits`	List permits filed by a contractor	Contractor ID (positional)
`contractors employees`	List employees of a contractor	Contractor ID (positional)
`contractors metrics`	Monthly performance metrics	`--metric-from`, `--metric-to`, `--property-type`, `--tag` (all required)

Example: Find electrical contractors in Austin

shovels contractors search \
  --geo-id 78701 \
  --permit-from 2024-01-01 \
  --permit-to 2024-12-31 \
  --tags electrical \
  --min-permits 10

Contractor search supports state, county, city, jurisdiction, and ZIP code geo_ids, but not address-level geo_ids. Use permits search for address-level queries.

addresses

Search for addresses to resolve geo_ids.

shovels addresses search -q "1600 Pennsylvania Ave"

Returns matching addresses with their geo_id, formatted name, and coordinates.

cities, counties, jurisdictions

Resolve geographic names to geo_ids for use in search commands.

shovels cities search -q "Miami Beach"
shovels counties search -q "Los Angeles"
shovels jurisdictions search -q "San Francisco"

usage

Check your API credit usage and limits.

shovels usage

config

Manage persistent CLI settings.

shovels config set api-key your-key  # Save API key
shovels config show                   # Display current config

version

Print CLI version, git commit, and build date.

shovels version

These flags are available on permits search and contractors search:

Tag Filters

--tags solar                 # Include permits tagged "solar"
--tags solar,roofing         # Include solar OR roofing
--tags -electrical           # Exclude electrical permits

Tags support a - prefix for exclusion. Mix includes and excludes as needed.

Property Filters

--property-type residential
--min-market-value 500000
--min-building-area 2000
--min-lot-size 5000
--min-story-count 2
--min-unit-count 4

Permit Filters

--status final               # final, active, in_review, inactive
--min-job-value 100000
--min-fees 500
--min-approval-duration 30   # days
--min-construction-duration 90
--min-inspection-pr 80       # pass rate percentage
--has-contractor             # only permits with a linked contractor
-q "solar panel"             # text search in permit description

Contractor Filters (contractor search only)

--contractor-name "Smith"
--contractor-license "ABC123"
--classification general,electrical
--min-permits 50
--min-job-value 1000000

Global Flags

These flags apply to all commands:

Flag	Description	Default
`--limit`	Max records to return (1-100000 or `all`)	`50`
`--max-records`	Cap when using `--limit all`	`10000`
`--include-count`	Include total result count in response	`false`
`--base-url`	Override API endpoint	Config or default
`--no-retry`	Disable automatic retry on rate limits	`false`
`--timeout`	Per-request timeout (Go duration format)	`30s`

Getting Help

Every command supports --help:

shovels --help                  # Top-level help
shovels permits --help          # Permits group help
shovels permits search --help   # Detailed search flags and examples

CLI quickstart guide — First query in under a minute
Output format and pagination — Understanding JSON responses
Scripting and AI agents — Composing CLI commands into workflows

Knowledge Base

What Commands Are Available in the CLI?

Command Reference

permits

contractors

addresses

cities, counties, jurisdictions

tags

usage

config

version

Common Search Filters

Tag Filters

Property Filters

Permit Filters

Contractor Filters (contractor search only)

Global Flags

Getting Help

​Command Reference

​permits

​contractors

​addresses

​cities, counties, jurisdictions

​tags

​usage

​config

​version

​Common Search Filters

​Tag Filters

​Property Filters

​Permit Filters

​Contractor Filters (contractor search only)

​Global Flags

​Getting Help

​Related Articles

Command Reference

permits

contractors

addresses

cities, counties, jurisdictions

tags

usage

config

version

Common Search Filters

Tag Filters

Property Filters

Permit Filters

Contractor Filters (contractor search only)

Global Flags

Getting Help

Related Articles