teax: gap filler for Gitea's CLI

The problem

Gitea is great. Self-hosted, lightweight, GitHub-compatible. If you're running a homelab, self-hosting your repos, or just prefer not to depend on GitHub—Gitea is the answer. I run it for all my projects.

But the official CLI, tea, has gaps.

You can create issues, but editing them? Not so much. Bulk operations across a sprint's worth of tickets? Nope. Workflow run visibility? You get a list, but good luck finding out why something failed. Dependencies between issues? Not there.

For a while, I worked around it. Curl commands. Web UI. You know how it goes, right?

Then I got tired of workarounds. So I built teax—gap filler for tea.

What teax does

teax fills the gaps in tea. All the operations you expect from a CLI but tea doesn't support:

Issue management — Edit issues after creation. Add labels, change assignees, update milestones. The stuff you actually need to do.

teax issue edit 42 -r owner/repo --add-labels "bug,high-priority"
teax issue edit 42 -r owner/repo --assignees "alice,bob"

Bulk operations — Apply changes across multiple issues at once. Ranges, lists, or both.

teax issue bulk 17-23 -r owner/repo --add-labels "sprint/current"
teax issue bulk "17,18,25-30" -r owner/repo --rm-labels "needs-triage"

Dependencies — Track which issues block which. Essential for planning.

teax deps add 42 -r owner/repo --on 17    # Issue 42 depends on 17
teax deps list 42 -r owner/repo

Epics — Group related issues under a parent. Track progress across the set.

teax epic create auth-system -r owner/repo --child 17 --child 18
teax epic status 25 -r owner/repo

Workflow runs — See what's passing, what's failing, and why. This is the big one for CI visibility.

teax runs status -r owner/repo              # Quick health overview
teax runs get 42 -r owner/repo --errors-only  # Just show what broke
teax runs logs 123 -r owner/repo --tail 100   # Last 100 lines

Secrets and variables — Manage Actions secrets and variables from the terminal.

teax secrets set DEPLOY_TOKEN -r owner/repo   # Interactive prompt
teax vars set ENV_NAME --value prod -r owner/repo

Runners — List, inspect, and manage Gitea Actions runners.

teax runners list -r owner/repo
teax runners token -r owner/repo    # Get registration token

Why it matters

I use teax runs status constantly. It's how I keep CI health visible without leaving the terminal.

My tmux status bar polls teax runs status and shows me build health for all my projects:

B:✓ C:✓ D:✓ V:✓

When something's red, I run teax runs get <id> --errors-only to see exactly what failed. No clicking through web UI. No searching logs manually, right? Just the error, right there.

This is the visibility piece that makes trunk-based development work for solo devs. You need to know immediately when something breaks. teax gives you that.

Installation

Requires Python 3.11+ and tea already configured.

# pip
pip install git+https://github.com/simoninglis/teax.git

# pipx (recommended for CLI tools)
pipx install git+https://github.com/simoninglis/teax.git

teax reads auth from tea's config (~/.config/tea/config.yml), so if tea works, teax works. No separate setup.

The philosophy

I didn't build teax to replace tea. I built it to fill gaps—like Selly's (the Australian gap filler), but for CLIs.

tea handles the basics well: creating repos, opening issues, basic PR operations. teax handles everything else: editing, labels, bulk operations, dependencies, CI visibility, secrets, runners.

They work together. Same auth, same config, complementary commands.

If you're running Gitea and tired of switching to the web UI for things tea can't do, give teax a try.

GitHub: github.com/simoninglis/teax

Issues and PRs welcome. If tea's missing something you need, chances are teax should have it.