fgj command - codeberg.org/romaintb/fgj

README ¶

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)
Forgejo Actions (workflow runs, secrets, variables)
Automatic repository detection from git context
Secure authentication with personal access tokens
AI coding agent friendly

Installation

Arch Linux (AUR)

fgj is available in the Arch User Repository:

yay -S fgj

macOS (Homebrew)

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

Using Go Install

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:

fgj auth login

You'll be prompted for:

Forgejo instance hostname (default: codeberg.org)
Personal access token

To create a personal access token:

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

2. Check Authentication Status

fgj auth status

Usage

Repository Detection

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

# 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

# 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

# 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

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

Releases

# 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

# 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:

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:

Command-specific flags (e.g., --hostname)
FGJ_HOST environment variable
Auto-detected from git remote URL
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:

# 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
│   └── git/            # Git repository detection
├── main.go             # Entry point
└── go.mod              # Dependencies