forked from farhoodlabs/skills
481 lines
14 KiB
Markdown
481 lines
14 KiB
Markdown
# `tea` Command Reference
|
|
|
|
Verified against `tea` v0.14.1. When in doubt, run `tea <command> --help`. Flags below are exhaustive only for the operations agents need most often.
|
|
|
|
## Conventions
|
|
|
|
- `--login`/`-l`, `--repo`/`-r`, `--remote`/`-R` are available on most subcommands. Outside a git repo, pass `--repo owner/name` and (if you have multiple logins) `--login <name>`.
|
|
- `--output`/`-o` accepts: `simple`, `table`, `csv`, `tsv`, `yaml`, `json`. Use `json` for parsing, `simple` for terse non-interactive output.
|
|
- `--limit`/`--lm` (yes, double-dash on the short form), `--page`/`-p` for paging.
|
|
- Destructive ops normally require `--confirm`/`-y`. **Exceptions:** `tea repos delete` uses `--force`/`-f`; `tea labels delete` / `tea milestones delete` / `tea organizations delete` have no confirm flag (they just delete).
|
|
|
|
## Auth
|
|
|
|
```bash
|
|
# Token-based login (use for CI/agents)
|
|
tea logins add --name mygitea --url https://gitea.example.com --token <token>
|
|
|
|
# Or via env vars (read on first command)
|
|
export GITEA_SERVER_URL=https://gitea.example.com
|
|
export GITEA_SERVER_TOKEN=<token>
|
|
|
|
tea logins list
|
|
tea logins default <login-name> # set default
|
|
tea logins delete <login-name>
|
|
tea whoami # verify
|
|
```
|
|
|
|
OAuth/SSH-agent logins exist (`tea logins add --oauth …`, `--ssh-agent-key …`); they are interactive and not useful in agent contexts.
|
|
|
|
> `tea logins env` does **not** exist. The original wiki doc referenced it — ignore.
|
|
|
|
## Issues
|
|
|
|
```bash
|
|
# List
|
|
tea issues list
|
|
tea issues list --state all --labels bug,critical --assignee alice --milestone v1.0.0
|
|
tea issues list --repo owner/repo --login gitea.example.com
|
|
|
|
# View (positional <index>)
|
|
tea issues 42 # detail view
|
|
tea issue 42 --comments=false # without comments
|
|
|
|
# Create — note: --description (NOT --body), --assignees (plural), --labels (plural)
|
|
tea issues create \
|
|
--title "Fix authentication bug" \
|
|
--description "Users cannot login with special characters" \
|
|
--labels bug,security \
|
|
--assignees alice,bob \
|
|
--milestone v1.2.0
|
|
|
|
# Description from file
|
|
tea issues create --title "Feature request" --description "$(cat req.md)"
|
|
|
|
# Edit — add/remove labels are separate flags
|
|
tea issues edit 42 \
|
|
--title "Updated title" \
|
|
--add-assignees bob \
|
|
--add-labels enhancement \
|
|
--remove-labels stale
|
|
|
|
# State
|
|
tea issues close 42
|
|
tea issues reopen 42
|
|
```
|
|
|
|
## Pull requests
|
|
|
|
```bash
|
|
# List
|
|
tea pulls list
|
|
tea pulls list --state closed
|
|
# Note: --reviewer / --label do NOT exist on pulls list; filter client-side or via API.
|
|
|
|
# View
|
|
tea pulls 15
|
|
tea pr 15 --comments=false
|
|
|
|
# Create — same flag conventions as issues create
|
|
tea pulls create \
|
|
--title "Implement OAuth" \
|
|
--description "$(cat pr.md)" \
|
|
--base main --head feature/auth \
|
|
--assignees reviewer1,reviewer2 \
|
|
--labels enhancement \
|
|
--allow-maintainer-edits
|
|
|
|
# Checkout (no custom branch-name positional; only --branch/-b to create one)
|
|
tea pulls checkout 20
|
|
tea pulls checkout 20 --branch
|
|
tea pulls clean 20 # delete local + remote branches after merge
|
|
|
|
# Review — comment/reason are POSITIONAL, no --comment flag
|
|
tea pulls approve 20 "LGTM"
|
|
tea pulls reject 20 "Please add tests"
|
|
# Note: `tea pulls review <id>` is interactive — do not use in agent context.
|
|
|
|
# Merge
|
|
tea pulls merge 20 --style squash --title "feat: oauth" --message "Adds OAuth + JWT"
|
|
tea pulls merge 20 --style rebase
|
|
# Merge styles: merge, rebase, squash, rebase-merge
|
|
|
|
# State
|
|
tea pulls close 20
|
|
tea pulls reopen 20
|
|
```
|
|
|
|
## Releases
|
|
|
|
```bash
|
|
tea releases list
|
|
tea releases list --limit 10 --repo owner/repo
|
|
|
|
# Create — tag is positional; --target sets commitish; --note OR --note-file
|
|
tea releases create v1.0.0 \
|
|
--title "Version 1.0.0" \
|
|
--note "First stable release"
|
|
|
|
tea releases create v1.2.0 --title "v1.2.0" --note-file CHANGELOG.md
|
|
tea releases create v2.0.0-beta --title "Beta" --draft --note "For testing"
|
|
tea releases create v1.1.0-rc1 --title "RC1" --prerelease \
|
|
--asset dist/binary-linux-amd64 --asset dist/binary-darwin-amd64
|
|
tea releases create v1.3.0 --target main --title "v1.3.0" --note "..."
|
|
|
|
# Edit — note that --note-file does NOT exist on edit (use --note only)
|
|
tea releases edit v1.0.0 --title "v1.0.0 — Updated" --note "$(cat NEW-NOTES.md)"
|
|
tea releases edit v2.0.0 --draft false # publish
|
|
|
|
# Delete (--confirm/-y required)
|
|
tea releases delete v0.9.0 --confirm
|
|
tea releases delete v1.0.0-beta -y --delete-tag
|
|
|
|
# Release assets (NOT `tea attachments` — that command doesn't exist)
|
|
tea releases assets list v1.0.0
|
|
tea releases assets create v1.0.0 --file ./dist/binary.tar.gz
|
|
tea releases assets delete v1.0.0 --id 17 --confirm
|
|
```
|
|
|
|
## Labels
|
|
|
|
```bash
|
|
tea labels list
|
|
tea labels list --save # dump to file
|
|
|
|
# Create — name via --name flag (NOT positional)
|
|
tea labels create --name bug --color "#ff0000" --description "Something isn't working"
|
|
tea labels create --name enhancement --color "0,255,0" --description "New feature"
|
|
|
|
# Update — by --id (NOT by name)
|
|
tea labels update --id 7 --color "#cc0000"
|
|
tea labels update --id 7 --name new-name
|
|
|
|
# Delete — by --id (NOT positional name; no --confirm)
|
|
tea labels delete --id 7
|
|
```
|
|
|
|
## Milestones
|
|
|
|
```bash
|
|
tea milestones list
|
|
tea milestones list --state open
|
|
tea milestones list --state closed
|
|
|
|
# Create — title via --title flag
|
|
tea milestones create --title v2.0.0 \
|
|
--description "Major version" \
|
|
--deadline 2025-12-31
|
|
|
|
# Manage issues/pulls in a milestone — positional <name> <index>
|
|
tea milestones issues v1.0.0
|
|
tea milestones issues v1.0.0 --kind pull --state all
|
|
tea milestones issues add v1.0.0 42
|
|
tea milestones issues remove v1.0.0 42
|
|
|
|
# State (positional name)
|
|
tea milestones close v1.0.0
|
|
tea milestones reopen v1.0.0
|
|
tea milestones delete v0.9.0 # no confirm flag
|
|
```
|
|
|
|
## Repositories
|
|
|
|
```bash
|
|
# List
|
|
tea repos list
|
|
tea repos list --owner myorg
|
|
tea repos list --watched
|
|
tea repos list --starred
|
|
tea repos list --type fork # fork|mirror|source
|
|
|
|
# Search — positional <term>
|
|
tea repos search "keyword"
|
|
tea repos search "k8s" --topic --login gitea.example.com
|
|
|
|
# Create — fields via flags
|
|
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 --content --labels
|
|
|
|
# Fork — source via --repo, target owner via --owner
|
|
tea repos fork --repo owner/source
|
|
tea repos fork --repo owner/source --owner myorg
|
|
|
|
# Edit
|
|
tea repos edit --description "Updated" --private false
|
|
|
|
# Delete — via --name + --owner + --force (NOT positional owner/repo, NOT --yes)
|
|
tea repos delete --owner myorg --name myrepo --force
|
|
|
|
# Clone (NOT `tea repos clone`) — top-level helper, takes repo slug
|
|
tea clone owner/repo
|
|
tea clone owner/repo ./target-dir
|
|
tea clone gitea.example.com/owner/repo
|
|
tea clone --depth 1 owner/repo
|
|
```
|
|
|
|
## Branches
|
|
|
|
```bash
|
|
tea branches list
|
|
tea branches main # detail view (positional name)
|
|
tea branches protect main
|
|
tea branches unprotect main
|
|
tea branches rename old new
|
|
```
|
|
|
|
## Actions / CI/CD
|
|
|
|
### Workflow runs
|
|
|
|
```bash
|
|
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 alice --limit 50
|
|
|
|
tea actions runs view 12345
|
|
tea actions runs view 12345 --jobs # show jobs table
|
|
|
|
# Logs — job is via --job flag (NOT a positional second arg)
|
|
tea actions runs logs 12345
|
|
tea actions runs logs 12345 --job 7
|
|
tea actions runs logs 12345 --job 7 --follow
|
|
|
|
# Cancel/delete (same subcommand; aliases: delete, remove, rm, cancel)
|
|
tea actions runs cancel 12345 --confirm
|
|
tea actions runs delete 12345 -y
|
|
|
|
# Note: `tea actions runs rerun` does NOT exist. Use the MCP `actions_run_write` tool
|
|
# (method="rerun_run") or the REST API.
|
|
```
|
|
|
|
### Workflows
|
|
|
|
```bash
|
|
tea actions workflows list
|
|
tea actions workflows view ci.yml
|
|
tea actions workflows enable ci.yml
|
|
tea actions workflows disable ci.yml
|
|
|
|
# Dispatch — workflow_dispatch event
|
|
tea actions workflows dispatch ci.yml --ref main
|
|
tea actions workflows dispatch ci.yml --ref staging --input env=prod --input version=1.2.3
|
|
tea actions workflows dispatch ci.yml --ref main --follow # tail logs after dispatch
|
|
```
|
|
|
|
### Secrets
|
|
|
|
```bash
|
|
tea actions secrets list
|
|
|
|
# Create — value is POSITIONAL (NOT --value)
|
|
tea actions secrets create DEPLOY_TOKEN "secret-value"
|
|
tea actions secrets create DEPLOY_TOKEN --file /path/to/value.txt
|
|
echo "secret-value" | tea actions secrets create API_KEY --stdin
|
|
|
|
tea actions secrets delete DEPLOY_TOKEN --confirm
|
|
```
|
|
|
|
### Variables
|
|
|
|
```bash
|
|
tea actions variables list
|
|
tea actions variables list --name BUILD_VERSION
|
|
|
|
# Set — value is POSITIONAL (NOT --value)
|
|
tea actions variables set BUILD_VERSION "1.2.3"
|
|
tea actions variables set CONFIG --file /path/to/config.json
|
|
|
|
tea actions variables delete BUILD_VERSION --confirm
|
|
```
|
|
|
|
## Webhooks
|
|
|
|
```bash
|
|
tea webhooks list
|
|
tea webhooks list --repo owner/repo
|
|
tea webhooks list --org myorg
|
|
tea webhooks list --global
|
|
|
|
# Create — URL is positional
|
|
tea webhooks create https://example.com/webhook \
|
|
--type gitea --secret mysecret \
|
|
--events push,pull_request --active
|
|
|
|
# Update — ID is positional
|
|
tea webhooks update 1 --url https://new.example.com/hook --events push
|
|
tea webhooks update 1 --active # enable
|
|
tea webhooks update 1 --inactive # disable
|
|
|
|
tea webhooks delete 1 --confirm
|
|
```
|
|
|
|
Webhook types: `gitea, gogs, slack, discord, dingtalk, telegram, msteams, feishu, wechatwork, packagist`.
|
|
|
|
## SSH keys
|
|
|
|
```bash
|
|
tea ssh-keys list
|
|
|
|
# Add — key file is positional
|
|
tea ssh-keys add ~/.ssh/id_ed25519.pub
|
|
tea ssh-keys add ~/.ssh/id_ed25519.pub --title "Work laptop"
|
|
|
|
# Delete — ID is positional, --confirm required
|
|
tea ssh-keys delete 123 --confirm
|
|
```
|
|
|
|
## Time tracking
|
|
|
|
```bash
|
|
tea times list
|
|
tea times list --from 2024-01-01 --until 2024-12-31 --total
|
|
tea times list --mine # across all repos
|
|
|
|
# Add — both args POSITIONAL: <issue> <duration>. No --time, no --message.
|
|
tea times add 42 2h
|
|
tea times add 42 1h30m
|
|
|
|
tea times delete --id 123
|
|
tea times reset 42 # reset all on an issue
|
|
```
|
|
|
|
## Notifications
|
|
|
|
```bash
|
|
tea notifications list # current repo
|
|
tea notifications list --mine # across all repos
|
|
tea notifications list --types issue,pull
|
|
tea notifications list --states unread,pinned
|
|
|
|
tea notifications read # mark all filtered as read
|
|
tea notifications read 123 # mark one
|
|
tea notifications unread 123
|
|
tea notifications pin 123
|
|
tea notifications unpin 123
|
|
```
|
|
|
|
## Organizations
|
|
|
|
```bash
|
|
tea organizations list
|
|
tea organizations view myorg
|
|
tea organizations create myorg --description "..." --visibility public
|
|
tea organizations delete myorg # no confirm flag
|
|
```
|
|
|
|
## Comments
|
|
|
|
```bash
|
|
# Both args positional: <issue/pr index> [<body>]
|
|
tea comment 42 "This is my comment"
|
|
tea comment 42 "Comment text" --repo owner/repo
|
|
```
|
|
|
|
## Admin (requires admin token)
|
|
|
|
```bash
|
|
tea admin users list
|
|
tea admin users list --output json --page 2 --limit 50
|
|
|
|
tea admin users create \
|
|
--username newuser --email newuser@example.com \
|
|
--password "$(openssl rand -base64 24)" \
|
|
--full-name "New User" \
|
|
--admin --visibility public
|
|
|
|
# Edit — note: there is no --no-admin or --no-restricted. Boolean flags work in one direction.
|
|
tea admin users edit newuser \
|
|
--email new@example.com \
|
|
--full-name "Updated Name" \
|
|
--admin --restricted --active
|
|
|
|
tea admin users edit newuser --prohibit-login # deactivate
|
|
|
|
tea admin users delete newuser --confirm
|
|
```
|
|
|
|
## Generic API helper
|
|
|
|
```bash
|
|
# GET (default)
|
|
tea api /user
|
|
|
|
# Endpoint placeholders auto-expand from git context
|
|
tea api '/repos/{owner}/{repo}/actions/runs?status=success'
|
|
|
|
# POST with string fields
|
|
tea api /repos/{owner}/{repo}/issues -X POST \
|
|
-f title="New issue" -f body="Description"
|
|
|
|
# POST with typed fields (numbers, booleans). Read value from file with @path; stdin with @-.
|
|
tea api /repos/{owner}/{repo}/labels -X POST \
|
|
-F name="prio:high" -F color="#ff0000" -F exclusive=true
|
|
|
|
# Raw JSON body (mutually exclusive with -f/-F)
|
|
tea api /repos/{owner}/{repo}/issues -X POST \
|
|
-d '{"title":"New","body":"..."}'
|
|
|
|
tea api /repos/{owner}/{repo}/archive -o release.zip # write body to file
|
|
tea api /user -i # include status + headers (to stderr)
|
|
tea api /repos/{owner}/{repo} -H "X-Custom: value"
|
|
```
|
|
|
|
## Open in browser
|
|
|
|
```bash
|
|
tea open # current repo
|
|
```
|
|
|
|
> `tea open` opens a browser window. It will **hang indefinitely** in headless/agent environments. The previous skill version listed `tea open <issue-number>`, `tea open pulls`, etc. — those positional forms do not appear in `tea open --help`; do not rely on them.
|
|
|
|
## Common end-to-end recipes
|
|
|
|
### Feature branch → PR
|
|
```bash
|
|
git checkout -b feature/x
|
|
# ... commits ...
|
|
git push -u origin feature/x
|
|
tea pulls create --title "Add X" --base main --head feature/x --description "$(cat pr.md)"
|
|
```
|
|
|
|
### Review and merge
|
|
```bash
|
|
tea pulls checkout 20
|
|
# ... local review ...
|
|
tea pulls approve 20 "LGTM"
|
|
tea pulls merge 20 --style squash
|
|
tea pulls clean 20 # cleanup branches
|
|
```
|
|
|
|
### 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
|
|
```
|
|
|
|
### Manage Actions secrets
|
|
```bash
|
|
tea actions secrets create STAGING_DEPLOY_TOKEN "$(cat ~/.staging-token)" \
|
|
--repo myorg/myrepo
|
|
tea actions workflows dispatch deploy.yml --ref staging --repo myorg/myrepo
|
|
```
|
|
|
|
### Admin: create service account
|
|
```bash
|
|
tea admin users create \
|
|
--username ci-bot --email ci-bot@example.com \
|
|
--password "$(openssl rand -base64 24)" \
|
|
--restricted --no-must-change-password
|
|
```
|