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

# CLI

> Command-line interface for quick lookups, scripting, and terminal workflows.

## Installation

```bash theme={null}
pip install colacloud-cli
```

Requires Python 3.9+.

## Configuration

Set your API key via environment variable:

```bash theme={null}
export COLACLOUD_API_KEY=cola_xxxx
```

Or configure it persistently:

```bash theme={null}
cola config set-key
```

## Commands

### Search COLAs

```bash theme={null}
# Quick search
cola search "bourbon"

# With filters (use 'cola colas list' for full filtering)
cola colas list --brand "Maker's Mark" --product-type "distilled spirits" --limit 20

# Filter by origin
cola colas list --origin kentucky --product-type "distilled spirits"

# Filter by package and derived category
cola colas list --category Beer --derived-subcategory "Beer > Ale" \
  --container-type can --volume-unit "fluid ounces" --volume-min 12 --volume-max 16

# Date range
cola colas list --date-from 2024-01-01 --date-to 2024-06-30
```

### Get COLA Details

```bash theme={null}
# Fetch a specific COLA by TTB ID
cola colas get 24001001000001

# Output as JSON
cola colas get 24001001000001 --json
```

### Barcode Lookup

```bash theme={null}
# Find COLAs by UPC/EAN
cola barcode 012345678901
```

### Check Usage

```bash theme={null}
# View your API usage stats
cola usage
```

## Output Formats

```bash theme={null}
# Human-readable (default)
cola search "wine" --limit 5

# JSON output for scripting
cola search "wine" --limit 5 --json

# Pipe to jq for processing
cola search "wine" --json | jq '.data[].brand_name'
```

## Links

* [GitHub](https://github.com/cola-cloud-us/colacloud-cli)
* [PyPI](https://pypi.org/project/colacloud-cli/)