Forgejo CLI tool - work seamlessly with Forgejo and Codeberg from the command line. Like gh for GitHub, but for Forgejo instances.
  • Go 99.5%
  • Makefile 0.5%
Find a file
2026-11-04 08:14:14 +01:00
.gitea/workflows chore: setup custom ci runners 2026-07-15 10:10:08 +02:00
cmd fix(test): isolate user config and FGJ_* env vars during go test 2026-11-01 21:20:56 +09:00
internal fix(test): isolate user config and FGJ_* env vars during go test 2026-11-01 21:20:56 +09:00
tests/functional fix: add confirmation prompt to release delete 2026-04-14 14:48:40 +02:00
.editorconfig tools: add a basic .editorconfig 2026-01-05 12:57:57 +01:00
.gitignore chore: ignore dist/ release output 2026-10-26 08:47:12 +01:00
.golangci.yml chore: setup CI 2025-12-08 09:56:54 +01:00
CHANGELOG.md chore: release v0.6.1 2026-11-04 08:06:42 +01:00
CONTRIBUTORS.md docs: add contributors 2026-04-20 10:41:28 +02:00
go.mod feat: add actions workflow enable and disable 2026-01-18 13:11:41 +01:00
go.sum feat: add actions workflow enable and disable 2026-01-18 13:11:41 +01:00
LICENSE docs: update license date, and use my real name 2026-09-11 14:30:04 +02:00
main.go feat: initial version of the project 2025-12-08 09:49:07 +01:00
Makefile build: add openbsd and netbsd targets 2026-10-26 11:11:35 +01:00
README.md feat(config): add per-host token_cmd to read the token from a command 2026-10-25 12:56:47 +01:00

fgj - Forgejo CLI Tool

Go Version CI Status License: MIT

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, edit, merge, checkout, comment)
  • Issue tracking (create, list, view, comment, close, labels)
  • Repository operations (view, list, create, clone, fork)
  • Forgejo Actions (workflow runs, watch/rerun/cancel, enable/disable, runners, secrets, variables)
  • Generic authenticated API access (fgj api, like gh api) for any endpoint fgj has no dedicated command for
  • Releases (create, upload, delete)
  • Milestones (create, list, edit, delete)
  • Labels (create, list, edit, delete)
  • Shell completions (bash, zsh, fish, PowerShell) and man pages
  • JSON output (--json) for all list/view commands
  • 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

Packaging status

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 use SSH clone URLs, add -p ssh (see Git protocol).

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

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

# Prefix it with the instance when several are configured (like gh)
fgj pr list -R forge.example.com/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 (head branch defaults to current branch)
fgj pr create -t "PR Title" -b "PR Description" -B main

# Create a pull request with the body from a file (or stdin with -)
fgj pr create -t "PR Title" -F body.md

# Create a pull request with explicit head branch
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

# Edit a pull request's title and body
fgj pr edit 123 -t "New title" -b "New description"

# Edit a pull request's body from a file (or stdin with -)
fgj pr edit 123 -F body.md

# Change the base branch
fgj pr edit 123 -B main

# Manage labels and assignees
fgj pr edit 123 --add-label bug --remove-label wontfix
fgj pr edit 123 --add-assignee @me --remove-assignee someone

# Manage reviewers
fgj pr edit 123 --add-reviewer monalisa --remove-reviewer hubot

# Comment on a pull request
fgj pr comment 123 -b "LGTM"

# Comment with body from a file (or stdin with -)
fgj pr comment 123 -F review.md

# Close a pull request
fgj pr close 123

# Close a pull request with a comment and delete the branch
fgj pr close 123 -c "Merged, thanks!" -d

# Reopen a closed pull request
fgj pr reopen 123

# Reopen with a comment
fgj pr reopen 123 -c "Reopening to address feedback"

# Check out a pull request locally (alias: co)
fgj pr checkout 123

# Pick a custom local branch name
fgj pr checkout 123 -b review/pr-123

# Reset an existing local branch that has diverged from the PR
fgj pr checkout 123 --force

# Check out with a detached HEAD (no local branch created)
fgj pr checkout 123 --detach

# Check out a PR from a different repository (works for forks too)
fgj pr checkout 123 -R owner/repo

# Show open PRs relevant to you: current branch, created by you, assigned to you
fgj pr status

# Status for a different repository
fgj pr status -R owner/repo

# Show the diff of a pull request
fgj pr diff 123

# Diff of the PR for the current branch
fgj pr diff

# Patch format, or just the changed file names
fgj pr diff 123 --patch
fgj pr diff 123 --name-only

# Cap PRs fetched per section (default 30)
fgj pr status -L 10

# JSON output for scripting
fgj pr status --json

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

# Filter by label (repeatable or comma-separated)
fgj issue list -l bug
fgj issue list -l bug,enhancement

# Limit how many are fetched (default 30, 0 for all)
fgj issue list -L 100
fgj issue list --limit 0

# Filter by assignee (@me is you) or search title, body, and comments
fgj issue list -a @me
fgj issue list -S "login timeout" --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 the body from a file (or stdin with -)
fgj issue create -t "Issue Title" -F body.md

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

# Create an issue in a milestone
fgj issue create -t "Issue Title" -m "v1.0"

# Comment on an issue
fgj issue comment 456 -b "My comment"
fgj issue comment 456 -F comment.md

# Close an issue
fgj issue close 456

# Close an issue with a comment
fgj issue close 456 -c "Fixed in v2.0"

# Reopen an issue
fgj issue reopen 456

# Reopen an issue with a comment
fgj issue reopen 456 -c "Still reproducible"

# Edit an issue (title, body, state, labels, milestone)
fgj issue edit 456 -t "New Title"
fgj issue edit 456 --add-label priority --remove-label bug
fgj issue edit 456 -m "v1.0"
fgj issue edit 456 --remove-milestone
fgj issue edit 456 -F new-body.md

# Assign or unassign people (@me is you)
fgj issue edit 456 --add-assignee @me --remove-assignee alice

Repositories

# View repository details
fgj repo view owner/repo

# View repository details as JSON
fgj repo view owner/repo --json

# List your repositories
fgj repo list

# List repositories of another user or an organization
fgj repo list some-org

# 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

# Rename a repository (prompts for confirmation; updates origin in a local checkout)
fgj repo rename new-name
fgj repo rename new-name -R owner/repo --yes

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), prompts for confirmation
fgj release delete v1.2.3

# Skip confirmation
fgj release delete v1.2.3 --yes

Milestones

# List open milestones (auto-detects repo)
fgj milestone list

# Filter by state
fgj milestone list --state closed
fgj milestone list --state all

# Create a milestone
fgj milestone create "v1.0" -d "First stable release" --due 2026-06-30

# Create or update if it already exists
fgj milestone create "v1.0" -d "Updated description" -f

# Edit a milestone (rename, change description, due date, or state)
fgj milestone edit "v1.0" --title "v1.0.0"
fgj milestone edit "v1.0.0" --due 2026-07-15
fgj milestone edit "v1.0.0" --state closed

# Delete a milestone (prompts for confirmation)
fgj milestone delete "v1.0.0"
fgj milestone delete "v1.0.0" --yes

Labels

# List labels (auto-detects repo)
fgj label list

# Create a label
fgj label create bug -c ff0000 -d "Something isn't working"

# Create an exclusive (scoped) label
fgj label create priority/high -c ff8800 --exclusive

# Create or update if it already exists
fgj label create bug -c ee0701 -f

# Edit a label
fgj label edit bug -n defect -c cc0000

# Delete a label (prompts for confirmation)
fgj label delete wontfix
fgj label delete wontfix -y

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 repository runners
fgj actions runner list

# List repository and inherited runners visible to this repository
fgj actions runner list --visible

# Register a runner and print its credentials
fgj actions runner register my-runner

# Register an ephemeral runner and print its id, uuid, and token as JSON
fgj actions runner register my-runner --ephemeral --json

# Delete a repository runner
fgj actions runner delete 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

fgj api is a generic authenticated passthrough to the Forgejo REST API, mirroring gh api. It covers any endpoint that fgj has no dedicated command for, and its output is printed verbatim so you can pipe it to jq.

# GET a path ("/api/v1" is added when omitted); pipe to jq as usual
fgj api repos/owner/repo | jq .default_branch

# Send typed parameters with -F (true/false/null/integers become JSON literals,
# @file or @- reads a value) or strings with -f; this defaults to POST
fgj api repos/owner/repo/issues -F title='Bug' -F body=@report.md -f labels[]=bug

# Choose the method explicitly
fgj api -X PATCH repos/owner/repo/issues/1 -F state=closed

# Send a raw request body from a file (or stdin with -); field flags become query params
fgj api repos/owner/repo/contents/README.md -X PUT --input payload.json

# Add request headers, and include the response status line and headers
fgj api -i -H 'Accept: application/json' repos/owner/repo

# Follow pagination; --slurp wraps every page in a single JSON array
fgj api --paginate --slurp repos/owner/repo/commits | jq 'add | length'

# Reach endpoints fgj has no dedicated command for, e.g. branch
# protections and combined commit status / checks
fgj api repos/owner/repo/branch_protections
fgj api repos/owner/repo/commits/<sha>/status

fgj api does not embed a jq engine; pipe the JSON output to jq for filtering.

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
fgj actions runner list --json

For any endpoint without a dedicated --json command, use fgj api.

Configuration

Configuration is stored in ~/.config/fgj/config.yaml (or $XDG_CONFIG_HOME/fgj/config.yaml; pass --config <file> to use another file):

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
  forge.internal.example:
    hostname: forge.internal.example
    api_protocol: http
    token: another_token
    user: another_username
    git_protocol: ssh

Keeping the token out of the config file

Set token_cmd instead of token and fgj runs it (through sh -c, or cmd /C on Windows) whenever it needs the token, using the first line of its output. Any password manager works:

hosts:
  codeberg.org:
    hostname: codeberg.org
    user: your_username
    token_cmd: pass show forgejo/codeberg

The command only runs for commands that talk to the API, and its prompts (gpg pinentry and the like) reach your terminal. token_cmd wins over a stored token, and FGJ_TOKEN wins over both.

Plain HTTP instances

api_protocol selects the scheme used to reach a host's API. It defaults to https; set it to http for an instance served over plain HTTP, such as one on an internal network:

fgj auth login --hostname forge.internal.example --api-protocol http

fgj auth login records the protocol it authenticated with, including one that came from --api-protocol or FGJ_API_PROTOCOL, so later commands reach the host the same way without the flag. A re-login keeps the stored value when the flag is omitted.

A token sent over http travels in cleartext, so keep api_protocol in the per-host config where it applies only to that instance. The --api-protocol flag and FGJ_API_PROTOCOL apply to whatever host a command resolves to, which makes them right for bootstrapping a login and wrong for leaving set in a shell profile.

api_protocol is never inferred from the git remote: an http remote does not downgrade an API call that would otherwise use TLS.

Git protocol

git_protocol selects whether fgj pr checkout and fgj repo create --clone use a repository's SSH or HTTPS URL. It defaults to https; set it at login:

fgj auth login --git-protocol ssh   # or -p ssh

A re-login keeps the stored value when the flag is omitted.

Environment Variables

  • FGJ_HOST: Override the default Forgejo instance (auto-detected from git remote if not set)
  • FGJ_TOKEN: Provide authentication token
  • FGJ_API_PROTOCOL: Override the protocol (http or https) used to reach the API

Hostname is resolved in this priority order:

  1. Host part of -R HOST/OWNER/REPO, or --hostname
  2. FGJ_HOST environment variable
  3. Auto-detected from git remote URL
  4. The only configured host, if there is just one
  5. codeberg.org, if it is configured or no host is (with several hosts and no codeberg.org, fgj errors and asks you to pick one)

Token is resolved in this priority order:

  1. FGJ_TOKEN environment variable
  2. Output of the host's token_cmd
  3. Stored token from ~/.config/fgj/config.yaml

API protocol is resolved in this priority order:

  1. Command-specific flags (e.g., --api-protocol)
  2. FGJ_API_PROTOCOL environment variable
  3. api_protocol stored for that host in ~/.config/fgj/config.yaml
  4. Default to https

Command-line Flags

  • --hostname: Specify Forgejo instance for a command (overrides auto-detection and environment variables)
  • --api-protocol: Use http or https to reach the API (overrides the stored api_protocol)
  • --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.

Detection uses the repository the current directory belongs to. Inside a git submodule or a linked worktree, that is the submodule's or worktree's own repository, not the parent one.

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)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. See CONTRIBUTORS.md for a list of people who have contributed to the project.

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:

Not Yet Implemented:

  • run delete - Delete a workflow run
  • run download - Download workflow run artifacts
  • pr diff
  • pr review, pr checks, pr ready/draft
  • issue assign
  • release edit, release download, release generate-notes
  • repo delete, repo visibility

Endpoints without a dedicated command — such as branch protections and combined commit status / checks — are reachable today through fgj api.

We welcome contributions to implement any of these features! Please check the issues or create a new one to discuss implementation before starting work.

License

MIT License