# gitea-ci Cheatsheet

## Quick Reference

```
┌────────────────────────────────────────────────────────────────────────────┐
│ SETUP
├────────────────────────────────────────────────────────────────────────────┤
│ export GITEA_URL="https://gitea.example.com"
│ export GITEA_TOKEN="your-token"
│ gitea-ci config --test                     Verify connectivity
└────────────────────────────────────────────────────────────────────────────┘
```

## Common Tasks

```
┌──────────────────────────┬─────────────────────────────────────────────────┐
│ Task                     │ Command
├──────────────────────────┼─────────────────────────────────────────────────┤
│ List runs                │ gitea-ci list owner/repo
│ List failed only         │ gitea-ci list --failed
│ Show run status          │ gitea-ci status owner/repo 123
│ View logs                │ gitea-ci logs -R 123
│ Watch live               │ gitea-ci watch owner/repo
│ Trigger workflow         │ gitea-ci trigger -w deploy.yml
│ Re-run failed            │ gitea-ci rerun -R 123 -f
│ Cancel run               │ gitea-ci cancel -R 123
│ Validate workflows       │ gitea-ci validate
└──────────────────────────┴─────────────────────────────────────────────────┘
```

## Commands at a Glance

```
┌─────────────────┬────────┬──────────────────────────────────────────────────┐
│ Command         │ Alias  │ Purpose
├─────────────────┼────────┼──────────────────────────────────────────────────┤
│ list            │ ls l   │ List workflow runs
│ status          │ s      │ Show run details
│ logs            │ log    │ View job logs
│ watch           │ w      │ Live watch runs
│ stats           │        │ Statistics with graphs
│ trigger         │ t      │ Trigger workflow_dispatch
│ rerun           │        │ Re-run workflow/jobs
│ cancel          │        │ Cancel running workflow
│ delete          │ rm     │ Delete workflow run
│ artifacts       │ art    │ List/download artifacts
│ pr              │        │ PR CI status
│ compare         │ diff   │ Compare two runs
│ workflows       │ wf     │ List workflow files
│ validate        │ lint   │ Validate local workflows
│ runners         │        │ Manage runners
│ register-token  │ regtoken│ Get registration token
│ config          │        │ Configure tool
│ repo            │        │ Repository operations
│ infra           │        │ Infrastructure status
└─────────────────┴────────┴──────────────────────────────────────────────────┘
```

## Flags

```
┌────────────────────────┬────────────────────────────────────────────────────┐
│ Flag                   │ Meaning
├────────────────────────┼────────────────────────────────────────────────────┤
│ -o, --owner            │ Repository owner
│ -r, --repo             │ Repository name
│ -R, --run              │ Run ID
│ -j, --job              │ Job ID
│ -n, --limit            │ Number of items
│ -b, --branch           │ Branch filter
│ -w, --workflow         │ Workflow file
│ -i, --input            │ Workflow input (key=value)
│ -f, --force            │ Skip confirmation
│ --json                 │ JSON output
│ --compact              │ Single-line output
└────────────────────────┴────────────────────────────────────────────────────┘
```

## Status Symbols

```
✓  success       ●  running       ◌  queued
✗  failure       ○  pending       ⊘  cancelled/skipped
```

## Patterns

### After git push

```sh
git push && gitea-ci watch --notify
```

### Check last run status

```sh
gitea-ci list --compact | head -1
```

### Re-run latest failed

```sh
gitea-ci rerun -R "$(gitea-ci list --failed --compact | head -1 | awk '{print $1}')" -f
```

### Validate before commit

```sh
gitea-ci validate --strict && git commit -m "message"
```

### Export run data

```sh
gitea-ci list --json > runs.json
gitea-ci status -R 123 --json | jq '.jobs[].name'
```

### Watch with timeout

```sh
gitea-ci watch -t 600 --notify  # 10 min timeout
```

### Get artifact

```sh
gitea-ci artifacts -R 123
gitea-ci artifacts -d 456 -O build.zip
```

## Environment

```
GITEA_URL      Gitea instance URL
GITEA_TOKEN    API authentication token
NO_COLOR       Disable colors when set
```

## Config File

`~/.config/gitea-ci/config.json`

```json
{
  "url": "https://gitea.example.com",
  "token": "...",
  "default_owner": "myorg",
  "default_repo": "myproject"
}
```

## Package Structure

```
gitea-ci.py                  Wrapper script (entry point)
style.py                     Styling utilities
src/gitea_ci/
├── cli.py                   Argument parser, dispatch
├── config.py                Configuration
├── api.py                   Gitea API client
├── formatters.py            Output formatting
├── utils.py                 Utilities
└── commands/                Command implementations
```

## Validation

```sh
python3 -m py_compile src/gitea_ci/*.py     # Syntax check
./gitea-ci.py --help                        # Test CLI
python3 -m gitea_ci --help                  # Module mode (PYTHONPATH=src)
```