forked from farhoodlabs/skills
update/enhance gitea skills
This commit is contained in:
+114
-767
@@ -1,788 +1,135 @@
|
||||
---
|
||||
name: gitea-tea
|
||||
description: Manage Gitea via CLI using `tea`. Use when user mentions "tea", "gitea cli", or needs terminal-based Gitea operations. Use instead of GitHub CLI when agent reaches for "gh". (Child skill of `gitea` parent skill.)
|
||||
version: 1.0.0
|
||||
version: 1.1.0
|
||||
---
|
||||
|
||||
# Gitea CLI (tea)
|
||||
|
||||
## Overview
|
||||
Official command-line tool for Gitea. Verified against **tea v0.14.1**.
|
||||
|
||||
Official command-line interface for Gitea. Manage issues, PRs, releases, repos, Actions, webhooks, and more from terminal.
|
||||
## Decision flow
|
||||
|
||||
## Instructions
|
||||
1. **Prefer the `gitea` MCP server** (configured in `.mcp.json`) for repos, issues, PRs, releases, branches, files, commits, tags, packages, search, notifications, actions config/runs, time tracking, wiki, and labels/milestones. See `../gitea/references/mcp-tools.md`.
|
||||
2. Reach for `tea` when MCP doesn't cover the op cleanly:
|
||||
- `tea clone <repo-slug>` — local checkout without git
|
||||
- `tea pulls checkout / clean` — local-branch lifecycle for a PR
|
||||
- `tea ssh-keys add/delete` — current user's SSH keys
|
||||
- `tea webhooks` — webhook CRUD (MCP doesn't expose webhooks)
|
||||
- `tea admin users …` — user admin (MCP doesn't expose admin)
|
||||
- `tea times add/delete` — time-tracking entries (MCP exposes most; `tea` is the easier write path)
|
||||
- `tea actions secrets/variables` — quick stdin/file ingestion of secret values
|
||||
- `tea api …` — one-off arbitrary endpoint with auth handled
|
||||
3. Avoid: `tea open` (browser, hangs in headless), `tea pulls review` (interactive prompt), `tea logins add --oauth/--ssh-agent-*` (interactive).
|
||||
|
||||
1. **Verify authentication**: Run `tea whoami` to confirm login
|
||||
2. **Check context**: Run in git repo for auto-detection, or use `--repo owner/repo` or `--login <host>`
|
||||
3. **Use non-interactive mode**: Always use `--output` flag and provide all arguments
|
||||
4. **Choose operation**: See command reference sections below
|
||||
## Non-interactive rules
|
||||
|
||||
`tea` will prompt for missing values when stdout is a TTY. In agent contexts:
|
||||
|
||||
- Pass `--output simple` or `--output json` to disable interactive output.
|
||||
- Provide **every** required value upfront — title, description, etc.
|
||||
- Destructive ops require `--confirm`/`-y` for most commands, but `tea repos delete` uses `--force`/`-f`, and `tea labels/milestones/organizations delete` have no confirm flag (they just delete).
|
||||
- Outside a git repo, always pass `--repo owner/name` and (if multiple logins) `--login <login-name>`.
|
||||
|
||||
## Auth check
|
||||
|
||||
```bash
|
||||
tea whoami # confirm login works
|
||||
tea logins list # see configured logins
|
||||
```
|
||||
|
||||
Set up a token-based login non-interactively:
|
||||
|
||||
```bash
|
||||
tea logins add --name farh --url https://gitea.example.com --token "$GITEA_TOKEN"
|
||||
tea logins default farh
|
||||
```
|
||||
|
||||
Env vars read on first use: `GITEA_SERVER_URL`, `GITEA_SERVER_TOKEN`.
|
||||
|
||||
## Common flags
|
||||
|
||||
| Flag | Purpose |
|
||||
|------|---------|
|
||||
| `--login`/`-l <name>` | Pick a configured login |
|
||||
| `--repo`/`-r <owner/name>` | Operate on a specific repo (required outside git repos) |
|
||||
| `--remote`/`-R <name>` | Discover login from a git remote |
|
||||
| `--output`/`-o <fmt>` | `simple`, `table`, `csv`, `tsv`, `yaml`, `json` |
|
||||
| `--page`/`-p` `--limit`/`--lm` | Pagination (note: short form is `--lm`, two dashes) |
|
||||
| `--confirm`/`-y` | Confirm destructive ops (most commands) |
|
||||
|
||||
## Quick examples
|
||||
|
||||
```bash
|
||||
# Issues — note: --description (not --body), --assignees & --labels (plural)
|
||||
tea issues create --title "Bug" --description "..." --labels bug --assignees alice
|
||||
|
||||
# PRs — review comments are POSITIONAL, not via --comment
|
||||
tea pulls create --title "Add X" --base main --head feature/x --description "$(cat pr.md)"
|
||||
tea pulls approve 20 "LGTM"
|
||||
tea pulls merge 20 --style squash
|
||||
|
||||
# Releases — tag positional, --note OR --note-file (only on create)
|
||||
tea releases create v1.0.0 --title "v1.0.0" --note-file CHANGELOG.md \
|
||||
--asset dist/linux --asset dist/darwin
|
||||
|
||||
# Labels — name via --name, identification by --id
|
||||
tea labels create --name bug --color "#ff0000"
|
||||
tea labels update --id 7 --name regression
|
||||
|
||||
# Repos — delete uses --owner + --name + --force
|
||||
tea repos delete --owner myorg --name myrepo --force
|
||||
|
||||
# Clone — top-level helper, NOT `tea repos clone`
|
||||
tea clone owner/repo ./dir
|
||||
|
||||
# Actions — secret/variable values are POSITIONAL, not --value
|
||||
tea actions secrets create DEPLOY_TOKEN "$(cat ~/.token)"
|
||||
tea actions variables set BUILD_VERSION "1.2.3"
|
||||
tea actions runs logs 12345 --job 7 # --job flag, not positional
|
||||
|
||||
# Time tracking — both args POSITIONAL: <issue> <duration>
|
||||
tea times add 42 1h30m
|
||||
|
||||
# Generic API
|
||||
tea api /repos/{owner}/{repo}/issues -X POST -f title="..." -f body="..."
|
||||
```
|
||||
|
||||
## Full command reference
|
||||
|
||||
See [references/commands.md](references/commands.md) for the full verified surface — every common subcommand, with flag corrections vs. older docs.
|
||||
|
||||
## Known doc pitfalls (corrected in references/)
|
||||
|
||||
Documentation found in older copies of this skill (or from other sources) often contained these errors:
|
||||
|
||||
- `tea issues create --body "..."` — there is no `--body`; use `--description`/`-d`.
|
||||
- `tea pulls approve 20 --comment "LGTM"` — comment is positional: `tea pulls approve 20 "LGTM"`.
|
||||
- `tea pulls review 20 --state comment` — `tea pulls review` is interactive only; no `--state`/`--comment` flags.
|
||||
- `tea repos delete owner/repo --yes` — uses `--owner`/`--name`/`--force`.
|
||||
- `tea repos clone …` — doesn't exist; use `tea clone …`.
|
||||
- `tea labels delete bug` — `tea labels delete --id <int>`, no positional name.
|
||||
- `tea milestones create "v2.0.0"` — title is via `--title` flag.
|
||||
- `tea actions secrets create FOO --value "bar"` — value is positional.
|
||||
- `tea actions runs logs 12345 1` — second arg is `--job 1`.
|
||||
- `tea actions runs rerun 12345` — no such subcommand (use MCP `actions_run_write` method `rerun_run`).
|
||||
- `tea attachments …` — no such top-level command (use `tea releases assets …`).
|
||||
- `tea times add 42 --time 2h --message …` — `tea times add <issue> <duration>`, both positional, no flags.
|
||||
- `tea logins env` / `tea login env` — does not exist.
|
||||
- `tea open <issue-number>` / `tea open pulls` — `tea open` accepts no positional args per its `--help`; will also hang in headless environments.
|
||||
|
||||
## Installation
|
||||
|
||||
If `tea` isn't already on PATH:
|
||||
|
||||
```bash
|
||||
# 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/
|
||||
# Linux
|
||||
curl -sL https://dl.gitea.io/tea/main/tea-main-linux-amd64 -o /usr/local/bin/tea
|
||||
chmod +x /usr/local/bin/tea
|
||||
|
||||
# From source
|
||||
go install code.gitea.io/tea@latest
|
||||
```
|
||||
|
||||
## Common Flags
|
||||
|
||||
These flags are available on most commands:
|
||||
|
||||
| Flag | Alias | Description |
|
||||
|------|-------|-------------|
|
||||
| `--login` | `-l` | Use a specific Gitea login/instance |
|
||||
| `--repo` | `-r` | Specify repository (`owner/repo`) |
|
||||
| `--remote` | `-R` | Discover login from git remote |
|
||||
| `--output` | `-o` | Output format: `simple`, `table`, `csv`, `tsv`, `yaml`, `json` |
|
||||
| `--page` | `-p` | Page number for list commands (default: 1) |
|
||||
| `--limit` | `-lm` | Items per page (default: 30) |
|
||||
|
||||
## Authentication
|
||||
|
||||
```bash
|
||||
# Token-based login (recommended for CI/AI agents)
|
||||
tea login add \
|
||||
--name mygitea \
|
||||
--url https://gitea.example.com \
|
||||
--token <your-token>
|
||||
|
||||
# Or use environment variables
|
||||
export GITEA_SERVER_URL=https://gitea.example.com
|
||||
export GITEA_SERVER_TOKEN=<your-token>
|
||||
|
||||
# OAuth2 interactive login
|
||||
tea login add --oauth --name mygitea --url https://gitea.example.com
|
||||
|
||||
# SSH agent login (requires running ssh-agent with key loaded)
|
||||
tea login add --ssh-agent-key <fingerprint> --ssh-agent-principal <principal>
|
||||
|
||||
# List logins
|
||||
tea login list
|
||||
|
||||
# Set default
|
||||
tea login default gitea.example.com
|
||||
|
||||
# Refresh OAuth token
|
||||
tea login oauth-refresh [login-name]
|
||||
|
||||
# Delete login
|
||||
tea login delete gitea.example.com
|
||||
|
||||
# Verify
|
||||
tea whoami
|
||||
```
|
||||
|
||||
## Issues
|
||||
|
||||
### List Issues
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# View issue with comments
|
||||
tea issue 42
|
||||
|
||||
# Without comments
|
||||
tea issue 42 --comments=false
|
||||
|
||||
# Open in browser
|
||||
tea open 42
|
||||
```
|
||||
|
||||
### Create Issue
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Open PRs
|
||||
tea pulls
|
||||
|
||||
# Closed PRs
|
||||
tea pulls --state closed
|
||||
|
||||
# Filter by reviewer and labels
|
||||
tea pulls --reviewer username --label "needs-review"
|
||||
```
|
||||
|
||||
### View PR
|
||||
```bash
|
||||
# View PR details
|
||||
tea pr 15
|
||||
|
||||
# Without comments
|
||||
tea pr 15 --comments=false
|
||||
|
||||
# Open in browser
|
||||
tea open 15
|
||||
```
|
||||
|
||||
### Create PR
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
tea releases list
|
||||
tea releases list --limit 10
|
||||
tea releases list --repo owner/project
|
||||
```
|
||||
|
||||
### Create Release
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
# Edit repo
|
||||
tea repos edit owner/repo \
|
||||
--description "Updated description" \
|
||||
--private=false
|
||||
|
||||
# Delete repo
|
||||
tea repos delete owner/repo
|
||||
|
||||
# Clone repo (without git)
|
||||
tea repos clone owner/repo
|
||||
tea repos clone owner/repo ./target-dir
|
||||
tea repos clone gitea.com/owner/repo # With host
|
||||
```
|
||||
|
||||
## SSH Keys
|
||||
|
||||
```bash
|
||||
# List your SSH keys
|
||||
tea ssh-keys list
|
||||
|
||||
# Add SSH key from file
|
||||
tea ssh-keys add ~/.ssh/id_ed25519.pub
|
||||
tea ssh-keys add ~/.ssh/id_ed25519.pub --title "Work laptop"
|
||||
|
||||
# Delete SSH key by ID
|
||||
tea ssh-keys delete 123 --confirm
|
||||
```
|
||||
|
||||
## Actions / CI/CD
|
||||
|
||||
### Workflow Runs
|
||||
```bash
|
||||
# List workflow runs
|
||||
tea actions runs list
|
||||
tea actions runs list --status success --branch main
|
||||
tea actions runs list --event push --since "24h"
|
||||
tea actions runs list --actor username --limit 50
|
||||
|
||||
# View run details
|
||||
tea actions runs view 12345
|
||||
tea actions runs view 12345 --jobs=false
|
||||
|
||||
# View run logs
|
||||
tea actions runs logs 12345 1 # run ID, job ID
|
||||
|
||||
# Cancel run
|
||||
tea actions runs cancel 12345
|
||||
|
||||
# Rerun run
|
||||
tea actions runs rerun 12345
|
||||
|
||||
# Delete run
|
||||
tea actions runs delete 12345 --confirm
|
||||
```
|
||||
|
||||
### Workflows
|
||||
```bash
|
||||
# List workflows
|
||||
tea actions workflows list
|
||||
|
||||
# View workflow file
|
||||
tea actions workflows view .gitea/workflows/ci.yml
|
||||
|
||||
# Enable/disable workflow
|
||||
tea actions workflows enable .gitea/workflows/ci.yml
|
||||
tea actions workflows disable .gitea/workflows/ci.yml
|
||||
|
||||
# Dispatch workflow
|
||||
tea actions workflows dispatch .gitea/workflows/ci.yml --ref main
|
||||
```
|
||||
|
||||
### Actions Secrets
|
||||
```bash
|
||||
# List secrets
|
||||
tea actions secrets list
|
||||
|
||||
# Create secret
|
||||
tea actions secrets create DEPLOY_TOKEN --value "secret-value"
|
||||
tea actions secrets create DB_PASSWORD --file /path/to/password.txt
|
||||
echo "secret-value" | tea actions secrets create API_KEY --stdin
|
||||
|
||||
# Delete secret
|
||||
tea actions secrets delete DEPLOY_TOKEN --confirm
|
||||
```
|
||||
|
||||
### Actions Variables
|
||||
```bash
|
||||
# List variables (get specific one)
|
||||
tea actions variables list --name BUILD_VERSION
|
||||
|
||||
# Set variable
|
||||
tea actions variables set BUILD_VERSION --value "1.2.3"
|
||||
tea actions variables set CONFIG --file /path/to/config.json
|
||||
|
||||
# Delete variable
|
||||
tea actions variables delete BUILD_VERSION --confirm
|
||||
```
|
||||
|
||||
## Webhooks
|
||||
|
||||
```bash
|
||||
# List webhooks
|
||||
tea webhooks list
|
||||
tea webhooks list --repo owner/repo
|
||||
|
||||
# Create webhook
|
||||
tea webhooks create https://example.com/webhook \
|
||||
--type gitea \
|
||||
--secret mysecret \
|
||||
--events push,pull_request \
|
||||
--active
|
||||
|
||||
# Update webhook
|
||||
tea webhooks update 1 \
|
||||
--url https://new-url.com/hook \
|
||||
--secret newsecret \
|
||||
--events push
|
||||
|
||||
# Enable/disable webhook
|
||||
tea webhooks update 1 --active
|
||||
tea webhooks update 1 --inactive
|
||||
|
||||
# Delete webhook
|
||||
tea webhooks delete 1 --confirm
|
||||
```
|
||||
|
||||
## Attachments
|
||||
|
||||
```bash
|
||||
# List attachments
|
||||
tea attachments list 42 # issue/PR number
|
||||
|
||||
# Create attachment
|
||||
tea attachments create 42 --file ./artifact.zip
|
||||
|
||||
# Delete attachment
|
||||
tea attachments delete 42 --id 1 --confirm
|
||||
```
|
||||
|
||||
## Time Tracking
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# List organizations
|
||||
tea organizations list
|
||||
|
||||
# View organization details
|
||||
tea organizations view myorg
|
||||
|
||||
# Create organization
|
||||
tea organizations create myorg
|
||||
|
||||
# Delete organization
|
||||
tea organizations delete myorg --confirm
|
||||
```
|
||||
|
||||
## Branches
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
# Rename branch
|
||||
tea branches rename old-name new-name
|
||||
```
|
||||
|
||||
## Comments
|
||||
|
||||
```bash
|
||||
# Add comment to issue or PR
|
||||
tea comment 42 "This is my comment"
|
||||
|
||||
# From specific repo
|
||||
tea comment 42 "Comment text" --repo owner/repo
|
||||
```
|
||||
|
||||
## Open in Browser
|
||||
|
||||
```bash
|
||||
# Open issue/PR by number
|
||||
tea open 42
|
||||
|
||||
# Open specific pages
|
||||
tea open issues
|
||||
tea open pulls
|
||||
tea open releases
|
||||
tea open commits
|
||||
tea open branches
|
||||
tea open wiki
|
||||
tea open activity
|
||||
tea open settings
|
||||
tea open labels
|
||||
tea open milestones
|
||||
```
|
||||
|
||||
**Warning:** `tea open` opens a browser window. It will hang indefinitely in headless/agent environments — do not use in non-interactive contexts.
|
||||
|
||||
## Admin (requires admin access)
|
||||
|
||||
### Users
|
||||
```bash
|
||||
# List users
|
||||
tea admin users list
|
||||
tea admin users list --output json
|
||||
tea admin users list --page 2 --limit 50
|
||||
|
||||
# Create user
|
||||
tea admin users create \
|
||||
--username newuser \
|
||||
--email newuser@example.com \
|
||||
--password "SecurePass123!" \
|
||||
--full-name "New User" \
|
||||
--admin \
|
||||
--visibility public
|
||||
|
||||
# Edit user
|
||||
tea admin users edit username \
|
||||
--email newemail@example.com \
|
||||
--full-name "Updated Name" \
|
||||
--admin \
|
||||
--no-admin \
|
||||
--restricted \
|
||||
--active \
|
||||
--visibility private
|
||||
|
||||
# Delete user
|
||||
tea admin users delete username --confirm
|
||||
```
|
||||
|
||||
## Generic API Command
|
||||
|
||||
Make authenticated requests directly to the Gitea API:
|
||||
|
||||
```bash
|
||||
# GET request (default)
|
||||
tea api /user
|
||||
|
||||
# POST with JSON body
|
||||
tea api /repos/owner/repo/issues \
|
||||
--method POST \
|
||||
--data '{"title":"New issue","body":"Description"}'
|
||||
|
||||
# POST with form fields
|
||||
tea api /repos/owner/repo/issues \
|
||||
--method POST \
|
||||
--field title="New issue" \
|
||||
--field body="Description"
|
||||
|
||||
# With headers
|
||||
tea api /repos/owner/repo \
|
||||
--header "X-Custom-Header: value"
|
||||
|
||||
# Include response headers in output
|
||||
tea api /user --include
|
||||
|
||||
# Write response to file
|
||||
tea api /repos/owner/repo/archive --output release.zip
|
||||
|
||||
# Placeholder expansion (from git context)
|
||||
tea api /repos/{owner}/{repo}/actions/runs --login gitea.com
|
||||
```
|
||||
|
||||
## Non-Interactive Mode (AI Agents)
|
||||
|
||||
**IMPORTANT:** When using tea in AI agent environments (no TTY), avoid interactive prompts:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
tea admin users delete username --yes
|
||||
|
||||
# Set default login to avoid prompts
|
||||
tea login default <login-name>
|
||||
|
||||
# Always specify --login when not in a git repo
|
||||
tea issues list --login gitea.com --repo owner/repo
|
||||
```
|
||||
|
||||
**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
|
||||
- Specify `--login <host>` when operating outside a git repository
|
||||
|
||||
### 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
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
tea pulls checkout 20
|
||||
# ... review code ...
|
||||
tea pulls approve 20 --comment "LGTM!"
|
||||
tea pulls merge 20 --style squash
|
||||
```
|
||||
|
||||
### Example: Create Release with Assets
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
### Example: Manage Actions Secrets
|
||||
```bash
|
||||
# Deploy to staging
|
||||
tea actions secrets create STAGING_DEPLOY_TOKEN \
|
||||
--value "$(cat ~/secrets/staging-token)" \
|
||||
--repo myorg/myrepo
|
||||
|
||||
# Trigger workflow
|
||||
tea actions workflows dispatch .gitea/workflows/deploy.yml --ref staging \
|
||||
--repo myorg/myrepo
|
||||
```
|
||||
|
||||
### Example: Admin User Management
|
||||
```bash
|
||||
# Create service account
|
||||
tea admin users create ci-bot \
|
||||
--email ci-bot@mycompany.com \
|
||||
--password "$(openssl rand -base64 24)" \
|
||||
--restricted \
|
||||
--no-must-change-password
|
||||
|
||||
# Deactivate user
|
||||
tea admin users edit username --prohibit-login
|
||||
```
|
||||
Reference in New Issue
Block a user