---
name: bring-shopping
description: "Manage Bring! shopping lists — view lists, add/remove items, check off purchases. Use this skill whenever the user mentions shopping lists, groceries, Bring, adding items to buy, checking what's on the list, or anything related to grocery/shopping list management. Also trigger when the user wants to mark items as bought, remove things from a list, or add multiple items at once."
---

# Bring! Shopping List Skill

Manage shopping lists on the Bring! app directly from Claude Code.

## First-Run Setup

Before running any command, check if the environment is ready. Run this preflight check:

```bash
test -f .venv/bin/python && .venv/bin/python -c "import bring_api" 2>/dev/null && test -f .env && echo "READY" || echo "SETUP_NEEDED"
```

If `SETUP_NEEDED`, run through these steps:

1. **Python venv** — the skill uses a virtual environment (an isolated Python install in `.venv/`) to avoid polluting the system. Create it if `.venv/` doesn't exist:
   ```bash
   python3 -m venv .venv
   ```
   This requires Python 3.11+. On macOS with Homebrew, that's typically `/opt/homebrew/bin/python3`.

2. **Install dependencies** — the `bring-api` library and `python-dotenv` need to be installed into the venv:
   ```bash
   .venv/bin/pip install -r requirements.txt
   ```

3. **Credentials** — the script reads `BRING_EMAIL` and `BRING_PASSWORD` from a `.env` file. If `.env` doesn't exist, ask the user for their Bring! account email and password, then create it:
   ```bash
   cp .env.example .env
   ```
   Then edit `.env` with the user's credentials. These are the same credentials they use to log into the Bring! app.

## How to Use

Run the CLI script via the venv Python. The script handles authentication, list resolution (by name or UUID), and outputs human-readable text.

### Commands

**List all shopping lists:**
```bash
.venv/bin/python scripts/bring_cli.py lists
```

**Show items on a list** (accepts list name or UUID, case-insensitive, partial match):
```bash
.venv/bin/python scripts/bring_cli.py items "Groceries"
```

**Add a single item** (with optional specification like quantity or variant):
```bash
.venv/bin/python scripts/bring_cli.py add "Groceries" "Milk" --spec "2L organic"
```

**Add multiple items at once:**
```bash
.venv/bin/python scripts/bring_cli.py add-batch "Groceries" "Milk" "Eggs" "Bread" "Butter"
```

**Remove an item:**
```bash
.venv/bin/python scripts/bring_cli.py remove "Groceries" "Milk"
```

**Mark an item as bought:**
```bash
.venv/bin/python scripts/bring_cli.py complete "Groceries" "Milk"
```

### List Name Resolution

The script resolves list names flexibly:
- Exact UUID match
- Case-insensitive name match (e.g., "groceries" matches "Groceries")
- Partial name match if unambiguous (e.g., "groc" matches "Groceries")
- If ambiguous, it lists the matches so the user can clarify

## Common Workflows

### "What's on my shopping list?"
1. Run `lists` to see all lists
2. Run `items <list_name>` for the relevant list
3. Report the items, separating "to buy" from "recently bought"

### "Add these items to my list"
When the user provides multiple items, use `add-batch` for efficiency. If any items have specifications (quantities, brands, variants), use individual `add` commands with `--spec` for those.

Example: "Add milk (2L), eggs, bread, and organic butter to Groceries"
```bash
.venv/bin/python scripts/bring_cli.py add "Groceries" "Milk" --spec "2L"
.venv/bin/python scripts/bring_cli.py add "Groceries" "Butter" --spec "organic"
.venv/bin/python scripts/bring_cli.py add-batch "Groceries" "Eggs" "Bread"
```

### "I bought the milk"
Use `complete` to mark items as purchased — this moves them to the "recently bought" section in the Bring app rather than deleting them.

### "Remove X from the list"
Use `remove` to fully delete an item from the list (not just mark as bought).

## Error Handling

- **Auth errors**: Prompt the user to check their `.env` credentials. Suggest they verify by logging into the Bring! app with the same email/password.
- **List not found**: Show available lists so the user can pick the right one.
- **Network errors**: These are usually transient — retry once. If it persists, it may be a Bring! service issue.

## Advanced Usage

For operations not covered by the CLI (notifications, recipes, activity feed, user management), consult `references/api-reference.md` and write a custom Python snippet using the `bring-api` library directly.