# CLI/API Documentation

This project includes a CLI for programmatic access to all CRUD operations without browser automation.

## Quick Start

```bash
# List all items
./scripts/crud.sh list

# Get specific item
./scripts/crud.sh get <id>

# Create new item
./scripts/crud.sh create '{"title":"New Item","status":"open"}'

# Update field
./scripts/crud.sh update <id> status done

# Delete item
./scripts/crud.sh delete <id>

# Attach file
./scripts/crud.sh attach <id> ./file.pdf
```

## Setup

Copy `.env.example` to `.env.local` and add your API key:

```bash
cp .env.example .env.local
```

Edit `.env.local`:
```bash
API_URL=http://localhost:3000/api
API_KEY=your-service-role-key-here
```

## Available Commands

| Command | Description | Example |
|---------|-------------|---------|
| `list [filters]` | List all items | `./scripts/crud.sh list status=open` |
| `get <id>` | Get single item | `./scripts/crud.sh get abc-123` |
| `create <json>` | Create new item | `./scripts/crud.sh create '{"title":"X"}'` |
| `update <id> <field> <value>` | Update field | `./scripts/crud.sh update abc-123 title "New"` |
| `delete <id>` | Delete item | `./scripts/crud.sh delete abc-123` |
| `attach <id> <file>` | Attach file | `./scripts/crud.sh attach abc-123 file.pdf` |

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/items` | List items (with query params) |
| GET | `/api/items/:id` | Get single item |
| POST | `/api/items` | Create new item |
| PATCH | `/api/items/:id` | Update item fields |
| DELETE | `/api/items/:id` | Delete item |
| POST | `/api/items/:id/attachments` | Attach file (base64) |

## File Attachments

Files are attached as base64-encoded data URLs:

```bash
# Attach a file
./scripts/crud.sh attach task-123 ./document.pdf

# The file is stored in the item's attachments array
# and can be viewed via the UI or API
```

## Verification

Always verify operations worked:

```bash
# After create
./scripts/crud.sh get <new-id>

# After attach
./scripts/crud.sh get <id> | jq '.attachments | length'

# After update
./scripts/crud.sh get <id> | jq '.status'
```

## Authentication

The CLI uses a service role key stored in `.env.local`. This key has full access to the API.

**Never commit `.env.local` to git.**

## Troubleshooting

### "API error: 401"
- Check your API_KEY in `.env.local`
- Ensure the key is valid in your auth system

### "curl: (7) Failed to connect"
- Ensure the dev server is running: `npm run dev`
- Check the API_URL in `.env.local`

### "jq: command not found"
- Install jq: `brew install jq`

## Project Structure

```
project/
├── api/
│   └── items/
│       ├── route.ts          # List, Create
│       └── [id]/
│           ├── route.ts      # Get, Update, Delete
│           └── attachments/
│               └── route.ts  # File attachments
├── lib/
│   └── api-client.ts         # TypeScript API client
└── scripts/
    └── crud.sh               # This CLI
```

## Adding New Operations

1. Add API endpoint in `api/`
2. Add client method in `lib/api-client.ts`
3. Add CLI command in `scripts/crud.sh`
4. Update this README