fj/README.md

# fgj - Forgejo CLI Tool

[![Go Version](https://img.shields.io/badge/Go-1.23+-00ADD8?style=flat-square&logo=go)](https://golang.org)
[![CI Status](https://codeberg.org/romaintb/fgj/actions/workflows/ci.yml/badge.svg)](https://codeberg.org/romaintb/fgj/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)

`fgj` is a command-line tool for working with Forgejo instances (including Codeberg.org). It brings pull requests, issues, and other Forgejo concepts to the terminal, similar to what `gh` does for GitHub.

## Features

- Multi-instance support (works with any Forgejo instance)
- Pull request management (create, list, view, merge)
- Issue tracking (create, list, view, comment, close)
- Repository operations (view, list, clone, fork)
- Forgejo Actions (workflow runs, secrets, variables)
- Automatic repository detection from git context
- Secure authentication with personal access tokens
- AI coding agent friendly

## Installation

[![Packaging status](https://repology.org/badge/vertical-allrepos/fgj.svg)](https://repology.org/project/fgj/versions)

### Arch Linux (AUR)

`fgj` is available in the Arch User Repository:

```bash
yay -S fgj
```

### macOS (Homebrew)

```bash
brew tap romaintb/fgj https://codeberg.org/romaintb/homebrew-fgj.git
brew install fgj
```

### Using Go Install

```bash
go install codeberg.org/romaintb/fgj@latest
```

### Other Distributions

We'd love your help packaging `fgj` for other distributions! If you're interested in creating packages for Debian, Ubuntu, Fedora, or any packaging systems, please open an issue or reach out.

## Quick Start

### 1. Authenticate

First, authenticate with your Forgejo instance:

```bash
fgj auth login
```

You'll be prompted for:
- Forgejo instance hostname (default: codeberg.org)
- Personal access token

To create a personal access token:
1. Go to your Forgejo instance (e.g., https://codeberg.org)
2. Navigate to Settings > Applications > Generate New Token
3. Give it appropriate permissions (repo, issue, etc.)
4. Copy the token and paste it when prompted

### 2. Check Authentication Status

```bash
fgj auth status
```

## Usage

### Repository Detection

`fgj` automatically detects the repository from your git context, similar to `gh`:

```bash
# When inside a git repository, no -R flag needed!
cd /path/to/your/repo
fgj pr list              # Automatically uses current repo
fgj issue list           # Automatically uses current repo
fgj pr view 123          # Automatically uses current repo

# Or explicitly specify a repository with -R
fgj pr list -R owner/repo
```

The tool reads `.git/config` to find the origin remote and extract both the owner/repo information and the Forgejo instance hostname. If you're not in a git repository, you'll need to use the `-R` flag.

### Pull Requests

```bash
# List pull requests (auto-detects repo and hostname from git)
fgj pr list

# Or specify explicitly
fgj pr list -R owner/repo

# Filter by state
fgj pr list --state closed

# View a specific pull request
fgj pr view 123

# Create a pull request
fgj pr create -t "PR Title" -b "PR Description" -H feature-branch -B main

# Merge a pull request
fgj pr merge 123 --merge-method squash
```

### Issues

```bash
# List issues (auto-detects repo and hostname from git)
fgj issue list

# Or specify explicitly
fgj issue list -R owner/repo

# Filter by state
fgj issue list --state all

# View an issue
fgj issue view 456

# Create an issue
fgj issue create -t "Issue Title" -b "Issue Description"

# Comment on an issue
fgj issue comment 456 -b "My comment"

# Close an issue
fgj issue close 456

# Close an issue with a comment
fgj issue close 456 -c "Fixed in v2.0"
```

### Repositories

```bash
# View repository details
fgj repo view owner/repo

# List your repositories
fgj repo list

# Clone a repository
fgj repo clone owner/repo

# Clone via SSH
fgj repo clone owner/repo -p ssh

# Fork a repository
fgj repo fork owner/repo
```

### Releases

```bash
# List releases
fgj release list

# View a release (or use "latest")
fgj release view v1.2.3

# Create a release with notes and optional assets
fgj release create v1.2.3 -t "v1.2.3" -n "Release notes" ./dist/app.tar.gz

# Upload assets to an existing release
fgj release upload v1.2.3 ./dist/app.tar.gz --clobber

# Delete a release (keeps the Git tag)
fgj release delete v1.2.3
```

### Forgejo Actions

```bash
# List workflows
fgj actions workflow list

# View a workflow
fgj actions workflow view ci.yml

# Run a workflow (trigger workflow_dispatch)
fgj actions workflow run deploy.yml

# Run a workflow with inputs
fgj actions workflow run deploy.yml -f environment=production -f version=1.2.3

# Run a workflow on a specific branch
fgj actions workflow run deploy.yml -r feature-branch

# List workflow runs
fgj actions run list

# View a specific run
fgj actions run view 123

# View run with job details
fgj actions run view 123 --verbose

# View run logs
fgj actions run view 123 --log

# View specific job logs
fgj actions run view 123 --job 456 --log

# List secrets
fgj actions secret list

# Create a secret
fgj actions secret create MY_SECRET

# Delete a secret
fgj actions secret delete MY_SECRET

# List variables
fgj actions variable list

# Get a variable
fgj actions variable get MY_VAR

# Create a variable
fgj actions variable create MY_VAR "value"

# Update a variable
fgj actions variable update MY_VAR "new value"

# Delete a variable
fgj actions variable delete MY_VAR
```

## Configuration

Configuration is stored in `~/.config/fgj/config.yaml`:

```yaml
hosts:
  codeberg.org:
    hostname: codeberg.org
    token: your_token_here
    user: your_username
    git_protocol: https
  my-forgejo.com:
    hostname: my-forgejo.com
    token: another_token
    user: another_username
    git_protocol: ssh
```

### Environment Variables

- `FGJ_HOST`: Override the default Forgejo instance (auto-detected from git remote if not set)
- `FGJ_TOKEN`: Provide authentication token

Hostname is resolved in this priority order:
1. Command-specific flags (e.g., `--hostname`)
2. `FGJ_HOST` environment variable
3. Auto-detected from git remote URL
4. Default to `codeberg.org`

### Command-line Flags

- `--hostname`: Specify Forgejo instance for a command (overrides auto-detection and environment variables)
- `--config`: Use a custom config file

When working in a git repository, `fgj` automatically detects the Forgejo instance from your origin remote URL, so you typically don't need to specify `--hostname` unless working with multiple instances.

## Use with AI Coding Agents

`fgj` is designed to work seamlessly with AI coding agents like Claude Code. Common patterns:

```bash
# Create PR from agent's changes
fgj pr create -R owner/repo -t "feat: add new feature" -b "$(cat <<EOF
## Summary
- Added new feature X
- Fixed bug Y

Generated with AI assistance
EOF
)"

# Check PR status during development
fgj pr list -R owner/repo --state open

# View PR details for review
fgj pr view 123 -R owner/repo
```

## Supported Forgejo Instances

`fgj` works with any Forgejo instance, including:

- [Codeberg.org](https://codeberg.org) (default)
- Self-hosted Forgejo instances
- Gitea instances (compatible API)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Missing Features / Roadmap

`fgj` aims to be a drop-in replacement for `gh` when working with Forgejo instances. While we've implemented the core features, some `gh` commands are not yet available:

### Forgejo Actions / Workflows

**Not Yet Implemented:**
- `workflow enable/disable` - Enable or disable workflows
- `run watch` - Follow a workflow run in real-time
- `run rerun` - Rerun entire run, failed jobs, or specific jobs
- `run cancel` - Cancel a running workflow
- `run delete` - Delete a workflow run
- `run download` - Download workflow run artifacts

We welcome contributions to implement any of these features! Please check the issues or create a new one to discuss implementation before starting work.

## License

MIT License