---
name: forgejo
description: Manage Forgejo issues, comments, and labels from an agent session. Use when creating issues, posting comments, closing issues, assigning work, or querying the Forgejo API for trentuna/vigilio projects.
---

# Forgejo CLI

Forgejo is on PATH (`~/.local/bin/forgejo` → `~/projects/commons/bin/forgejo.sh`).
Requires `FORGEJO_TOKEN` in environment. Instance: `http://localhost:3001`

## Common Operations

```bash
# Issues
forgejo issues [owner/repo]                    # list open issues
forgejo issue <owner/repo> <number>            # read issue with comments
forgejo create <owner/repo> "title" "body"     # create issue
cat body.md | forgejo create <owner/repo> "title"  # multiline body via stdin
forgejo close <owner/repo> <number>            # close issue
forgejo assign <owner/repo> <num> <user>       # assign issue
forgejo flag <owner/repo> <number>             # mark priority 🔥

# Comments
forgejo comment <owner/repo> <num> "body"      # post inline comment
cat body.md | forgejo comment <owner/repo> <num>  # multiline body via stdin

# Labels & Milestones
forgejo labels <owner/repo>                    # list labels with IDs
forgejo label-create <repo> <name> <#hex> [desc]  # create label
forgejo milestone-list <owner/repo>            # list milestones
forgejo milestone-create <repo> <title> [desc] # create milestone

# Focus view (wake protocol)
forgejo focus                                  # prioritized issue view
```

## Direct API

For anything the CLI doesn't cover:

```bash
curl -s -H "Authorization: token ${FORGEJO_TOKEN}" \
  http://localhost:3001/api/v1/repos/<owner>/<repo>/issues/<num>/dependencies

# Close an issue via API (when CLI close has issues)
curl -s -X PATCH \
  -H "Authorization: token ${FORGEJO_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"state": "closed"}' \
  "http://localhost:3001/api/v1/repos/<owner>/<repo>/issues/<num>" \
  | python3 -c "import sys,json; i=json.load(sys.stdin); print(f'#{i[\"number\"]}: {i[\"state\"]}')"

# List issues with a specific label
curl -s -H "Authorization: token ${FORGEJO_TOKEN}" \
  'http://localhost:3001/api/v1/repos/<owner>/<repo>/issues?labels=<label>&state=open&type=issues' \
  | python3 -c "import sys,json; issues=json.load(sys.stdin); [print(f'#{i[\"number\"]}: {i[\"title\"]}') for i in issues]"
```

## Known Repositories

| Repo | Purpose |
|------|---------|
| `vigilio/vault` | Vigilio's knowledge vault |
| `trentuna/a-team` | A-Team operational tasks |
| `trentuna/commons` | Shared infrastructure |
| `a-team/playground` | Agent experiments, branding |
| `ludo/homa` | Ludo's home project |

## Notes

- Always verify state changes by re-fetching after API calls — don't trust response alone
- Issue numbers in commit messages don't auto-close issues (no GitHub-style integration)
- Drop label on `vigilio/vault` is used for inbox items from Ludo