fgj - Forgejo CLI Tool

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)
• Secure authentication with personal access tokens
• AI coding agent friendly

Installation

From Source

git clone https://codeberg.org/romaintb/fgj.git
cd fgj
go build -o fgj
sudo mv fgj /usr/local/bin/

Using Go Install

go install codeberg.org/romaintb/fgj@latest

Quick Start

1. Authenticate

First, authenticate with your Forgejo instance:

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

fgj auth status

Usage

Pull Requests

# List pull requests
fgj pr list -R owner/repo

# View a specific pull request
fgj pr view 123 -R owner/repo

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

# Merge a pull request
fgj pr merge 123 -R owner/repo --merge-method squash

Issues

# List issues
fgj issue list -R owner/repo

# View an issue
fgj issue view 456 -R owner/repo

# Create an issue
fgj issue create -R owner/repo -t "Issue Title" -b "Issue Description"

# Comment on an issue
fgj issue comment 456 -R owner/repo -b "My comment"

# Close an issue
fgj issue close 456 -R owner/repo

Repositories

# 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

Configuration

Configuration is stored in ~/.config/fgj/config.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
• FGJ_TOKEN: Provide authentication token

Command-line Flags

• --hostname: Specify Forgejo instance for a command
• --config: Use a custom config file

Use with AI Coding Agents

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

# 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 (default)
• Self-hosted Forgejo instances
• Gitea instances (compatible API)

Development

Building

go build -o fgj

Testing

go test ./...

Project Structure

fgj/
├── cmd/                 # Command implementations
│   ├── root.go         # Root command and config
│   ├── auth.go         # Authentication commands
│   ├── pr.go           # Pull request commands
│   ├── issue.go        # Issue commands
│   └── repo.go         # Repository commands
├── internal/
│   ├── api/            # API client wrapper
│   └── config/         # Configuration management
├── main.go             # Entry point
└── go.mod              # Dependencies

Contributing

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

License

MIT License

Acknowledgments

• Inspired by GitHub's gh CLI tool
• Built using the Gitea SDK (compatible with Forgejo)
• Uses Cobra for CLI framework