bring-shopping-skill/SKILL.md

# Bring Shopping List Skill

Manage your Bring! Shopping List via CLI using the unofficial Bring! API.

TypeScript implementation with full type safety.

## Installation

```bash
npm install
chmod +x bring.ts
```

Or to build and run as JavaScript:

```bash
npm install
npm run build
node dist/bring.js
```

## Configuration

Set the following environment variables:

```bash
export BRING_EMAIL="your-email@example.com"
export BRING_PASSWORD="your-password"
export BRING_LIST_UUID="your-list-uuid"
```

### Option 1: Using a `.env` file (recommended)

Create a `.env` file in your skill directory:

```bash
BRING_EMAIL=your-email@example.com
BRING_PASSWORD=your-password
BRING_LIST_UUID=your-list-uuid
```

Then source it before running commands:
```bash
source .env
./bring list
```

Or use with AI agents that support .env files.

### Option 2: System environment variables

Add to your `~/.bashrc` or `~/.zshrc`:

```bash
export BRING_EMAIL="your-email@example.com"
export BRING_PASSWORD="your-password"
export BRING_LIST_UUID="your-list-uuid"
```

### Finding your List UUID

```javascript
const bringApi = require('bring-shopping');
const bring = new bringApi({
    mail: 'your@email.com',
    password: 'yourpassword'
});
await bring.login();
const lists = await bring.loadLists();
console.log(lists.lists);  // Shows all lists with their UUIDs
```

## Commands

```bash
./bring.ts add <item> [specification]     # Add item to shopping list
./bring.ts list                            # Show current items
./bring.ts remove <item>                   # Remove item (mark as purchased)
./bring.ts recent                          # Show recently purchased items
```

Or using ts-node directly:
```bash
ts-node bring.ts add <item>
```

## Examples

```bash
# Add items
./bring.ts add Apples
./bring.ts add Milk "1 Liter"
./bring.ts add "Coffee Beans" "Fair Trade"

# Show list
./bring.ts list

# Remove item (mark as bought)
./bring.ts remove Apples

# Show recently purchased items
./bring.ts recent
```

## Integration with AI Agents

### For nanoclaw/openclaw/Carson

Add to your `CLAUDE.md`:

```markdown
## Bring! Shopping List

**IMPORTANT - "Shopping list" always means Bring! App:**

When the user says "shopping list", they ALWAYS mean the Bring! Shopping List App:
- **NEVER** use a custom text file or other system
- **ALWAYS** use the Bring skill: `bring`

**Usage:**
```bash
bring add <item> [specification]     # Add item
bring list                            # Show list
bring remove <item>                   # Remove item
bring recent                          # Recently purchased
```

**Examples:**
- "Add milk to shopping list" → `bring add Milk`
- "What's on the shopping list?" → `bring list`
- "Remove apples from list" → `bring remove Apples`
```

### Setting environment variables for AI agents

Create a `.env` file in the skill directory with your credentials, then ensure your AI agent loads it before executing commands.

For nanoclaw/Carson, you can set the environment variables in the skill activation:

```bash
export BRING_EMAIL="your-email@example.com"
export BRING_PASSWORD="your-password"
export BRING_LIST_UUID="your-list-uuid"
```

## API Reference

This skill uses the unofficial `bring-shopping` npm package:
https://github.com/foxriver76/node-bring-api

## Security Notes

- **Never commit your `.env` file** - it's in `.gitignore` by default
- Environment variables keep credentials out of the code
- Each user/agent instance uses their own credentials

## Notes

- Items sync in real-time across all connected devices
- The specification parameter is optional (e.g., "Organic", "500g", etc.)
- Use quotes for items or specifications with spaces