Introduction

I integrated forgejo-contrib/forgejo-cli to make it easier for AI coding agents to interact with my self-hosted Forgejo instance. forgejo-cli is similar to gh, the official CLI tool for GitHub.

Installation

I installed it on a Linux environment using Nix’s home-manager. The Nix 25.11 package repository includes forgejo-cli Version 0.3.0.

{
  ...
  outputs = inputs@{ nixpkgs-old, flake-parts, ... }:
    let
      mkHome = system: homeDirectory:
        inputs.home-manager.lib.homeManagerConfiguration {
          pkgs = import inputs.nixpkgs { inherit system; };
          modules = [
            ({ pkgs, ... }: {
              home.username = "username";
              home.homeDirectory = homeDirectory;
              home.stateVersion = "25.11";
              home.packages = with pkgs; [
                forgejo-cli
              ];
            })
          ];
        };
    in
    ...
}

forgejo-cli is launched with the fj command:

$ fj version
fj v0.3.0

Generating an Access Token

Generate a token from Forgejo’s frontend at Settings > Applications > Access tokens > Generate new token. I configured the permissions as follows:

read:notification
read:organization
write:package
write:issue
write:repository
write:user

Logging In with a Token

I stored the generated token in gnome-keyring first:

$ echo -n "MY_FORGEJO_PAT" | secret-tool store --label="Forgejo PAT" service forgejo user username@git.example.com

Register the key using the auth add-key subcommand. Note that you must specify the host with -H git.example.com; otherwise, it defaults to github.com:

$ echo -n "$(secret-tool lookup service forgejo user username@git.example.com)" | fj -H git.example.com auth add-key username

$ fj auth list
username@git.example.com

$ fj -H git.example.com whoami
currently signed in to username@git.example.com

Managing Issues and Pull Requests

The v0.3.0 fj provides issue and pr commands for managing issues and pull requests.

Issues

Create an issue with fj issue create. Note that the -H flag for specifying the host must come before the subcommand:

$ fj -H git.example.com issue create --repo <REPO> [TITLE] --body <BODY>

To search for issues in a specific repository, use fj issue search. The --repo option is required:

$ fj issue search --repo <REPO>

To view issue details, use fj issue view <ISSUE> body. Replace <ISSUE> with the issue number. You can also close issues using the -w option to include a comment. Interestingly, this command works correctly without requiring the repository name:

$ fj -H git.example.com issue close <ISSUE> -w <WITH_MSG>

Pull Requests

Create a pull request with fj pr create. This creates a pull request requesting to merge the <HEAD> branch into the <BASE> branch:

$ fj pr create --repo <REPO> --base <BASE> --head <HEAD> [TITLE] --body <BODY>

List pull requests using fj pr search. You can filter by state using the -s option with either open or closed:

$ fj pr search -r <REPO> -s <STATE>

View pull request details (title and body) with fj pr view [ID] body.

You can access help for any command using the --help flag.

Logging Out

Logout from a host with fj auth logout:

$ fj auth list
username@git.example.com
$ fj auth logout git.example.com
signed out of username@git.example.com
$ fj auth list
No logins.

Conclusion

By introducing fj to AI coding agents, I was able to automate issue-based coding and pull request creation. Tools like forgejo-cli that offer CLI operations are particularly valuable for AI agent automation, and I welcome their development.

Note: The review and translation were assisted by an AI generative model. The author is responsible for the final content.

Operating Self-Hosted Forgejo via CLI: A forgejo-cli Guide