Reference on madtea

ActivityPub

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

Inspect ActivityPub federation actors for repositories and users.

CLI Commands

`madtea activitypub actor`

Get instance ActivityPub actor

`madtea activitypub repo`

Get repository ActivityPub actor

`madtea activitypub user`

Get user ActivityPub actor

MCP Tools

`madt_activitypub`

ActivityPub federation endpoints (requires madt_enable(domains=[“activitypub”])): instance, user, and repository actors.

Output schema: declared

One tool, action-dispatched. Set action to one of:

`action="actor"`

Get the instance ActivityPub actor.

`action="repo"`

Get a repository’s ActivityPub actor by numeric repository ID.

Admin

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

Administer the instance, managing users, organizations, cron jobs, global webhooks, runners, and unadopted repositories.

CLI Commands

`madtea admin cron list`

List cron tasks

`madtea admin cron run`

Run a cron task

`madtea admin emails list`

List all emails

Flag	Type	Default	Description
`--limit`	int	0	Maximum number of items to return (0 = server default)
`--page`	int	0	Page number for pagination (0 = first page)

`madtea admin emails search`

Search emails

Branches & Tags

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

Manage remote branches and tags, including branch protection rules.

CLI Commands

`madtea branches-remote create`

Create branch via API

Flag	Type	Default	Description
`--from`	string		Branch or ref to create from

`madtea branches-remote delete`

Delete remote branch

`madtea branches-remote get`

Get branch details

`madtea branches-remote list`

List remote branches

Flag	Type	Default	Description
`--limit`	int	0	Maximum number of items to return (0 = server default)
`--page`	int	0	Page number for pagination (0 = first page)

`madtea branches-remote protect`

Get branch protection rules

CI/CD & Actions

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

Drive Forgejo/Gitea Actions CI/CD, covering workflows, runs, jobs, logs, artifacts, runners, secrets, variables, and manual dispatch.

CLI Commands

`madtea actions artifacts delete`

Delete an artifact

`madtea actions artifacts download`

Download an artifact zip

Flag	Type	Default	Description
`--output`	string		Output file path (default: stdout)

`madtea actions artifacts get`

Get artifact details

`madtea actions artifacts list`

List repository artifacts

Flag	Type	Default	Description
`--limit`	int	0	Maximum number of items to return (0 = server default)
`--page`	int	0	Page number for pagination (0 = first page)

`madtea actions dispatch`

Trigger a workflow dispatch

Commits

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

List, inspect, and compare commits, and manage their commit statuses.

CLI Commands

`madtea commits compare`

Compare two refs

`madtea commits diff`

Get commit as unified diff

`madtea commits get`

Get full commit details

`madtea commits list`

List commits

Flag	Type	Default	Description
`--files`	bool	false	Include file change list per commit
`--limit`	int	0	Maximum number of items to return (0 = server default)
`--not`	string		Exclude commits reachable from this ref
`--page`	int	0	Page number for pagination (0 = first page)
`--path`	string		Filter to commits affecting this file path
`--sha`	string		Branch, tag, or commit SHA to start from
`--since`	string		Commits since timestamp (YYYY-MM-DD or RFC3339)
`--stat`	bool	false	Include diff statistics
`--until`	string		Commits until timestamp (YYYY-MM-DD or RFC3339)
`--verification`	bool	false	Include GPG signature verification info

`madtea commits pr-for-commit`

Get PR for a commit

Destructive

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

Explains why madtea never exposes an operation that destroys unrecoverable work or data, and where to perform a genuine hard delete instead.

Model of record: ADR 0029 (strict omission). A madtea surface never carries an operation that can destroy unrecoverable work or data; destruction is offered only when madtea can machine-prove nothing is lost (content-verified prune, force-with-lease push, merged-only branch delete). The irreversible forge-data deletes (repository, issue, release, tag, wiki page) are omitted from both the MCP tools and the CLI: each delete subcommand remains discoverable but refuses, naming the forge web UI. Use the forge web UI (or raw git) for a genuine hard delete.

Files & Content

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

Manage repository file contents, directory listings, and batch file operations.

CLI Commands

`madtea dir list`

List directory contents

Flag	Type	Default	Description
`--ref`	string		Branch, tag, or SHA

`madtea dir list-root`

List root directory contents

Flag	Type	Default	Description
`--ref`	string		Branch, tag, or SHA

`madtea file batch`

Batch file operations

`madtea file contents`

Get file contents via file-contents endpoint

`madtea file create`

Create a new file

Flag	Type	Description
`--author-email`	string	Custom commit author email
`--author-name`	string	Custom commit author name
`--branch`	string	Branch to create file on
`--committer-email`	string	Custom committer email
`--committer-name`	string	Custom committer name
`--date-author`	string	Custom author date (ISO 8601)
`--date-committer`	string	Custom committer date (ISO 8601)
`--message`	string	Commit message (required)
`--new-branch`	string	Create file on a new branch with this name

`madtea file delete`

Delete a file

Git

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

Local git operations on the working checkout, including staging, committing, branching, worktrees, and inspecting local-only refs.

Foreign-checkout immutability model (madt_fetch, madt_pull, madt_worktrees): ADR 0019. Credential injection model (GIT_ASKPASS, never token-in-URL): ADR 0013.

CLI Commands

`madtea add`

Stage files for commit

`madtea branch`

Create, list, or delete local branches

Flag	Type	Default	Description
`--base`	string		Start-point ref/sha to branch from (with -b; default: current HEAD)
`--create`	bool	false	Create and checkout a new branch
`--delete`	bool	false	Delete a merged branch (safe; madtea never force-deletes)
`--issue`	int	0	Link branch to Forgejo/Gitea issue number
`--list`	bool	false	List branches

`madtea checkout`

Switch branches

Git Objects

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

Read and write low-level git objects through the forge API, including blobs, trees, refs, notes, tag objects, and patches.

MCP Tools

`madt_git_objects`

Low-level git object operations (current repo by default; requires madt_enable(domains=[“git-objects”])): refs, trees, blobs, annotated tags, notes, and diff/patch apply.

Output schema: declared

One tool, action-dispatched. Set action to one of:

`action="apply_diff"`

Apply a diff or patch to the repository, creating a new commit. The target branch must already exist (create one via madt_branches_remote action=create); applying to a protected default branch is rejected.

Issues

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

Create, edit, and triage issues, with comments, attachments, labels, dependencies, deadlines, time tracking, reactions, and dependency-aware ranking.

CLI Commands

`madtea issue all-comments`

List all comments in the repository

Flag	Type	Default	Description
`--limit`	int	0	Maximum number of items to return (0 = server default)
`--page`	int	0	Page number for pagination (0 = first page)
`--since`	string		Filter comments updated since this date (YYYY-MM-DD or RFC3339)

`madtea issue attachments`

List attachments on an issue

Labels

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

Create, update, and delete repository labels, and assign or clone them across issues and repositories.

CLI Commands

`madtea labels add`

Add labels to an issue (keeps existing labels)

`madtea labels clone`

Clone labels from a source repository

Flag	Type	Default	Description
`--force`	bool	false	on create: update an existing same-named label; on clone: update existing instead of skipping

`madtea labels create`

Create a label

Flag	Type	Default	Description
`--color`	string	cccccc	hex color, without leading #
`--description`	string		Optional label description — a short note explaining what the label means (e.g. ‘Something is not working’).
`--exclusive`	bool	false	mark exclusive (only one label per group)
`--force`	bool	false	on create: update an existing same-named label; on clone: update existing instead of skipping
`--is-archived`	bool	false	archive the label (hidden from selectors)
`--name`	string		Label name (alternative to positional argument)

`madtea labels delete`

Delete a label

MCP Prompts

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

madtea registers its golden-path workflows as MCP prompts. A client that supports prompts (such as Claude Code) surfaces each one as a slash command — invoke it as /mcp__madtea__<name> followed by the prompt’s arguments.

Prompt	Invocation	Title	Arguments
`file-issue`	`/mcp__madtea__file-issue`	File a well-formed issue	`title` (required): concise issue title; `body` (optional): issue body: context, expected vs actual, repro steps (optional)
`finish-branch`	`/mcp__madtea__finish-branch`	Finish the current branch	`summary` (required): what changed and why (PR body); `closes` (optional): comma-separated issue numbers to close on merge (optional; e.g. 42,57)
`reconcile`	`/mcp__madtea__reconcile`	Reconcile a conflicted pull request	`number` (required): the pull request number to reconcile (e.g. 42)
`release`	`/mcp__madtea__release`	Check release cadence and cut a release	—
`review`	`/mcp__madtea__review`	Review a pull request	`number` (required): the pull request number to review (e.g. 42)
`standup`	`/mcp__madtea__standup`	Recent activity summary	`days` (optional): how many days back to summarize (optional; default 7)
`start-feature`	`/mcp__madtea__start-feature`	Start a feature branch	`name` (required): branch/feature name (e.g. fix-login or issue-42-rate-limit)
`triage`	`/mcp__madtea__triage`	Triage the open backlog	`target` (optional): what to rank: omit for the current repo, or pass owner/repo, or a bare owner to aggregate a whole org

Milestones

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

Create, update, close, reopen, and list repository milestones.

CLI Commands

`madtea milestone close`

Close one or more milestones

`madtea milestone create`

Create a new milestone

Flag	Type	Default	Description
`--description`	string		Milestone description
`--due`	string		Due date (YYYY-MM-DD)

`madtea milestone delete`

Delete a milestone

`madtea milestone get`

Get milestone details

`madtea milestone list`

List milestones

Flag	Type	Default	Description
`--limit`	int	0	Maximum number of items to return (0 = server default)
`--page`	int	0	Page number for pagination (0 = first page)
`--state`	string	open	Filter by state: open, closed, all

`madtea milestone reopen`

Reopen one or more milestones

Miscellaneous

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

Assorted utilities, including markdown and markup rendering, server info, instance settings, signing keys, templates, and topic search.

CLI Commands

`madtea render markdown`

Render markdown to HTML

Flag	Type	Default	Description
`--repo`	string		Repository context (owner/repo)

`madtea render markup`

Render markup to HTML

Flag	Type	Default	Description
`--mode`	string	gfm	Markup mode (gfm, comment, wiki)
`--repo`	string		Repository context (owner/repo)

`madtea server-info`

Show detected server platform and version

`madtea settings api`

API settings

Notifications

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

List notification threads and mark them as read, globally or scoped to a single repository.

CLI Commands

`madtea notifications list`

List notifications

Flag	Type	Default	Description
`--all`	bool	false	Include read notifications
`--before`	string		Only show notifications updated before this time (YYYY-MM-DD or RFC3339)
`--limit`	int	0	Maximum number of items to return (0 = server default)
`--page`	int	0	Page number for pagination (0 = first page)
`--since`	string		Only show notifications updated after this time (YYYY-MM-DD or RFC3339)
`--status-types`	stringSlice	[]	Filter by status: read, unread, pinned
`--subject-type`	stringSlice	[]	Filter by subject: issue, pull, commit, repository

`madtea notifications new`

Get count of unread notifications

Organizations

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

Manage organizations and their members, teams, webhooks, secrets, variables, runners, and org-level labels.

CLI Commands

`madtea org activity`

Get organization activity feed

`madtea org avatar delete`

Delete an organization’s avatar

`madtea org avatar upload`

Upload an organization avatar

`madtea org blocks add`

Block a user

`madtea org blocks check`

Check if a user is blocked

`madtea org blocks list`

List blocked users

`madtea org blocks remove`

Unblock a user

`madtea org create`

Create a new organization

Packages

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

List, inspect, and delete registry packages, along with their versions, files, and repository links.

CLI Commands

`madtea packages delete`

Delete a package version

`madtea packages files`

List package files

`madtea packages get`

Get package version details

`madtea packages latest`

Get latest package version

`madtea packages link`

Link package to a repository

`madtea packages list`

List packages for an owner

Flag	Type	Default	Description
`--limit`	int	0	Maximum number of items to return (0 = server default)
`--page`	int	0	Page number for pagination (0 = first page)
`--type`	string		Filter by package type (go, npm, container, etc.)

`madtea packages unlink`

Unlink package from repository

Pull Requests

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

Open, review, and merge pull requests, covering diffs, checks, review threads, reviewers, conflict handling, and merge control.

CLI Commands

`madtea pr body append`

Append content to the end of a pull-request body

Flag	Type	Default	Description
`--file`	string		Read content from file (use - for stdin)

`madtea pr body patch`

Apply anchored (old -> new) replacements to a pull-request body

Flag	Type	Default	Description
`--file`	string		Read replacements JSON from file (use - for stdin)
`--new`	stringArray	[]	Replacement text (repeatable; pairs with –old)
`--old`	stringArray	[]	Anchor text to find (repeatable; pairs with –new)
`--replace-all`	boolSlice	[]	Replace every occurrence for the corresponding –old/–new pair (repeatable, in order)

`madtea pr body section-replace`

Replace the content of a named marked section in a pull-request body

Releases

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

Publish and manage releases and their downloadable assets, including lookup by tag and latest-release resolution.

CLI Commands

`madtea release assets edit`

Rename or edit a release asset

Flag	Type	Default	Description
`--name`	string		New name for the asset

`madtea release assets get`

Get a specific release asset

`madtea release assets list`

List assets on a release

`madtea release by-tag`

Get a release by tag name

`madtea release create`

Create a release from a tag

Repository

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

Manage repositories and their settings, including creation, forking, transfer, collaborators, branch protection, webhooks, mirrors, deploy keys, and topics.

CLI Commands

`madtea project disable`

Disable projects for the current repository

`madtea project enable`

Enable projects for the current repository

Flag	Type	Default	Description
`--mode`	string		Projects mode: repo, owner, or all

`madtea project status`

Show project settings for the current repository

`madtea repo activity`

Get activity feed

`madtea repo archive`

Download a repository archive

Search

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

Search across the instance for issues, pull requests, repositories, and users.

CLI Commands

`madtea search issues`

Search issues across the instance

Flag	Type	Default	Description
`--label`	stringSlice	[]	Label names (comma-separated or repeated)
`--limit`	int	0	Maximum number of items to return (0 = server default)
`--owner`	string		Filter by repository owner
`--page`	int	0	Page number for pagination (0 = first page)
`--state`	string		Filter by state: open, closed, all

`madtea search prs`

Search pull requests across the instance

Setup

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

Set up and configure madtea, covering authentication, installation, updates, the MCP server, shell completion, and raw API access.

Credential storage model (OS keychain, never token-in-URL): ADR 0013. Install location policy (one blessed binary per OS): ADR 0010. Launch-scope credential boundary (one token per session, no cross-clone shopping): ADR 0027.

CLI Commands

`madtea auth login`

Set up Forgejo/Gitea credentials

Flag	Type	Default	Description
`--force`	bool	false	Skip confirmations (for non-interactive use)
`--insecure-storage`	bool	false	Store the token in plaintext git config instead of a secure backend (OS keychain, pass, or systemd-creds).
`--token`	string		API token
`--url`	string		Forgejo/Gitea server URL
`--web`	bool	false	Open a browser to authenticate

`madtea auth logout`

Clear madtea-stored credentials for a scope

Stats

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

Report repository, organization, issue, contributor, and instance-usage statistics.

CLI Commands

`madtea stats`

Repository or organization statistics

`madtea stats contributors`

Contributor stats for a repository

`madtea stats issues`

Issue analytics for a repository

`madtea stats org`

Get organization statistics

`madtea stats repo`

Get repository statistics

`madtea stats usage`

Local command usage statistics

Flag	Type	Default	Description
`--html`	string		Write a self-contained HTML report to this path and print the path
`--limit`	int	20	Maximum rows to show (0 = all)
`--since`	string		Filter events since date (YYYY-MM-DD) or Go duration (e.g. 720h)

MCP Tools

`madt_stats`

Repository, organization, contributor, and issue statistics.

Users

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

Manage user accounts and profiles, including SSH and GPG keys, emails, access tokens, OAuth2 apps, follows, stars, subscriptions, and quotas.

CLI Commands

`madtea gpg-key add`

Add a GPG key

`madtea gpg-key delete`

Delete a GPG key

`madtea gpg-key list`

List GPG keys

`madtea user activity`

Get user activity feed

`madtea user avatar delete`

Delete avatar

`madtea user avatar upload`

Upload avatar image

`madtea user blocks add`

Block a user

`madtea user blocks check`

Check if a user is blocked

Wiki

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

Create, read, update, and delete repository wiki pages and view their revision history.

CLI Commands

`madtea wiki create`

Create wiki page

Flag	Type	Default	Description
`--file`	string		Read content from file (use - for stdin)
`--message`	string		Commit message (required)

`madtea wiki delete`

Delete a wiki page (refused — use the forge web UI)

`madtea wiki get`

Get wiki page content

`madtea wiki list`

List wiki pages

Flag	Type	Default	Description
`--limit`	int	0	Maximum number of items to return (0 = server default)
`--page`	int	0	Page number for pagination (0 = first page)

`madtea wiki revisions`

List wiki page revisions

Workflows

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

High-level git workflow commands for branch initialization, branch completion, orchestration, ADR management, and merged-branch pruning.

Destruction model for prune (content-verified, never force-delete) and branch delete: ADR 0029.

CLI Commands

`madtea adr check`

Verify ADR numbering, index bijection, and links (exit 1 on drift)

`madtea adr new`

Create the next ADR record and index row (number from origin)

Flag	Type	Default	Description
`--offline`	bool	false	Number from the local tree instead of the origin default branch
`--title`	string		Record title (defaults to a title derived from the slug)
`--tracking`	string		Tracking reference recorded in the header (e.g. an issue or epic)

`madtea finish`

Commit, push, create PR, merge, and return to default branch