What Commands Are Available in the CLI?

A complete overview of Shovels CLI commands for searching permits, contractors, addresses, and geographic data from your terminal.

The CLI organizes commands into groups: permits, properties, contractors, decisions, addresses, geographic lookups, tags, schema, 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

properties

Search properties with their permit history rolled up onto each record. Added in v0.8.0.

Subcommand	Description	Key Flags
properties search	Search properties by geographic scope and/or legal owner	--geo-id or --legal-owner (at least one)
properties get	Retrieve 1-50 properties by address ID	Positional IDs

Example: Properties with no solar permit

shovels properties search \
  --geo-id 92024 \
  --permit-tags "-solar" \
  --property-type residential \
  --limit 10

Properties are in beta. Unlike permits search, there is no --permit-to flag and jurisdiction geo_ids are rejected. See Querying properties from the CLI.

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.

decisions

Search municipal zoning and land-use decisions. Added in v0.7.0.

Subcommand	Description	Key Flags
decisions search	Search decisions by location, date range, and category	--decision-from, --decision-to (both required)
decisions get	Retrieve decisions by ID	Positional IDs

shovels decisions search --geo-id CA \
  --decision-from 2024-01-01 --decision-to 2024-12-31 \
  --category Rezoning --asset-class Residential

addresses

Search for addresses to resolve geo_ids, plus resident and metrics lookups.

shovels addresses search -q "1600 Pennsylvania Ave"

Returns matching addresses with their geo_id, formatted name, and coordinates. Also supports addresses residents and addresses metrics current|monthly.

cities, counties, jurisdictions, states, zipcodes

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"
shovels states search -q "CA"
shovels zipcodes search -q "941"

states search matches on the 2-letter abbreviation (CA), not the full state name. zipcodes search matches on ZIP prefix and spans states, so filter the results if you need one state.

Each group also exposes a coverage subcommand reporting which permit fields are reliably populated for that area. The geo_id is a positional argument here, and both dates are required. Cities, counties, and jurisdictions additionally support metrics current and metrics monthly.

shovels cities coverage Q2l0eXxGTHxNaWFtaSBCZWFjaA \
  --coverage-from 2024-01-01 --coverage-to 2024-12-31

schema

Print the annotated JSON response schema for any data command — offline, with no API call and no API key required.

shovels schema                      # List all available command paths
shovels schema properties search    # Full schema for one command

Each schema gives response_fields (type, description, unit, range, enum), meta_fields for commands whose meta carries more than the standard keys, a jq-ready field_index, and filters mapping each CLI flag to its type. Nested objects appear as dotted paths like trust.coverage_tier.

This is the cheapest way for an AI agent to learn a command’s output shape before spending credits. Any data command also accepts --schema to print its own: shovels properties search --schema.

tags

List available permit tags (work type classifications).

shovels tags list

Returns tags like solar, hvac, roofing, electrical, pool_spa, new_dwelling, kitchen_remodel, and more. Use these values with the --tags flag in search commands.

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

Common Search Filters

These flags are available on permits search and contractors search. properties search names and scopes several of them differently — see Querying properties from the CLI:

Difference	permits / contractors	properties
Tag flag	--tags, repeatable or comma-separated	--permit-tags, same shape. Multiple positive tags match at address grain, not on one shared permit
Unknown tag	Returns zero rows	Rejected with a 422 naming the tag
Date range	--permit-from and --permit-to, both required	--permit-from only; no upper bound exists
Scope	--geo-id required	--geo-id or --legal-owner
Attribute prefix	--min-market-value	--property-min-market-value
Jurisdiction geo_ids	Accepted by permits search	Rejected

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
--dry-run	Print the resolved HTTP request as JSON without calling the API or spending credits	false
--schema	Print this command’s annotated response schema (offline, no auth)	false

--dry-run and --schema both short-circuit before any network call, so they’re free. Use --dry-run to confirm how your flags map to query parameters, and --schema to learn the response shape.

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

Related Articles

• CLI quickstart guide — First query in under a minute
• Querying properties from the CLI — The properties command group
• CLI absence searches and trust fields — Finding properties with no permit on record
• Output format and pagination — Understanding JSON responses
• Scripting and AI agents — Composing CLI commands into workflows