Guides on madtea

Configuration & first run

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

How to point madtea at your forge, where it stores credentials, and how the override precedence resolves. This guide assumes the madtea binary is already installed - see install.md if not. For what scopes to enable on the token, see PERMISSIONS.md. For how madtea stores the token and the credential-safety guarantees, see credential-safety.md.

First run

madtea auth login walks you through entering your forge URL and pasting an API token, then stores the token securely in your OS keychain (or pass, or systemd-creds on a headless server, when no keychain is available). Run it once globally and every repo on that forge is covered:

Editor & MCP client setup

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

The same madtea binary serves an MCP endpoint over stdio (madtea serve). The consolidated MCP tools (one per resource noun, action-dispatched — issues, prs, repos, branches, releases, actions, …) are identical across every client; only the config file’s location and format differ.

Every client launches the server the same way — running the madtea binary with the single argument serve and talking to it over stdio. The blocks below differ only in how each client spells that out.

Raw API passthrough

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

madtea api makes a raw call against the forge’s REST API and prints the response. It is the last-resort escape hatch: prefer a first-class command (issue list, pr create, labels set, …) every time, because those carry the safety, confirmation, and output handling that a raw call does not. Reach for api only when no built-in command covers the endpoint you need — and when that happens, it’s worth filing an issue so the gap gets a real command.

secret-exec — run a command with your token, never on disk

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

madtea secret-exec runs a child command with your stored Forgejo/Gitea token injected into its environment. The token is fetched from wherever madtea already keeps it — your OS keychain, pass, the MADTEA_TOKEN environment variable, or git config — and placed into the child process’s environment under the variable name(s) you choose. It is never printed, logged, written to a file, or passed as a command-line argument.

The use case: a deploy script, goreleaser, curl, or some other tool needs the same token madtea uses, but you don’t want to copy it into a shell variable, an .env file, or your shell history to get it there.

Take a Seat

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

Install madtea on Linux, macOS, or Windows - one self-contained binary, one prerequisite: git.

Linux

# amd64 shown; arm64: swap the arch
curl -fsSL https://codeberg.org/sixfold_space/madtea/releases/download/latest/madtea_linux_amd64.tar.gz | tar -xz
./madtea_linux_amd64/madtea install # installs to /usr/local/bin; delete the extracted dir after

The one-liner trusts TLS alone. Every release ships a GPG-signed checksums.txt; to verify the tarball before running anything from it, follow verifying release artifacts. (Later updates via madtea update verify automatically.)

macOS

brew tap sixfold_space/tap https://codeberg.org/sixfold_space/homebrew-tap.git && brew install --cask madtea

Windows

scoop bucket add madtea https://codeberg.org/sixfold_space/scoop-bucket && scoop install madtea

Any OS, from source

# needs Go
go install codeberg.org/sixfold_space/madtea/cmd/madtea@latest

Building from a clone instead is covered in Build madtea from source.

Troubleshooting Guide

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

This guide covers common errors in madtea, their causes, and how to fix them. Error messages are taken directly from the codebase.

1. Configuration Errors

`not configured - run 'madtea auth login' first`

Cause: No Forgejo/Gitea URL or token found in environment variables or git config.

Recovery:

madtea auth login # Interactive setup for this repo
madtea auth login --global # Store credentials globally
# Or set environment variables:
export MADTEA_URL=https://forgejo.example.com
export MADTEA_TOKEN=your-token

`not configured - run 'madtea auth login' or set MADTEA_URL and MADTEA_TOKEN`

Cause: GetConfig() found neither env vars nor git config entries. Same fix as above.