Matt Bruce
8f4f979c85
New specialized agents: - ios-dev: iOS/Swift/SwiftUI development - web-dev: Next.js/React/web development - research: Research and analysis tasks Each agent has: - Own agent.json config with specialized system prompt - Auto-loaded relevant skills - Domain-specific best practices and rules - Proper model configuration Also added: - SPECIALIZED_AGENTS.md documentation - CLI_README_TEMPLATE.md for reference
132 lines
3.1 KiB
Markdown
132 lines
3.1 KiB
Markdown
# 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
|