Gitea CLI companion for tea feature gaps.
teax complements the official tea CLI by providing commands that tea doesn't support:
- Issue lifecycle: Create, view, close, reopen, and comment on issues
- Issue editing: Modify labels, assignees, milestones on existing issues
- Dependency management: Set and manage issue blockers/blocked-by relationships
- Bulk operations: Apply changes to multiple issues at once
- Sprint management: View sprint status, ready queue, and plan sprints
- Epic management: Create and track parent issues with child issue checklists
- Runner management: List, inspect, and manage Gitea Actions runners
- Workflow runs: View workflow run status, jobs, logs, and trigger reruns
- Secrets & Variables: Manage repository/org/user secrets and variables
- Package management: Link/unlink packages to repositories
- Milestone management: Create, edit, close milestones; determine current sprint
Uses tea's configuration for authentication - no additional setup required.
# Using pip
pip install git+https://github.com/simoninglis/teax.git
# Using uv
uv pip install git+https://github.com/simoninglis/teax.git
# Using pipx (isolated environment)
pipx install git+https://github.com/simoninglis/teax.git# Clone the repository
git clone https://github.com/simoninglis/teax.git
cd teax
# Install with Poetry
poetry install
# Verify installation
poetry run teax --version- Python 3.11+
- tea CLI installed and configured (
tea login add)
# List dependencies for an issue
teax deps list 25 --repo owner/repo
# Add dependency: issue 25 depends on issue 17
teax deps add 25 --repo owner/repo --on 17
# Add blocker: issue 17 blocks issue 25
teax deps add 17 --repo owner/repo --blocks 25
# Remove dependency
teax deps rm 25 --repo owner/repo --on 17# Create a new issue
teax issue create -r owner/repo --title "Bug: login broken"
teax issue create -r owner/repo -t "Feature request" -b "Description here"
teax issue create -r owner/repo -t "Task" --labels "bug,urgent" --assignees "user1"
# List issues with filtering
teax issue list -r owner/repo --state open
teax issue list -r owner/repo --label ready --no-label "sprint/*"
teax -o json issue list -r owner/repo
# View issue details (body, labels, assignees, milestone)
teax issue view 25 --repo owner/repo
teax issue view 25 --repo owner/repo --comments
# Close issues
teax issue close 42 -r owner/repo
teax issue close 42,43,44 -r owner/repo -y # Multiple with confirmation skip
# Reopen issues
teax issue reopen 42 -r owner/repo
# Add a comment
teax issue comment 42 -r owner/repo -m "This is my comment"
# Edit a comment (ID shown in view --comments)
teax issue comment-edit 12345 -r owner/repo -m "Updated text"
# Delete a comment
teax issue comment-delete 12345 -r owner/repo
teax issue comment-delete 12345 -r owner/repo -y # Skip confirmation# Add labels
teax issue edit 25 --repo owner/repo --add-labels "epic/diagnostics,prio/p1"
# Remove labels
teax issue edit 25 --repo owner/repo --rm-labels "needs-triage"
# Replace all labels
teax issue edit 25 --repo owner/repo --set-labels "type/feature,prio/p2"
# Set assignees
teax issue edit 25 --repo owner/repo --assignees "user1,user2"
# Set milestone (by ID or name)
teax issue edit 25 --repo owner/repo --milestone 5
teax issue edit 25 --repo owner/repo --milestone "Sprint 1"
# Clear milestone
teax issue edit 25 --repo owner/repo --milestone ""
# List labels on an issue
teax issue labels 25 --repo owner/repo# Add labels to multiple issues
teax issue bulk 17-23 --repo owner/repo --add-labels "sprint/week1"
# Set assignees on a range of issues
teax issue bulk "17,18,25-30" --repo owner/repo --assignees "user1"
# Set milestone on multiple issues (by ID or name)
teax issue bulk 17-20 --repo owner/repo --milestone 5
# Skip confirmation prompt
teax issue bulk 17-23 --repo owner/repo --add-labels "done" --yes# Create a new epic with child issues
teax epic create auth --repo owner/repo --title "Auth System" -c 17 -c 18
# Add issues to an existing epic
teax epic add 25 17 18 19 --repo owner/repo
# Show epic progress
teax epic status 25 --repo owner/repo# View sprint overview (current sprint, ready queue, backlog)
teax sprint status --repo owner/repo
# List issues ready for sprint (have "ready" label, no sprint label)
teax sprint ready --repo owner/repo
# List issues in a specific sprint
teax sprint issues 28 --repo owner/repo
teax sprint issues 28 --repo owner/repo --state open
# Plan a sprint (assign issues to sprint label)
teax sprint plan 29 --repo owner/repo --issues 17-23,25
teax sprint plan 29 --repo owner/repo --issues 17-23 --confirm # Execute
# Ensure a label exists (idempotent)
teax label ensure sprint/29 --repo owner/repo
teax label ensure ready --repo owner/repo --color 00ff00Manage Gitea Actions runners across repos, orgs, or globally (admin).
# List runners for a repository
teax runners list --repo owner/repo
# List runners for an organisation
teax runners list --org myorg
# List global runners (admin only)
teax runners list --global
# Get runner details
teax runners get 42 --repo owner/repo
# Delete a runner (prompts for confirmation)
teax runners delete 42 --repo owner/repo
teax runners delete 42 --repo owner/repo -y # Skip confirmation
# Get registration token for adding new runners
teax runners token --repo owner/repo
teax -o simple runners token --repo owner/repo # For scriptingView and manage Gitea Actions workflow runs.
# Quick status of recent runs
teax runs status --repo owner/repo
# List all runs with filtering
teax runs list --repo owner/repo --status failure --limit 10
# Get run details
teax runs get 42 --repo owner/repo
# List jobs for a run
teax runs jobs 42 --repo owner/repo
teax runs jobs 42 --repo owner/repo --errors-only
# View job logs with filtering
teax runs logs 123 --repo owner/repo --tail 100
teax runs logs 123 --repo owner/repo --grep "Error" --context 5
# Rerun a failed workflow
teax runs rerun 42 --repo owner/repo
# Delete old runs
teax runs delete 42 --repo owner/repo -yManage secrets and variables at repository, organisation, or user level.
# List secrets
teax secrets list --repo owner/repo
teax secrets list --org myorg
teax secrets list --user
# Set a secret
teax secrets set MY_SECRET "secret-value" --repo owner/repo
# Delete a secret
teax secrets delete MY_SECRET --repo owner/repo
# Variables work the same way
teax vars list --repo owner/repo
teax vars set MY_VAR "value" --repo owner/repo
teax vars delete MY_VAR --repo owner/repoLink packages to repositories for better organisation.
# Link a package to a repository
teax pkg link mypackage --owner myorg --type pypi --repo myproject
# Unlink a package
teax pkg unlink mypackage --owner myorg --type container
# Get latest version
teax pkg latest mypackage --owner myorg --type pypiCreate API access tokens programmatically (requires password).
# Create a token (prompts for password)
teax token create my-ci-token --scopes write:repository,write:package
# Create token with password from environment variable
teax token create my-token --password-env MY_PASSWORD
# Get token value only (for scripting)
teax -o simple token create my-token --scopes write:repository -p MY_PASSWORDNote: Token creation requires Basic authentication (username + password), not token auth. This is a Gitea API requirement.
Manage milestones for sprint tracking and lifecycle management.
# List all milestones
teax milestone list -r owner/repo
teax milestone list -r owner/repo --state open
# Create a milestone
teax milestone create "Sprint 50" -r owner/repo
teax milestone create "Sprint 50" -r owner/repo --due-date 2026-03-01
teax milestone create "Sprint 50" -r owner/repo -d "Sprint goals" --if-not-exists
# Close a milestone
teax milestone close "Sprint 50" -r owner/repo
# Reopen a milestone
teax milestone open "Sprint 50" -r owner/repo
# Edit milestone (title, description, due date)
teax milestone edit "Sprint 50" -r owner/repo -t "Sprint 50 (Extended)"
teax milestone edit 5 -r owner/repo --due-date 2026-03-15
teax milestone edit "Sprint 50" -r owner/repo --due-date "" # Clear due date
# Get lifecycle state (completed, in_progress, planned, not_found)
teax milestone state "Sprint 50" -r owner/repo
# Get current in-progress sprint
teax milestone current -r owner/repo
CURRENT=$(teax -o simple milestone current -r owner/repo)# Use specific tea login
teax --login backup.example.com deps list 25 --repo owner/repo
# Change output format
teax --output simple deps list 25 --repo owner/repo
teax --output csv deps list 25 --repo owner/repoteax reads authentication from tea's config file at ~/.config/tea/config.yml:
logins:
- name: gitea.example.com
url: https://gitea.example.com
token: <your-api-token>
default: true
user: usernameIf you haven't configured tea yet:
tea login add| Variable | Description |
|---|---|
TEAX_CA_BUNDLE |
Path to custom CA certificate bundle (e.g., /path/to/ca.pem). Use for self-hosted Gitea with custom certificates. |
TEAX_INSECURE |
Set to 1 to skip SSL certificate verification entirely (not recommended). |
Examples:
# Use a custom CA certificate bundle
TEAX_CA_BUNDLE=/etc/ssl/certs/my-ca.pem teax deps list 25 --repo owner/repo
# Skip SSL verification (not recommended)
TEAX_INSECURE=1 teax deps list 25 --repo owner/repo# Install dev dependencies
poetry install
# Run all quality checks (lint, typecheck, test)
just check
# Run individual checks
just test # Run pytest
just lint # Run ruff linting
just typecheck # Run mypy
# Format code
just format
# Run CLI during development
just run --help
just run deps list 25 --repo owner/repo| Feature | tea Support | teax Scope |
|---|---|---|
| Issue create | Supported | Implemented (semantic clarity) |
| Issue list | Supported | Implemented (with filtering) |
| Issue view | Buggy¹ | Implemented |
| Issue close/reopen | Supported | Implemented (semantic clarity) |
| Issue comments | Missing | Implemented |
| Issue edit | Missing | Implemented |
| Issue dependencies | Missing | Implemented |
| Issue bulk ops | Missing | Implemented |
| Sprint management | Missing | Implemented |
| Epic management | Missing | Implemented |
| Runner management | Missing | Implemented |
| Workflow runs | Missing | Implemented |
| Secrets/Variables | Missing | Implemented |
| Package linking | Missing | Implemented |
| Token creation | Missing | Implemented |
| Label CRUD | Full | Out of scope |
| Label ensure | Missing | Implemented |
| Milestone CRUD | Partial² | Implemented |
| Milestone lifecycle | Missing | Implemented |
| Milestone assign | Missing | Via issue edit |
| PR operations | Full | Out of scope |
¹ tea's issue view breaks with --fields or --comments flags, returning a list instead of issue details.
² tea supports milestone list but not create/edit/close. teax provides full milestone management including lifecycle state detection.
Note: While tea supports some issue operations, teax provides all issue commands for semantic clarity: use tea for authentication, repos, and PRs; use teax for all issue operations.
MIT - see LICENSE for details.