Setup

Generated automatically at build time from the madtea repository - do not edit here. Source: docs/reference/cli-setup.md.

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

Flag	Type	Default	Description
`--global`	bool	false	Clear global git config (~/.gitconfig) instead of the current repo

`madtea auth use-ssh`

Flip a git remote’s URL between HTTPS and SSH forms

Flag	Type	Default	Description
`--dir`	string		Git repository directory (default: current directory)
`--remote`	string	origin	Remote name to flip

`madtea auth whoami`

Show current Forgejo/Gitea identity, verify it against the server, and report token permissions

`madtea completion bash`

Generate bash completion script

`madtea completion fish`

Generate fish completion script

`madtea completion powershell`

Generate powershell completion script

`madtea completion zsh`

Generate zsh completion script

`madtea install`

Install this madtea binary to the standard per-OS location

Flag	Type	Default	Description
`--mcp-client`	stringSlice	[]	also wire the madtea MCP server into these agents: codex, antigravity (repeatable or comma-separated; Claude Code is wired by the bare install)
`--skip-binary`	bool	false	skip the binary copy and its stale-copy sweep (re-run completions and/or MCP registration only)
`--skip-completions`	bool	false	skip installing shell completion scripts
`--skip-mcp`	bool	false	skip MCP server registration with Claude Code
`--yes-delete-stale`	bool	false	consent to deleting stale madtea copies outside the destination without prompting; the plan is still printed
`--yes-sudo`	bool	false	consent to the privileged copy via sudo without prompting; the plan is still printed

`madtea mcp-config`

Print MCP server configuration for an AI coding agent

Flag	Type	Default	Description
`--client`	string		Target AI agent: claude \| codex \| antigravity (auto-detected when omitted)

`madtea open`

Open the repo, an issue, or a PR in the browser

Flag	Type	Default	Description
`--pr`	bool	false	Treat the number as a pull request instead of an issue

`madtea serve`

Start MCP server (stdio transport)

`madtea update`

Update madtea to the latest release

Flag	Type	Default	Description
`--apply`	string		Finish a staged update: replace the running binary with the file staged by –stage. Requires –sha256. Does no network I/O and uses no credentials — run it with elevated privileges (e.g. sudo)
`--check`	bool	false	Check for updates without downloading
`--sha256`	string		Expected SHA-256 (hex) of the staged binary; printed by –stage and required by –apply, which re-verifies the staged file before replacing
`--stage`	bool	false	Download and verify the latest release, then stage the verified binary to a temp file and print the elevated command to finish the update — for installs where the binary needs root to replace but credentials belong to the invoking user (does not replace the running binary)
`--verify`	bool	false	Verify the installed binary against its matching release instead of updating: re-fetch that release, run the same GPG/checksum/archive verification as a normal update, extract the platform binary, and byte-compare it to the file on disk. Reports match or mismatch; on mismatch, repairs via the normal verified swap. A development, unreleased, or go-installed build has nothing to compare against and is reported as such (no download). Best-effort self-diagnosis — a badly broken binary should be reinstalled manually; the value is catching quiet drift (a partial write, a disk fault, or a stale build at the install path)

MCP Tools

`madt_api_call`

Raw Forgejo/Gitea API call (escape hatch). Prefer a specific tool first — they add validation, formatting, and safety. Authenticates with the configured token; endpoint is a path under /api/v1. For issues/PRs/commits/branches/milestones, prefer the typed actions (e.g. madt_issues action=get numbers=[…]) which batch and format; use raw api only for endpoints the typed tools don’t cover.

Output schema: declared

Parameter	Type	Required	Description
`body`	string	no	JSON request body for POST/PATCH/PUT requests
`endpoint`	string	yes	API endpoint starting with / (without /api/v1 prefix)
`jq`	string	no	jq expression to filter JSON response (e.g. ‘.[].title’) — mutually exclusive with template
`method`	string	yes	HTTP method (GET, POST, PATCH, PUT, DELETE)
`paginate`	boolean	no	Follow Link headers to auto-paginate; concatenates JSON arrays across all pages
`raw`	boolean	no	Skip /api/v1 prefix for non-API endpoints (e.g. /swagger.json)
`template`	string	no	Go text/template expression to format JSON response (e.g. ‘{{range .}}{{.title}}{{"\n"}}{{end}}’) — mutually exclusive with jq

`madt_auth_login`

Authenticate this MCP session to the launch-scope forge by completing a browser OAuth login (authorization code + PKCE) and storing the resulting API token in a secure backend. Use this when a call returns 401/“not configured” and no token resolves — it is the in-session remedy for a broken/unauthenticated session, so no terminal ‘madtea auth login’ is needed.

This is a single blocking call: it emits the authorize URL as a progress notification immediately (visit it in a browser to approve), then periodic “still waiting” notifications until you approve or it times out (default 3 minutes; raise with wait_seconds, capped at 600). On success the minted token is stored via a secure backend (OS keychain, pass, or systemd-creds) — never plaintext; if no secure backend exists the call refuses BEFORE starting the flow. No token is ever pasted in and none is echoed in any result or notification.

LOOPBACK LIMITATION: the OAuth redirect lands on 127.0.0.1 on the SERVE host, so your browser must be able to reach the serve host’s loopback — run madtea where your browser is, or forward the port with ssh -L. On success, madtea’s API tools authenticate immediately (credentials resolve per call); the initialize-time capability banner will NOT refresh for this session, so ignore it and call the tools directly. Already authenticated? This returns your identity and does nothing else (idempotent).

Output schema: declared

Parameter	Type	Required	Description
`wait_seconds`	integer	no	How long (in seconds) to block waiting for the browser authorization callback before giving up. Omit or 0 for the 3-minute default; capped at 600. Raise it when you need more time to open the URL on another machine (e.g. via ssh -L).

`madt_auth_use_ssh`

Flip a git remote’s URL between HTTPS and SSH forms (toggles on each call) — the madtea equivalent of fj’s auth use-ssh.

SSH remotes are user-managed authentication outside madtea’s HTTPS token model: ssh-agent or an SSH key carries auth, madtea’s GIT_ASKPASS credential injection never fires, and the stored token is never offered to an SSH remote. Flipping is reversible — call again to switch back.

IMPORTANT — first-contact caveat: before using an SSH remote from a non-interactive surface (including this MCP server), pre-populate ~/.ssh/known_hosts once: ssh -o StrictHostKeyChecking=accept-new -T git@ Otherwise the first operation will fail fast with a clear error (madtea injects BatchMode=yes on the MCP path to prevent an indefinite hang).

Output schema: declared

Parameter	Type	Required	Description
`dir`	string	no	Local filesystem path to the git repository to target (e.g. “/home/user/project”). Defaults to the MCP server’s working directory when omitted.
`remote`	string	no	Git remote name whose URL will be flipped between HTTPS and SSH forms (e.g. “origin”, “upstream”). Defaults to “origin” when omitted.

`madt_auth_whoami`

Show the authenticated user’s identity, confirmed with one authenticated read against the server (not just local credential resolution), plus their permission level and the token’s granted scopes on the current (or specified) repository. Useful for verifying access before attempting operations, or as a pre-flight when a call hits 403/404 to confirm the token is the constraint, not the API path. If this reports a rejected token or no credentials resolve, use madt_auth_login to authenticate this session via a browser OAuth flow (no terminal needed). Pass dir= to instead report the identity THAT checkout’s resolution chain would use, from local config only — no server call, unverified (for orienting/confirming a checkout’s credentials in a multi-repo layout). To flip a remote between HTTPS and SSH protocols, use madt_auth_use_ssh instead.

Output schema: declared

Parameter	Type	Required	Description
`dir`	string	no	Optional absolute path to a LOCAL git checkout to report on instead of the launch scope. With dir=, whoami reports the identity THAT checkout’s chain WOULD use (url, user, source, chain rungs) from LOCAL config only — no server call, result labelled unverified, no token bytes. For orienting or confirming a checkout’s credentials in a multi-repo layout; a whoami-only repo selector, never a token selector. Defaults to the working directory when omitted.
`owner_repo`	string	no	Repository in owner/repo format. Defaults to the repo at the server’s working directory; pass it explicitly to target another repo. See madt_help(topic=“repo-scope”).
`raw_json`	boolean	no	Return raw JSON instead of formatted text. The formatted text shows the full content — titles, bodies, and comments are complete, not previewed — so do not re-fetch with raw_json to check for truncation; use raw_json only when you need machine-readable fields (ids, URLs, timestamps, full hashes).

`madt_enable`

Activate gated tool domain groups mid-conversation (admin, users, hooks, notifications, orgs, packages, project, tags, wiki, activitypub, git-objects). Loads every tool in a domain at once. Call madt_help(topic=“domains”) to list available domains.

Output schema: declared

Parameter	Type	Required	Description
`domains`	[]string \| string	yes	Domain names to enable. Call madt_help(topic=‘domains’) to list available domains.

`madt_help`

Look up madtea usage and tool documentation by topic. Call with an empty topic to list all available topics; topic=“domains” lists gated tool domains.

Output schema: declared

Parameter	Type	Required	Description
`topic`	string	no	Help topic to look up. Omit to list available topics.

`madt_open`

Return the Forgejo/Gitea web URL for the current repo, a specific issue, or a specific PR. URL only — does not launch a browser (the CLI ‘madtea open’ additionally tries xdg-open).

Output schema: declared

Parameter	Type	Required	Description
`number`	integer	no	Issue or PR number to open (0 = open the repo itself)
`pr`	boolean	no	Treat the number as a pull request instead of an issue

Canonical source: docs/reference/cli-setup.md in the madtea repo.