test-repo/CLI_README_TEMPLATE.md

CLI/API Documentation

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

Quick Start

# 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:

cp .env.example .env.local

Edit .env.local:

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:

# 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:

# 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