# bring-shopping

Adopt this skill: https://proskills.md/skills/other/masone-bring-shopping-skill

Page: https://proskills.md/skills/other/masone-bring-shopping-skill
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 4491
upstream: https://github.com/masone/bring-shopping-skill/blob/HEAD/SKILL.md

````text
---
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.
````

## File: README.md
upstream: https://github.com/masone/bring-shopping-skill/blob/HEAD/README.md

````text
# Bring! Shopping List Skill for Claude Code

A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skill for managing [Bring!](https://www.getbring.com/) shopping lists — view lists, add/remove items, and check off purchases, all from your terminal.

## Requirements

- Python 3.11+
- A [Bring!](https://www.getbring.com/) account

## Setup

1. Clone this repo (or add it as a skill directory):
   ```bash
   git clone https://github.com/YOUR_USERNAME/bring-shopping-skill.git
   ```

2. Create a virtual environment and install dependencies:
   ```bash
   cd bring-shopping-skill
   python3 -m venv .venv
   .venv/bin/pip install -r requirements.txt
   ```

3. Configure your Bring! credentials:
   ```bash
   cp .env.example .env
   # Edit .env with your Bring! account email and password
   ```

4. Install as a Claude Code skill:
   ```bash
   # Project-level (current project only)
   mkdir -p .claude/skills
   ln -s "$(pwd)" .claude/skills/bring

   # OR user-level (all projects)
   mkdir -p ~/.claude/skills
   ln -s "$(pwd)" ~/.claude/skills/bring
   ```

## Usage

Once installed, Claude will automatically use this skill when you mention shopping lists, groceries, or Bring. You can also invoke it explicitly with `/bring`.

Examples:
- "What's on my shopping list?"
- "Add milk, eggs, and bread to my Groceries list"
- "Remove the bananas"
- "I bought the milk and eggs"
- "Add 2L of oat milk and organic butter to my list"

## CLI Reference

The underlying CLI can also be used directly:

```bash
.venv/bin/python scripts/bring_cli.py lists                              # List all shopping lists
.venv/bin/python scripts/bring_cli.py items "Groceries"                  # Show items on a list
.venv/bin/python scripts/bring_cli.py add "Groceries" "Milk" --spec "2L" # Add an item with details
.venv/bin/python scripts/bring_cli.py add-batch "Groceries" Milk Eggs    # Add multiple items
.venv/bin/python scripts/bring_cli.py remove "Groceries" "Milk"          # Remove an item
.venv/bin/python scripts/bring_cli.py complete "Groceries" "Milk"        # Mark as bought
```

List names are resolved flexibly — case-insensitive, partial matching supported.

## Credits

This skill is built on top of the [bring-api](https://github.com/miaucl/bring-api) Python library by [miaucl](https://github.com/miaucl) and contributors. The library provides an unofficial async Python client for the Bring! shopping list API.

- **bring-api**: MIT License, (c) miaucl — https://github.com/miaucl/bring-api
- **Bring!** is a product of [Bring! Labs AG](https://www.getbring.com/). This skill is not affiliated with or endorsed by Bring! Labs AG.

## License

MIT — see [LICENSE](LICENSE).
````
