repertory-api/ain/README.md

# ain templates

[ain](https://github.com/jonaslu/ain) is a terminal HTTP client. These templates cover every API endpoint.

## Setup

### 1. Install ain

```bash
brew install ain        # macOS
# or: go install github.com/jonaslu/ain/cmd/ain@latest
```

ain requires `curl`, `wget`, or `httpie` to be available — `curl` is already on macOS.

### 2. Configure connection details

ain picks up variables from the project root `.env` automatically when run from the project root. `make local` will have already created that file for you. The relevant variables are:

```bash
API_KEY=dev-secret-key-change-me
REPERTORY_HOST=http://localhost:5000
```

### 3. Run a template

Every template is run by combining `base.ain` with a specific template file. `base.ain` provides the host and auth header; the specific file adds the path, method, and body.

```bash
ain ain/base.ain ain/health.ain
```

---

## Templates

### Health

```bash
ain ain/base.ain ain/health.ain
```

### Tunes

```bash
# List all tunes
ain ain/base.ain ain/tunes/list.ain

# List with filters (edit the [Query] section in the file first)
ain ain/base.ain ain/tunes/list-filtered.ain

# Get a single tune
ain ain/base.ain ain/tunes/get.ain --vars ID=1

# Create a tune (edit the [Body] in the file first)
ain ain/base.ain ain/tunes/create.ain

# Update core fields
ain ain/base.ain ain/tunes/update.ain --vars ID=1

# Delete a tune
ain ain/base.ain ain/tunes/delete.ain --vars ID=1
```

### Instruments (banjo / fiddle)

```bash
# Create or replace a banjo entry
ain ain/base.ain ain/instruments/upsert-banjo.ain --vars ID=1

# Create or replace a fiddle entry
ain ain/base.ain ain/instruments/upsert-fiddle.ain --vars ID=1

# Patch individual banjo fields
ain ain/base.ain ain/instruments/patch-banjo.ain --vars ID=1

# Patch individual fiddle fields
ain ain/base.ain ain/instruments/patch-fiddle.ain --vars ID=1

# Delete banjo entry
ain ain/base.ain ain/instruments/delete-banjo.ain --vars ID=1

# Delete fiddle entry
ain ain/base.ain ain/instruments/delete-fiddle.ain --vars ID=1
```

### Notes

```bash
# List notes for a tune
ain ain/base.ain ain/notes/list.ain --vars ID=1

# Add a note
ain ain/base.ain ain/notes/create.ain --vars ID=1

# Update a note
ain ain/base.ain ain/notes/update.ain --vars ID=1 NOTE_ID=2

# Delete a note
ain ain/base.ain ain/notes/delete.ain --vars ID=1 NOTE_ID=2
```

### References

```bash
# List references for a tune
ain ain/base.ain ain/references/list.ain --vars ID=1

# Add a reference (with optional musicians in the body)
ain ain/base.ain ain/references/create.ain --vars ID=1

# Update a reference
ain ain/base.ain ain/references/update.ain --vars ID=1 REF_ID=2

# Delete a reference
ain ain/base.ain ain/references/delete.ain --vars ID=1 REF_ID=2

# Add a musician to a reference
ain ain/base.ain ain/references/add-musician.ain --vars ID=1 REF_ID=2

# Remove a musician from a reference
ain ain/base.ain ain/references/delete-musician.ain --vars ID=1 REF_ID=2 NAME="Tony Rice"
```

---

## Tips

- **Print without sending**: `ain -p ain/base.ain ain/tunes/list.ain` — shows the curl command ain would run, useful for debugging
- **Pipe output**: `ain ain/base.ain ain/tunes/list.ain | jq .` — pipe straight into jq or anything else
- **Multiple filters**: edit `ain/tunes/list-filtered.ain` and remove the query params you don't need before running
- **Musician names with spaces**: quote the whole `--vars` value: `--vars NAME="Doc Watson"`