fj

A minimal Forgejo/Gitea CLI client. Manage issues and pull requests without leaving the terminal.

Features

• Issue management: list, show, create, edit, close, delete, comments, labels, pins, reactions, deadlines, stopwatch and time tracking
• Pull request management: list, show, create, edit, close
• Instance-wide listings (--global) and full-text search across repositories
• Auto-detects repo from git remote (SSH and HTTPS)
• Credential resolution via git credential
• Shell completion for commands, flags, and live repository data
• Raw JSON output (--json) for scripting
• Installs as git-fj for use as a git subcommand
• Symlink as git-issues or git-prs for quick listing

Install

go install go.schlittermann.de/heiko/fj@latest

Place fj in $PATH. To use it as a git subcommand, add a symlink:

ln -s fj ~/bin/git-fj   # enables: git fj issue list

Usage

git fj issue list                     # open issues
git fj issue list --state closed      # closed issues
git fj issue show 42                  # issue details
git fj issue create --title "bug"     # new issue
git fj issue edit 42 --state closed   # close issue
git fj issue comment create 42 --body "fix"  # add comment
git fj issue search nagonag --type pulls     # full-text search, all repos

git fj pr list                        # open PRs
git fj pr show 7                      # PR details
git fj pr create --title "feat" --head dev
git fj pr edit 7 --state closed

git fj workflow init nagonag          # scaffold .forgejo/workflows/*.yaml
git fj workflow init nagonag --ref v1 # pin a source ref
git fj workflow init nagonag --force  # overwrite local edits

git fj issue list --json | jq '.[].title'

Instance-wide listings work inside any repository, or anywhere once an instance is registered:

fj login --alias fj https://git.example.org   # stores fj.fj.url, becomes fj.default
fj prs -g                                     # open PRs in all repositories
fj issues -g --assigned                       # issues assigned to me
fj issues -g --instance fj --owner heiko

fj login --with-token URL < token-file verifies a token and hands it to your git credential helper; tokens are never written to the git config.

Shell completion:

source <(fj completion bash)   # or zsh; fish: fj completion fish | source

Symlink shortcuts:

ln -s fj ~/bin/git-issues
ln -s fj ~/bin/git-prs
git issues              # same as: fj issue list
git prs                 # same as: fj pr list

Display the built-in manual page:

fj man

Configuration

fj reads configuration from git config:

git config fj.token <your-api-token>    # API token (optional if git credential works)
git config fj.remote upstream           # override remote detection (default: current branch remote, then origin)
git config --global fj.default fj       # instance for --global outside a repository (set by fj login)
git config --global fj.fj.url https://git.example.org   # instance alias (set by fj login)

Token resolution order:

1. git config fj.token
2. git credential fill for the remote host
3. git credential fill after following redirects

Development

The man page source is docs/fj.1.md (pandoc Markdown). After editing it, regenerate and commit the derived files:

go generate ./...   # requires pandoc; writes .generated/fj.1{,.gz} and .generated/git-fj.1{,.gz}
git add docs/fj.1.md .generated/fj.1.gz .generated/git-fj.1.gz
git commit

Only the .gz files are committed; .generated/fj.1.gz is embedded in the binary. The uncompressed files are gitignored.

License

Apache-2.0. See LICENSE.