Hugo Nijhuis
e2198c0d8e
Documents that tea CLI uses --description/-d flag for PR body content, not --body like the gh CLI. This helps avoid failed commands when transitioning from gh CLI. Closes #5 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
184 lines
4.9 KiB
Markdown
184 lines
4.9 KiB
Markdown
# Gitea CLI (tea)
|
|
|
|
Command-line interface for interacting with Gitea repositories.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
brew install tea
|
|
```
|
|
|
|
## Authentication
|
|
|
|
The `tea` CLI authenticates via `tea logins add`. Credentials are stored locally by tea.
|
|
|
|
```bash
|
|
tea logins add # Interactive login
|
|
tea logins add --url <url> --token <token> --name <name> # Non-interactive
|
|
tea logins list # Show configured logins
|
|
tea logins default <name> # Set default login
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Config is stored at `~/Library/Application Support/tea/config.yml` (macOS).
|
|
|
|
To avoid needing `--login` on every command, set defaults:
|
|
|
|
```yaml
|
|
preferences:
|
|
editor: false
|
|
flag_defaults:
|
|
remote: origin
|
|
login: git.flowmade.one
|
|
```
|
|
|
|
## Repository Detection
|
|
|
|
`tea` automatically detects the repository from git remotes when run inside a git repository. Use `--remote <name>` to specify which remote to use.
|
|
|
|
## Common Commands
|
|
|
|
### Issues
|
|
|
|
```bash
|
|
# List issues
|
|
tea issues # Open issues (default)
|
|
tea issues --state all # All issues
|
|
tea issues --state closed # Closed issues
|
|
|
|
# View issue details
|
|
tea issues <number> # Full issue details
|
|
tea issues <number> --comments # Include comments
|
|
|
|
# Create issue
|
|
tea issues create --title "<title>" --description "<body>"
|
|
tea issues create -t "<title>" -d "<body>"
|
|
|
|
# Edit issue
|
|
tea issues edit <number> --title "<new-title>"
|
|
tea issues edit <number> --description "<new-body>"
|
|
|
|
# Close/reopen
|
|
tea issues close <number>
|
|
tea issues reopen <number>
|
|
|
|
# Labels
|
|
tea issues edit <number> --labels "bug,help wanted"
|
|
```
|
|
|
|
### Pull Requests
|
|
|
|
```bash
|
|
# List PRs
|
|
tea pulls # Open PRs (default)
|
|
tea pulls --state all # All PRs
|
|
tea pulls --state closed # Closed/merged PRs
|
|
|
|
# View PR
|
|
tea pulls <number> # PR details
|
|
tea pulls <number> --comments # Include comments
|
|
tea pulls <number> -f diff # PR diff
|
|
|
|
# Create PR
|
|
tea pulls create --title "<title>" --description "<body>"
|
|
tea pulls create -t "<title>" -d "<body>"
|
|
tea pulls create -t "<title>" -d "Closes #<issue>"
|
|
tea pulls create --head <branch> --base main -t "<title>"
|
|
|
|
# Checkout PR locally
|
|
tea pulls checkout <number>
|
|
|
|
# Review/Approve
|
|
tea pulls approve <number> # Approve PR (LGTM)
|
|
tea pulls reject <number> # Request changes
|
|
tea pulls review <number> # Interactive review
|
|
|
|
# Merge
|
|
tea pulls merge <number> # Default merge
|
|
tea pulls merge <number> --style squash # Squash commits
|
|
tea pulls merge <number> --style rebase # Rebase commits
|
|
tea pulls merge <number> --style rebase-merge # Rebase then merge
|
|
|
|
# Clean up after merge
|
|
tea pulls clean <number> # Delete local & remote branch
|
|
```
|
|
|
|
### Repository
|
|
|
|
```bash
|
|
tea repos # List repos
|
|
tea repos <owner>/<repo> # Repository info
|
|
tea clone <owner>/<repo> # Clone repository
|
|
```
|
|
|
|
### Comments
|
|
|
|
```bash
|
|
# Add comment to issue or PR
|
|
tea comment <number> "<comment body>"
|
|
tea comment 3 "LGTM, ready to merge"
|
|
|
|
# Multiline comments (use heredoc)
|
|
tea comment 3 "$(cat <<'EOF'
|
|
## Review Summary
|
|
- Code looks good
|
|
- Tests pass
|
|
EOF
|
|
)"
|
|
```
|
|
|
|
### Notifications
|
|
|
|
```bash
|
|
tea notifications # List notifications
|
|
tea notifications --mine # Only participating
|
|
```
|
|
|
|
## Output Formatting
|
|
|
|
Most commands support `--output` or `-o` flag:
|
|
- `-o simple` - Plain text
|
|
- `-o table` - Tabular format (default)
|
|
- `-o json` - Machine-readable JSON
|
|
- `-o yaml` - YAML format
|
|
- `-o csv` - CSV format
|
|
|
|
## Specifying Remote/Login
|
|
|
|
```bash
|
|
tea issues --remote gitea # Use specific git remote
|
|
tea issues --login myserver # Use specific login
|
|
tea issues -r owner/repo # Specify repo directly
|
|
```
|
|
|
|
## Tips
|
|
|
|
- **View single issue**: Use `tea issues <number>` (NOT `tea issues view <number>` - there is no `view` subcommand)
|
|
- **PR description flag**: Use `--description` or `-d` (NOT `--body` like gh CLI)
|
|
- Always verify you're in the correct repository before running commands
|
|
- Use `tea issues` to find issue numbers before viewing/editing
|
|
- Reference issues in PR bodies with `Closes #N` for auto-linking
|
|
- Use `--remote gitea` when you have multiple remotes (e.g., origin + gitea)
|
|
- The `tea pulls checkout` command is handy for reviewing PRs locally
|
|
|
|
## Actions / CI
|
|
|
|
```bash
|
|
# List workflow runs
|
|
tea actions runs # List all workflow runs
|
|
tea actions runs -o json # JSON output for parsing
|
|
|
|
# List jobs for a run
|
|
tea actions jobs <run-id> # Show jobs for a specific run
|
|
tea actions jobs <run-id> -o json # JSON output
|
|
|
|
# Get job logs
|
|
tea actions logs <job-id> # Display logs for a job
|
|
|
|
# Full workflow: find failed job logs
|
|
tea actions runs # Find the run ID
|
|
tea actions jobs <run-id> # Find the job ID
|
|
tea actions logs <job-id> # View the logs
|
|
```
|