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