# Forgejo Instance Setup Guide

This document describes how to set up and work with a Forgejo instance from scratch.

## 1. Create an Account

### Via Web UI
1. Go to your Forgejo instance URL (e.g., `https://vmd185580.tailf38284.ts.net`)
2. Click **Sign Up** or **Register**
3. Fill in:
   - Username (e.g., `nazim`)
   - Email address
   - Password
4. Complete CAPTCHA if required
5. Check email for verification link (if email is enabled)

### Via API (Admin-only)
Regular users cannot create accounts via API. Contact an admin or use the web UI.

## 2. Install `tea` CLI

### macOS
```bash
brew install tea-org/tea/tea
```

### Linux (amd64)
```bash
# Download latest release
curl -sL https://github.com/tea-org/tea/releases/latest/download/tea-linux-amd64.tar.gz | tar xz -C /tmp
sudo mv /tmp/tea /usr/local/bin/
sudo chmod +x /usr/local/bin/tea
```

### Linux (arm64)
```bash
curl -sL https://github.com/tea-org/tea/releases/latest/download/tea-linux-arm64.tar.gz | tar xz -C /tmp
sudo mv /tmp/tea /usr/local/bin/
sudo chmod +x /usr/local/bin/tea
```

### Verify Installation
```bash
tea --version
# Expected: Version: [1m0.12.0[0m  golang: 1.25.7  go-sdk: v0.23.2
```

## 3. Configure Login

### Get a Personal Access Token

1. Log in to your Forgejo instance via web UI
2. Go to **Settings** → **Application**
3. Click **Add Access Token**
4. Fill in:
   - Token name: e.g., `tea-cli`
   - Select scopes (minimum required):
     - `read:user` — View user profile
     - `write:repository` — Create and manage repos
   - Click **Generate Token**
5. Copy the generated token (you won't see it again!)

### Save to `tea` Config

The config file is at:
- Linux/macOS: `~/.config/tea/config.yml`
- Windows: `%AppData%\tea\config.yml`

#### Example Config
```yaml
logins:
- name: vmd185580
  url: https://vmd185580.tailf38284.ts.net
  token: <your-generated-token-here>
  default: true
  ssh_host: vmd185580.tailf38284.ts.net
  ssh_key: ""
  insecure: false
  user: nazim
  created: <unix-timestamp>
preferences:
  editor: false
  flag_defaults:
    remote: ""
```

#### Get Current Unix Timestamp
```bash
date +%s
# Example output: 1776359800
```

### Test Connection
```bash
tea whoami
# Expected output:
# # nazim                                                                     
# Follower Count: 0, Following Count: 0, Starred Repos: 0
```

## 4. Common Tasks

### List Logins
```bash
tea login list
```

### Create a Repository
```bash
tea repos create --name my-repo \
  --description "My project" \
  --init \
  --license mit
```

### Clone a Repository
```bash
tea clone nazim/my-repo
# or
git clone https://vmd185580.tailf38284.ts.net/nazim/my-repo.git
```

### List Repositories
```bash
tea repos list --mine
```

### Create an Issue
```bash
tea issues create --repo nazim/my-repo \
  --title "Bug: Something is wrong" \
  --body "Steps to reproduce..."
```

### Create a Pull Request
```bash
tea pr create --repo nazim/my-repo \
  --title "Fix: Something was wrong" \
  --body "This PR fixes the issue." \
  --head feature-branch
```

## 5. SSH Access (Optional)

If you want to use SSH instead of HTTPS:

### Generate SSH Key
```bash
ssh-keygen -t ed25519 -C "nazim@openclaw.ai" -f ~/.ssh/vmd185580
```

### Add Public Key to Forgejo
```bash
cat ~/.ssh/vmd185580.pub
# Copy output to Forgejo → Settings → SSH Keys
```

### Configure Git SSH Host
```bash
# Add to ~/.ssh/config
Host vmd185580.tailf38284.ts.net
  HostName vmd185580.tailf38284.ts.net
  User git
  Port 222
  IdentityFile ~/.ssh/vmd185580
```

### Clone via SSH
```bash
git clone ssh://git@vmd185580.tailf38284.ts.net:222/nazim/my-repo.git
```

## 6. Troubleshooting

### Token Scope Errors
If you see `token does not have at least one of required scope(s)`, add more scopes to your token via Forgejo web UI → Settings → Application.

### Connection Timeouts
- Check if the instance is reachable: `ping vmd185580.tailf38284.ts.net`
- Check TLS: `curl -v https://vmd185580.tailf38284.ts.net`
- Check API: `curl https://vmd185580.tailf38284.ts.net/api/v1/version`

### Wrong Login Used
Set the default login in config or use `--login` flag:
```bash
tea whoami --login vmd185580
```

## 7. Scope Reference

| Scope | Description |
|-------|-------------|
| `read:user` | View user profile and followers |
| `write:repository` | Create, update, delete repositories |
| `read:repository` | Read repository contents (public) |
| `write:organization` | Manage organizations |
| `admin:org` | Admin-level org access |

## 8. Example Workflow

```bash
# 1. Create repo
tea repos create --name krallen-skills \
  --description "Forgejo instance skills" \
  --init

# 2. Clone locally
git clone https://vmd185580.tailf38284.ts.net/nazim/krallen-skills.git

# 3. Add content
cd krallen-skills
echo "# Krallen Skills" > README.md

# 4. Push changes
git add .
git commit -m "Initial commit"
git push origin main
```