gitea-tea

Gitea CLI（tea）

概述

Gitea 官方命令行界面。可在终端中管理问题、PR、发行版和仓库。

使用说明

1. 验证身份验证：运行 tea whoami 确认已登录
2. 检查上下文：在 git 仓库中运行以自动检测，或使用 --repo owner/repo
3. 使用非交互模式：始终使用 --output 标志并提供所有参数
4. 选择操作：参阅下方的命令参考章节

安装

# 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

身份验证

# 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

问题

列出问题

# 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 with comments
tea issue 42

# Without comments
tea issue 42 --comments=false

# Open in browser
tea open 42

创建问题

# 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)"

修改问题

# 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"

拉取请求

列出 PR

# Open PRs
tea pulls

# Closed PRs
tea pulls --state closed

# Filter by reviewer and labels
tea pulls --reviewer username --label "needs-review"

查看 PR

# View PR details
tea pr 15

# Without comments
tea pr 15 --comments=false

# Open in browser
tea open 15

创建 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)"

检出 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

审查与合并

# 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

发行版

列出发行版

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

创建发行版

# 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"

编辑/删除发行版

# 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

标签

# 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

里程碑

# 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"

仓库

# 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

时间跟踪

# 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

通知

# 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

组织

# List organizations
tea organizations list

# View organization details
tea organizations myorg

# Create organization
tea organizations create myorg

# Delete organization
tea organizations delete myorg

分支

# 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

评论

# Add comment to issue or PR
tea comment 42 "This is my comment"

# From specific repo
tea comment 42 "Comment text" --repo owner/repo

管理（需要管理员权限）

# List users
tea admin users list
tea admin users list --output json

非交互模式（AI Agent）

**重要：**在 AI Agent 环境（无 TTY）中使用 tea 时，请避免交互式提示：

# 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>

始终优先使用明确标志，而非交互式提示。

指南

应做事项

• 在非交互模式下使用 --output simple 或 --output json
• 提前提供所有必需参数，以避免提示
• 操作前运行 tea whoami 验证身份验证
• 使用 tea open <number> 在浏览器中快速查看

不应做事项

• 在 AI Agent 上下文（无 TTY）中使用交互式命令
• 在 git 仓库外忘记添加 --repo owner/repo
• 在脚本中执行破坏性操作时漏掉 --yes 标志
• 以交互方式使用 tea login add（请提前配置）

示例

示例：功能分支 → 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

示例：审查并合并 PR

tea pulls checkout 20
# ... review code ...
tea pulls approve 20 --comment "LGTM!"
tea pulls merge 20 --style squash

示例：创建包含资源的发行版

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