public/fj
1
0
Fork 0
Code Issues 3 Pull requests Projects Releases 1 Packages Wiki Activity Actions 1

feat: v0.3.0a — add api command, pr diff/comment/review, structured errors

Browse source 
New commands:
- fgj api: raw REST API passthrough with field inference and path interpolation
- fgj pr diff: view PR diffs with color, --name-only, --stat
- fgj pr comment: add comments to pull requests
- fgj pr review: approve, request changes, or comment on PRs

Agentic enhancements:
- --json-errors flag for structured JSON error output on stderr
- APIError type wrapping HTTP status codes for machine consumption
- Error codes: auth_required, not_found, api_error, invalid_input, etc.

Docs updated for forgejo.zerova.net/sid/fgj-sid fork.
This commit is contained in:
sid 2026-03-21 21:50:24 -06:00
parent 50191cc542
commit 43e43e7024
17 changed files with 64 additions and 64 deletions
Download patch file Download diff file Expand all files Collapse all files

75
README.md
View file

@ -1,14 +1,15 @@
# fgj - Forgejo CLI Tool
# fgj - Forgejo/Gitea 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.
`fgj` is a command-line tool for working with Forgejo and Gitea instances. It brings pull requests, issues, and other forge concepts to the terminal, similar to what `gh` does for GitHub. This fork adds agentic dev features — raw API access, PR review workflows, structured error output, and machine-readable I/O for AI coding agents.
> Forked from [codeberg.org/romaintb/fgj](https://codeberg.org/romaintb/fgj) and hosted at [forgejo.zerova.net/sid/fgj-sid](https://forgejo.zerova.net/sid/fgj-sid).
## Features
- Multi-instance support (works with any Forgejo instance)
- Multi-instance support (works with any Forgejo or Gitea instance)
- Pull request management (create, list, view, merge, diff, comment, review)
- Issue tracking (create, list, view, comment, close, labels)
- Repository operations (view, list, create, clone, fork)
@ -25,49 +26,43 @@
## 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 tap sid/fgj-sid https://forgejo.zerova.net/sid/homebrew-fgj-sid.git
brew install fgj
```
### Using Go Install
```bash
go install codeberg.org/romaintb/fgj@latest
go install forgejo.zerova.net/sid/fgj-sid@latest
```
### Other Distributions
### From Source
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.
```bash
git clone https://forgejo.zerova.net/sid/fgj-sid.git
cd fgj-sid
go build -o fgj .
```
## Quick Start
### 1. Authenticate
First, authenticate with your Forgejo instance:
First, authenticate with your Forgejo or Gitea instance:
```bash
fgj auth login
```
You'll be prompted for:
- Forgejo instance hostname (default: codeberg.org)
- 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)
1. Go to your instance (e.g., https://forgejo.zerova.net)
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
@ -105,7 +100,7 @@ fgj pr view 123 # Automatically uses current repo
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.
The tool reads `.git/config` to find the origin remote and extract both the owner/repo information and the instance hostname. If you're not in a git repository, you'll need to use the `-R` flag.
### Pull Requests
@ -376,21 +371,21 @@ Configuration is stored in `~/.config/fgj/config.yaml`:
```yaml
hosts:
codeberg.org:
hostname: codeberg.org
forgejo.zerova.net:
hostname: forgejo.zerova.net
token: your_token_here
user: your_username
git_protocol: https
my-forgejo.com:
hostname: my-forgejo.com
git_protocol: ssh
codeberg.org:
hostname: codeberg.org
token: another_token
user: another_username
git_protocol: ssh
git_protocol: https
```
### Environment Variables
- `FGJ_HOST`: Override the default Forgejo instance (auto-detected from git remote if not set)
- `FGJ_HOST`: Override the default instance (auto-detected from git remote if not set)
- `FGJ_TOKEN`: Provide authentication token
Hostname is resolved in this priority order:
@ -401,10 +396,10 @@ Hostname is resolved in this priority order:
### Command-line Flags
- `--hostname`: Specify Forgejo instance for a command (overrides auto-detection and environment variables)
- `--hostname`: Specify 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.
When working in a git repository, `fgj` automatically detects the 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
@ -442,21 +437,21 @@ fgj api /repos/{owner}/{repo}/labels -X POST -f name=agent-reviewed -f color="#0
fgj pr view 9999 --json --json-errors 2>errors.json
```
## Supported Forgejo Instances
## Supported Instances
`fgj` works with any Forgejo instance, including:
`fgj` works with any Forgejo or Gitea instance, including:
- [Codeberg.org](https://codeberg.org) (default)
- Self-hosted Forgejo instances
- Gitea instances (compatible API)
- Self-hosted Gitea instances
- [Codeberg.org](https://codeberg.org)
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Contributions are welcome! Please feel free to submit a Pull Request at [forgejo.zerova.net/sid/fgj-sid](https://forgejo.zerova.net/sid/fgj-sid).
## 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:
`fgj` aims to be a drop-in replacement for `gh` when working with Forgejo and Gitea instances. While we've implemented the core features, some `gh` commands are not yet available:
**Not Yet Implemented:**
- `run delete` - Delete a workflow run
@ -467,7 +462,11 @@ Contributions are welcome! Please feel free to submit a Pull Request.
- `release edit`, `release download`, `release generate-notes`
- `repo delete`, `repo rename`, `repo visibility`
We welcome contributions to implement any of these features! Please check the issues or create a new one to discuss implementation before starting work.
We welcome contributions to implement any of these features!
## Acknowledgments
Based on [fgj by romaintb](https://codeberg.org/romaintb/fgj). Enhanced with agentic dev features for AI-assisted workflows.
## License