Gitea CLI (tea)

Overview

Official command-line interface for Gitea. Manage issues, PRs, releases, and repos from terminal.

Instructions

• Verify authentication: Run tea whoami to confirm login

• Check context: Run in git repo for auto-detection, or use --repo owner/repo

• Use non-interactive mode: Always use --output flag and provide all arguments

• Choose operation: See command reference sections below

Installation

macOS

brew install tea

Linux (binary)

curl -sL https://dl.gitea.io/tea/main/tea-main-linux-amd64 -o tea chmod +x tea && sudo mv tea /usr/local/bin/

From source

go install code.gitea.io/tea@latest

Authentication

Interactive login (recommended)

tea login add

Select: Application Token

Enter Gitea URL and token from User Settings → Applications

List logins

tea login list

Set default

tea login default gitea.example.com

Delete login

tea login delete gitea.example.com

Verify

tea whoami

Issues

List Issues

Open issues in current repo

tea issues list

All issues (including closed)

tea issues list --state all

Filter by milestone

tea issues list --milestone "v1.0.0"

Filter by assignee and labels

tea issues list --assignee username --label bug,critical

From specific repo

tea issues list --repo owner/repo --login gitea.com

View Issue

View issue with comments

tea issue 42

Without comments

tea issue 42 --comments=false

Open in browser

tea open 42

Create Issue

Interactive

tea issues create

With arguments

tea issues create
--title "Fix authentication bug"
--body "Users cannot login with special characters"
--label bug,security
--assignee developer1
--milestone "v1.2.0"

From file

tea issues create
--title "Feature request"
--body "$(cat feature-request.md)"

Modify Issues

Close issue

tea issues close 42

Reopen issue

tea issues reopen 42

Edit issue

tea issues edit 42
--title "Updated title"
--assignee newdev
--add-labels "enhancement"

Pull Requests

List PRs

Open PRs

tea pulls

Closed PRs

tea pulls --state closed

Filter by reviewer and labels

tea pulls --reviewer username --label "needs-review"

View PR

View PR details

tea pr 15

Without comments

tea pr 15 --comments=false

Open in browser

tea open 15

Create PR

Interactive

tea pulls create

With arguments

tea pulls create
--title "Implement user authentication"
--description "Adds OAuth and JWT support"
--base main
--head feature/auth
--assignee reviewer1,reviewer2
--label "enhancement"

Description from file

tea pulls create
--title "Major refactor"
--description "$(cat pr-description.md)"

Checkout PR

Checkout PR locally

tea pulls checkout 20

Custom branch name

tea pulls checkout 20 pr-20-custom-name

Clean up checked out PRs

tea pulls clean

Review & Merge

Approve PR

tea pulls approve 20 --comment "LGTM!"

Request changes

tea pulls reject 20 --comment "Please add tests"

Leave comment

tea pulls review 20
--state comment
--comment "Consider refactoring this section"

Merge PR (squash)

tea pulls merge 20 --style squash --message "feat: implement auth"

Merge PR (rebase)

tea pulls merge 20 --style rebase

Close PR

tea pulls close 20

Reopen PR

tea pulls reopen 20

Releases

List Releases

tea releases list tea releases list --limit 10 tea releases list --repo owner/project

Create Release

Basic release

tea releases create v1.0.0
--title "Version 1.0.0"
--note "First stable release"

From changelog file

tea releases create v1.2.0
--title "Version 1.2.0"
--note-file CHANGELOG.md

Draft release

tea releases create v2.0.0-beta
--title "Beta Release"
--draft
--note "Beta for testing"

With assets

tea releases create v1.1.0-rc1
--title "Release Candidate 1"
--prerelease
--asset dist/binary-linux-amd64
--asset dist/binary-darwin-amd64

Create tag + release

tea releases create v1.3.0
--target main
--title "Version 1.3.0"
--note "New features"

Edit/Delete Release

Update release

tea releases edit v1.0.0
--title "Version 1.0.0 - Updated"
--note-file NEW-NOTES.md

Publish draft

tea releases edit v2.0.0 --draft=false

Delete release

tea releases delete v0.9.0 tea releases delete v1.0.0-beta --confirm

Labels

List labels

tea labels list tea labels list --repo owner/project tea labels list --save # Save labels to file

Create label

tea labels create bug
--color "#ff0000"
--description "Something isn't working"

tea labels create enhancement
--color "0,255,0"
--description "New feature"

Update label

tea labels update bug --color "#cc0000" tea labels update old-name --name new-name

Delete label

tea labels delete bug

Milestones

List milestones

tea milestones list tea milestones list --state open tea milestones list --state closed

View milestone issues

tea milestones issues "v1.0.0" tea milestones issues "v1.0.0" --kind pull # Only PRs tea milestones issues "v1.0.0" --state all

Add issue/PR to milestone

tea milestones issues add "v1.0.0" 42

Remove issue/PR from milestone

tea milestones issues remove "v1.0.0" 42

Create milestone

tea milestones create "v2.0.0"
--description "Major version release"
--deadline "2024-12-31"

Close milestone

tea milestones close "v1.0.0"

Reopen milestone

tea milestones reopen "v1.0.0"

Delete milestone

tea milestones delete "v0.9.0"

Repositories

List repos

tea repos list tea repos list --org myorg tea repos list --watched # Watched repos tea repos list --starred # Starred repos tea repos list --type fork # Filter: fork, mirror, source tea repos list --output yaml

Search repos

tea repos search "keyword" --login gitea.com

View repo details

tea repos owner/repo

Create repo

tea repos create --name myrepo --private --init tea repos create
--name myrepo
--owner myorg
--description "My project"
--private
--init
--gitignores Go
--license MIT

Create from template

tea repos create-from-template
--template owner/template-repo
--name new-repo

Fork repo

tea repos fork --repo owner/repo tea repos fork --repo owner/repo --owner myorg

Delete repo

tea repos delete owner/repo

Clone repo (without git)

tea clone owner/repo tea clone owner/repo ./target-dir tea clone gitea.com/owner/repo # With host

Time Tracking

List time entries

tea times list tea times list --issue 42 tea times list --user username tea times list --from "2024-01-01" --until "2024-12-31"

Add time

tea times add 42 --time "2h" tea times add 42 --time "1h30m" --message "Implemented auth logic"

Delete entry

tea times delete 42 --id 123

Notifications

List notifications (current repo)

tea notifications list

List all notifications

tea notifications list --mine

Filter by type

tea notifications list --types issue,pull

Filter by state

tea notifications list --states unread,pinned

Mark as read

tea notifications read # All filtered tea notifications read 123 # Specific ID

Mark as unread

tea notifications unread 123

Pin/unpin

tea notifications pin 123 tea notifications unpin 123

Organizations

List organizations

tea organizations list

View organization details

tea organizations myorg

Create organization

tea organizations create myorg

Delete organization

tea organizations delete myorg

Branches

List branches

tea branches list tea branches list --output json

View branch details

tea branches main

Protect branch

tea branches protect main

Unprotect branch

tea branches unprotect main

Comments

Add comment to issue or PR

tea comment 42 "This is my comment"

From specific repo

tea comment 42 "Comment text" --repo owner/repo

Admin (requires admin access)

List users

tea admin users list tea admin users list --output json

Non-Interactive Mode (AI Agents)

IMPORTANT: When using tea in AI agent environments (no TTY), avoid interactive prompts:

Use --output to disable interactive mode

tea issues --output simple tea pulls --output json

Provide ALL required arguments upfront

tea issue create --title "Bug title" --body "Description here" tea pr create --title "PR title" --head feature-branch --base main

Use -y or --yes for confirmations

tea pr merge 5 --yes tea releases delete v0.9.0 --yes

Set default login to avoid prompts

tea login default <login-name>

Always prefer explicit flags over interactive prompts.

Guidelines

Do

• Use --output simple or --output json for non-interactive mode

• Provide all required arguments upfront to avoid prompts

• Run tea whoami to verify authentication before operations

• Use tea open <number> to quickly view in browser

Don't

• Use interactive commands in AI agent context (no TTY)

• Forget --repo owner/repo when outside git repository

• Skip --yes flag for destructive operations in scripts

• Use tea login add interactively (configure beforehand)

Examples

Example: Feature Branch → PR

git checkout -b feature/new-feature

... make changes ...

git add . && git commit -m "feat: add new feature" git push -u origin feature/new-feature tea pulls create --title "Add new feature" --base main --head feature/new-feature

Example: Review & Merge PR

tea pulls checkout 20

... review code ...

tea pulls approve 20 --comment "LGTM!" tea pulls merge 20 --style squash

Example: Create Release with Assets

git tag v1.0.0 git push origin v1.0.0 tea releases create v1.0.0
--title "v1.0.0"
--note-file CHANGELOG.md
--asset dist/app-linux
--asset dist/app-darwin