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

# Shovels CLI Quickstart Guide

> Install the Shovels CLI, configure your API key, and run your first permit search in under a minute.

**The Shovels CLI is a single-binary command-line tool for querying U.S. building permit and contractor data.** It outputs JSON to stdout, handles pagination automatically, and retries on rate limits. No runtime dependencies required.

<Info>
  **CLI vs. API vs. Online:** The CLI wraps the same Shovels REST API but handles auth headers, cursor pagination, rate-limit retries, and credit tracking for you. Use it from your terminal, in shell scripts, or from AI agents.
</Info>

Choose your environment to get started:

<Tabs>
  <Tab title="Terminal / Local">
    ## Install

    Run the install script to download the latest release:

    ```bash theme={null}
    curl -LsSf https://shovels.ai/install.sh | sh
    ```

    The script detects your OS and architecture, downloads the correct binary from GitHub Releases, verifies the SHA256 checksum, and installs to `~/.shovels/bin`.

    <Tip>
      Add `~/.shovels/bin` to your `PATH` if the installer doesn't do it automatically. For most shells, add `export PATH="$HOME/.shovels/bin:$PATH"` to your shell profile.
    </Tip>

    Verify the installation:

    ```bash theme={null}
    shovels version
    ```

    ## Configure Your API Key

    You need a Shovels API key. If you don't have one, [create a free account](https://app.shovels.ai/create-account/) to get a key with 250 free requests.

    There are two ways to provide your API key:

    ### Option A: Environment variable

    ```bash theme={null}
    export SHOVELS_API_KEY=your-api-key
    ```

    ### Option B: Config file (persistent)

    ```bash theme={null}
    shovels config set api-key your-api-key
    ```

    This saves your key to `~/.config/shovels/config.yaml` so you don't need to export it every session.

    Confirm your config is set:

    ```bash theme={null}
    shovels config show
    ```

    ## Verify the Setup

    Check that the CLI can connect to the API and authenticate:

    ```bash theme={null}
    shovels usage
    ```

    You should see a JSON response with your credit usage, confirming the CLI is installed and configured correctly.

    ## Run Your First Query

    Search for solar permits in Encinitas, CA (ZIP 92024) from 2024:

    ```bash theme={null}
    shovels permits search \
      --geo-id 92024 \
      --permit-from 2024-01-01 \
      --permit-to 2024-12-31 \
      --tags solar \
      --limit 5
    ```

    You'll see JSON output like this:

    ```json theme={null}
    {
      "data": [
        {
          "id": "...",
          "description": "INSTALL ROOF MOUNTED SOLAR PV SYSTEM...",
          "status": "final",
          "tags": ["solar"],
          "address": {
            "street": "123 Main St",
            "city": "Encinitas",
            "state": "CA",
            "zip_code": "92024"
          }
        }
      ],
      "meta": {
        "count": 5,
        "has_more": true,
        "credits_used": 1,
        "credits_remaining": 249
      }
    }
    ```

    Every response includes a `meta` object with credit tracking so you always know your usage.

    ## Understanding geo\_id

    Most search commands require a `--geo-id` flag. A geo\_id can be:

    * **A ZIP code** — Use it directly (e.g., `92024`)
    * **A state** — Use the 2-letter code (e.g., `CA`)
    * **A city, county, or jurisdiction** — Use the base64-encoded ID from a search

    To find a geo\_id for a city:

    ```bash theme={null}
    shovels cities search -q "Miami Beach"
    ```

    ```json theme={null}
    {
      "data": [
        {
          "geo_id": "Q2l0eXxGTHxNaWFtaSBCZWFjaA",
          "name": "Miami Beach, FL"
        }
      ]
    }
    ```

    Use that `geo_id` in subsequent searches:

    ```bash theme={null}
    shovels permits search \
      --geo-id Q2l0eXxGTHxNaWFtaSBCZWFjaA \
      --permit-from 2024-01-01 \
      --permit-to 2024-12-31 \
      --tags roofing
    ```

    ## Explore More Commands

    The CLI covers permits, contractors, addresses, and geographic lookups:

    ```bash theme={null}
    # Search contractors by location and specialty
    shovels contractors search \
      --geo-id 78701 \
      --permit-from 2024-01-01 \
      --permit-to 2024-12-31 \
      --tags electrical

    # Look up a specific contractor's permits
    shovels contractors permits CONTRACTOR_ID

    # Search for an address
    shovels addresses search -q "1600 Pennsylvania Ave"

    # Check your API credit usage
    shovels usage

    # List available permit tags
    shovels tags list
    ```

    Every command has built-in help:

    ```bash theme={null}
    shovels permits search --help
    ```

    ## Pipe It

    The CLI outputs JSON to stdout, so it works with `jq` and other Unix tools:

    ```bash theme={null}
    # Count solar permits in a ZIP code
    shovels permits search --geo-id 92024 \
      --permit-from 2024-01-01 --permit-to 2024-12-31 \
      --tags solar --include-count --limit 1 \
      | jq '.meta.total_count.value'

    # Export contractor names and permit counts to CSV
    shovels contractors search --geo-id CA \
      --permit-from 2024-01-01 --permit-to 2024-12-31 \
      --tags solar --limit 100 \
      | jq -r '.data[] | [.name, .permit_count] | @csv' \
      > solar_contractors.csv
    ```

    ## Next Steps

    * [CLI installation options](/docs/knowledge-base/cli/installation) — Platform-specific details and version pinning
    * [CLI commands overview](/docs/knowledge-base/cli/commands-overview) — Full list of commands and flags
    * [Output format and pagination](/docs/knowledge-base/cli/output-and-pagination) — Understanding responses and `--limit all`
    * [Scripting and AI agents](/docs/knowledge-base/cli/scripting-and-agents) — Composing the CLI into workflows
    * [CLI error codes](/docs/knowledge-base/cli/error-codes) — Exit codes and troubleshooting
  </Tab>

  <Tab title="Claude Cowork">
    ## Overview

    You can set up the Shovels CLI inside [Claude Cowork](https://claude.ai/cowork) and query building permit data directly from your workspace — no command-line experience required. Just add one file to your Cowork folder and Claude handles the rest.

    ## What You'll Need

    **Download the Shovels CLI binary** — Go to [github.com/ShovelsAI/shovels-cli/releases/latest](https://github.com/ShovelsAI/shovels-cli/releases/latest) and download the `linux_arm64` release (the file ending in `.tar.gz`). Save it to your Cowork folder.

    You'll also need your Shovels API key handy. If you don't have one, [create a free account](https://app.shovels.ai/create-account/) to get a key with 250 free requests.

    <Warning>
      Only the `linux_arm64` binary works in Cowork. The Cowork environment runs on Linux (arm64 architecture), so make sure you download that specific version from the releases page — not the macOS, Windows, or amd64 versions.
    </Warning>

    ## Getting Started

    Once the `.tar.gz` file is in your Cowork folder, just ask Claude:

    > *"Set up the Shovels CLI for me."*

    Claude will:

    1. **Find and extract the binary** — Claude locates the archive in your folder, unpacks it, and installs the `shovels` binary to `~/.local/bin`.
    2. **Ask for your API key** — Claude will prompt you for your Shovels API key. Just paste it into the chat. Claude uses it to configure the CLI by running `shovels config set api-key`.
    3. **Verify everything works** — Claude runs `shovels usage` to confirm the CLI can connect and authenticate. You should see a response with your credit usage, meaning you're all set.

    That's it — you're ready to start querying Shovels data. Try asking Claude something like *"How many permits were pulled in Austin last month?"* and it will use the CLI to find the answer.

    ## Troubleshooting

    If something doesn't go as expected, tell Claude what happened and it can usually fix it. Common issues include:

    * **CLI not found after install** — Claude re-adds `~/.local/bin` to the session's `PATH`.
    * **Permission error on the binary** — Claude runs `chmod +x` to fix it.
    * **401 Unauthorized error** — Claude re-runs the config step with your API key.
    * **No `.tar.gz` file found** — Make sure you downloaded the `linux_arm64` release and placed it in your Cowork folder.
  </Tab>
</Tabs>