Skip to main content
The CLI uses the same API key as the Shovels REST API. You can provide it through an environment variable or a persistent config file.

​
Authentication Priority

The CLI checks for your API key in this order (first match wins):
  1. SHOVELS_API_KEY environment variable
  2. Config file at ~/.config/shovels/config.yaml

​
Option A: Environment Variable

Set your API key for the current session: 
export SHOVELS_API_KEY=your-api-key
This is useful for CI/CD pipelines, Docker containers, or temporary sessions. Save your API key persistently: 
shovels config set api-key your-api-key
This creates or updates ~/.config/shovels/config.yaml: 
api_key: your-api-key
The config file location follows the XDG Base Directory specification, so it respects $XDG_CONFIG_HOME if set.

​
Verify Your Configuration

shovels config show
This displays your resolved configuration with the API key partially masked for security.

​
Additional Config Options

The config file supports these settings:
KeyDescriptionDefault
api_keyYour Shovels API key(none)
base_urlAPI base URL overridehttps://api.shovels.ai/v2
default_limitDefault result limit50
Set any option with the config set command: 
shovels config set base-url https://api.shovels.ai/v2

​
Authentication Errors

If your API key is missing or invalid, the CLI exits with code 2 and prints a JSON error to stderr: 
{
  "error": "API key is required. Set SHOVELS_API_KEY or run: shovels config set api-key YOUR_KEY",
  "code": 2,
  "error_type": "auth_error"
}
Some commands don’t require authentication: version, config show, and usage. Geographic search commands (cities search, counties search, etc.) and tags list are also credit-free but require a valid API key.

​
Getting an API Key

If you don’t have an API key yet:
  1. Create a free Shovels account
  2. Go to Profile Settings
  3. Copy your API key from the API Key field
Free accounts include 250 requests to explore the platform.