Appendices on madtea

API Compatibility

Mon, 01 Jan 0001 00:00:00 +0000

What this answers: “will this madtea feature work against my server?” — madtea features × the Gitea and Forgejo REST APIs — plus the maintainer view: tracking drift between the two platforms. The client-vs-client question (“which CLI covers what”) is a different axis and lives in COMPARISON.md.

madtea targets Gitea API v1 as its single API surface (ADR 0017); Forgejo is supported through the Gitea-compatible API it maintains. Where Forgejo diverges, madtea detects the platform and surfaces the gap as a typed, explained error — see How madtea handles divergence.

CLI Comparison

Mon, 01 Jan 0001 00:00:00 +0000

What this answers: which client covers what, for someone — human or agent — picking a forge CLI. It compares madtea against the four relevant clients, feature by feature:

gh — the GitHub CLI, the Microsoft-backed benchmark everyone knows. gh cannot talk to a Forgejo/Gitea server at all; its column reads “gh offers this on its own forge” — the capability bar to clear, not an alternative client. gh is also madtea’s naming yardstick: ADR 0016 makes gh-then-tea vocabulary a recorded, test-enforced rule (internal/parity/), so gh muscle-memory lands on the right verb.
glab — GitLab’s official CLI. Like gh, it cannot talk to a Forgejo/Gitea server; its column reads “glab offers this on its own forge (GitLab)”. GitLab concepts are mapped to their forge equivalents (MR ≈ PR, pipeline ≈ Actions run, group ≈ org).
tea — Gitea’s official CLI. Same backend as madtea.
fj — forgejo-cli, the Forgejo-native community CLI. Same backend as madtea.

Server-side compatibility is a different question. “Will this feature work against my Forgejo/Gitea server?” lives in COMPAT.md, which owns the platform axis. A row below carries at most a terse pointer there.

Security Policy

Mon, 01 Jan 0001 00:00:00 +0000

Reporting a vulnerability

If you find a security issue in madtea — credential leak, authentication bypass, code execution via crafted input, etc. — please report it privately rather than opening a public issue.

How to report: open a confidential issue on the project tracker (Codeberg’s “confidential issues” feature). Include a brief description, reproduction steps if you have them, and the madtea version (madtea --version).

Pre-release: madtea’s public Codeberg repo is not live yet. Until it is, report security issues privately by email to security@sixfold.space instead of via the confidential-issue tracker.

Token Permissions

Mon, 01 Jan 0001 00:00:00 +0000

What scopes to enable on your Forgejo/Gitea personal-access token. For how madtea stores that token and the credential-safety guarantees, see the credential safety guide. For how to report a security issue, see the security policy.

What to enable

madtea works against three rough token tiers. Pick the smallest one that covers what you’ll do.

Read-only (browse, list, search):

read:repository
read:issue
read:user

Standard (typical day-to-day: create PRs/issues, merge, comment, mark notifications read):

read:repository + write:repository
read:issue + write:issue
read:notification + write:notification
read:user

Full (org administration, packages, webhooks, branch protection, admin domains):

Why madtea

Mon, 01 Jan 0001 00:00:00 +0000

Other forge CLIs wrap the API. madtea wraps the workflow — and it is built on the assumption that an AI agent with shell access may be driving it.

This is the punch list: what madtea does that gh, tea, and raw API calls don’t. Every claim below is verified against the source tree; where a comparison against gh or tea is asserted, it is backed by the CLI comparison.

1. It has an issue graph. Nobody else does.

gh and tea have zero dependency commands — this whole category is a capability gap, not an ergonomics win.