> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shovels.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
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**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
shovels properties search \
  --geo-id 92024 \
  --permit-tags "-solar" \
  --property-type residential \
  --limit 10
```

<Info>
  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](/docs/knowledge-base/cli/properties).
</Info>

### 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**

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
shovels contractors search \
  --geo-id 78701 \
  --permit-from 2024-01-01 \
  --permit-to 2024-12-31 \
  --tags electrical \
  --min-permits 10
```

<Info>
  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.
</Info>

### 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                                     |

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
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.

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
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.

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
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"
```

<Info>
  `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.
</Info>

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`.

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
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**.

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
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`.

<Tip>
  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`.
</Tip>

### tags

List available permit tags (work type classifications).

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
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.

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
shovels usage
```

### config

Manage persistent CLI settings.

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
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.

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
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](/docs/knowledge-base/cli/properties):

| 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

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
--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

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
--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

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
--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)

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
--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`           |

<Tip>
  `--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.
</Tip>

## Getting Help

Every command supports `--help`:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
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](/docs/shovels-cli-quickstart) — First query in under a minute
* [Querying properties from the CLI](/docs/knowledge-base/cli/properties) — The `properties` command group
* [CLI absence searches and trust fields](/docs/knowledge-base/cli/absence-and-trust) — Finding properties with no permit on record
* [Output format and pagination](/docs/knowledge-base/cli/output-and-pagination) — Understanding JSON responses
* [Scripting and AI agents](/docs/knowledge-base/cli/scripting-and-agents) — Composing CLI commands into workflows