How Does CLI Authentication Work? - Shovels Documentation

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):

SHOVELS_API_KEY environment variable
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.

Option B: Config File (Recommended)

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:

Key	Description	Default
`api_key`	Your Shovels API key	(none)
`base_url`	API base URL override	`https://api.shovels.ai/v2`
`default_limit`	Default result limit	`50`

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:

Create a free Shovels account
Go to Profile Settings
Copy your API key from the API Key field

Free accounts include 250 requests to explore the platform.

How to access your API key — Find your key in the Shovels dashboard
CLI installation — Install the CLI binary
CLI error codes — Understanding exit codes and error types

​Authentication Priority

​Option A: Environment Variable

​Option B: Config File (Recommended)

​Verify Your Configuration

​Additional Config Options

​Authentication Errors

​Getting an API Key

​Related Articles

Authentication Priority

Option A: Environment Variable

Option B: Config File (Recommended)

Verify Your Configuration

Additional Config Options

Authentication Errors

Getting an API Key

Related Articles