fj/README.md

fgj - Forgejo/Gitea CLI Tool

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 and hosted at forgejo.zerova.net/sid/fgj-sid.

Features

• 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)
• Forgejo Actions (workflow runs, watch/rerun/cancel, enable/disable, secrets, variables)
• Releases (create, upload, delete)
• Raw API access (fgj api) for arbitrary REST calls
• Shell completions (bash, zsh, fish, PowerShell) and man pages
• JSON output (--json) for all list/view commands
• Structured JSON error output (--json-errors) for machine consumption
• Automatic repository and hostname detection from git context
• Secure authentication with personal access tokens
• XDG Base Directory compliant config location
• AI coding agent friendly

Installation

macOS (Homebrew)

brew tap sid/fgj-sid https://forgejo.zerova.net/sid/homebrew-fgj-sid.git
brew install fgj

Using Go Install

go install forgejo.zerova.net/sid/fgj-sid@latest

From Source

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 or Gitea instance:

fgj auth login

You'll be prompted for:

• Instance hostname (default: codeberg.org)
• Personal access token

To create a personal access token:

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

2. Check Authentication Status

fgj auth status

Auth Helpers

# Print the stored token for the current host
fgj auth token

# Remove authentication for a host
fgj auth logout

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

# View PR diff
fgj pr diff 123

# View diff with color
fgj pr diff 123 --color always

# Show only changed file names
fgj pr diff 123 --name-only

# Show diffstat summary
fgj pr diff 123 --stat

# Comment on a pull request
fgj pr comment 123 -b "Looks good, minor nit on line 42"

# Comment from a file
fgj pr comment 123 --body-file review-notes.md

# Approve a pull request
fgj pr review 123 --approve -b "LGTM"

# Request changes
fgj pr review 123 --request-changes -b "Please fix the error handling"

# Submit a review comment (neither approve nor request changes)
fgj pr review 123 --comment -b "Some observations"

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"

# Create an issue with labels
fgj issue create -t "Issue Title" -b "Issue Description" -l bug -l enhancement

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

# Edit an issue (title, body, state, labels)
fgj issue edit 456 -t "New Title"
fgj issue edit 456 --add-label priority --remove-label bug

Repositories

# View repository details
fgj repo view owner/repo

# List your repositories
fgj repo list

# Create a repository
fgj repo create my-repo
fgj repo create my-repo -d "My project" --private --add-readme -g Go -l MIT

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

# Enable or disable a workflow
fgj actions workflow enable ci.yml
fgj actions workflow disable ci.yml

# 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

# Watch a run until completion
fgj actions run watch 123

# Rerun a workflow run
fgj actions run rerun 123

# Cancel a running workflow
fgj actions run cancel 123

# 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

Raw API Access

# GET request (auto-detects owner/repo from git context)
fgj api /repos/{owner}/{repo}/pulls

# POST with fields
fgj api /repos/{owner}/{repo}/issues -X POST -f title="Bug report" -f body="Description"

# Explicit method and hostname
fgj api /repos/myorg/myrepo/labels --hostname my-forgejo.example.com

# Read request body from file
fgj api /repos/{owner}/{repo}/issues -X POST --input issue.json

# Read from stdin
echo '{"title":"test"}' | fgj api /repos/{owner}/{repo}/issues -X POST --input -

# Include response headers
fgj api /repos/{owner}/{repo} -i

# Suppress output (useful for DELETE)
fgj api /repos/{owner}/{repo}/issues/123 -X DELETE --silent

Shell Completions and Man Pages

# Generate shell completion scripts
fgj completion bash > /etc/bash_completion.d/fgj
fgj completion zsh > "${fpath[1]}/_fgj"
fgj completion fish > ~/.config/fish/completions/fgj.fish

# Generate man pages to a directory
fgj manpages --dir ~/.local/share/man/man1

JSON Output

Most list and view commands support --json for machine-readable output:

fgj pr list --json
fgj issue view 456 --json
fgj release list --json
fgj actions run list --json
fgj actions workflow view ci.yml --json

# Get JSON output from PR comment/review
fgj pr comment 123 -b "LGTM" --json
fgj pr review 123 --approve -b "Ship it" --json

Structured Error Output

For machine consumption (ideal for AI agents and scripts), use --json-errors to get structured JSON errors on stderr:

# Errors are written to stderr as JSON
fgj pr view 9999 --json-errors
# stderr: {"error":{"code":"not_found","message":"...","status":404}}

# Combine with --json for fully machine-readable I/O
fgj pr list --json --json-errors

Configuration

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

hosts:
  forgejo.zerova.net:
    hostname: forgejo.zerova.net
    token: your_token_here
    user: your_username
    git_protocol: ssh
  codeberg.org:
    hostname: codeberg.org
    token: another_token
    user: another_username
    git_protocol: https

Environment Variables

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

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 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 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. Use --json and --json-errors for fully machine-readable I/O:

# 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
)" --json

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

# Review a PR diff, then approve
fgj pr diff 123
fgj pr review 123 --approve -b "LGTM" --json

# Post review feedback
fgj pr comment 123 -b "Consider using a map here for O(1) lookup" --json

# Request changes with detailed feedback
fgj pr review 123 --request-changes --body-file feedback.md --json

# Use raw API for anything not covered by commands
fgj api /repos/{owner}/{repo}/topics --json-errors
fgj api /repos/{owner}/{repo}/labels -X POST -f name=agent-reviewed -f color="#00ff00"

# Fully machine-readable error handling
fgj pr view 9999 --json --json-errors 2>errors.json

Supported Instances

fgj works with any Forgejo or Gitea instance, including:

• Self-hosted Forgejo instances
• Self-hosted Gitea instances
• Codeberg.org

Contributing

Contributions are welcome! Please feel free to submit a Pull Request at forgejo.zerova.net/sid/fgj-sid.

Missing Features / Roadmap

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
• run download - Download workflow run artifacts
• pr checkout, pr close/reopen
• pr checks, pr ready/draft
• issue reopen, issue assign
• release edit, release download, release generate-notes
• repo delete, repo rename, repo visibility

We welcome contributions to implement any of these features!

Acknowledgments

Based on fgj by romaintb. Enhanced with agentic dev features for AI-assisted workflows.

License

MIT License