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.

It can create issues, but editing them? Not so much. Bulk operations across a sprint's worth of tickets? Nope. Workflow run visibility? It gives you 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, a 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

It lets you edit issues after creation, which tea doesn't. Add labels, change assignees, update milestones. The stuff you actually need to do day-to-day.

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. This is the one I use most during sprint planning when I need to tag a batch of issues.

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

It tracks which issues block which. Essential for planning, and something tea has no concept of at all.

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 and track progress across the set. Useful when a feature spans half a dozen tickets.

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

Workflow runs

This is the big one for CI visibility. It shows what's passing, what's failing and why, without clicking through the web UI.

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, variables and runners

It manages Actions secrets and variables from the terminal, and lists or inspects Gitea Actions runners. Not glamorous, but you'd be surprised how often you need to rotate a deploy token or check runner health.

teax secrets set DEPLOY_TOKEN -r owner/repo   # Interactive prompt
teax vars set ENV_NAME --value prod -r owner/repo
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, without clicking through web UI or searching logs manually. 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 without 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.