feat: add forgejo-cli guide blog post

- Create comprehensive English blog post on operating self-hosted Forgejo via CLI - Document forgejo-cli installation, configuration, and usage workflow - Include detailed examples for managing issues and pull requests - Follow standard bash code block formatting (input with $, output without prefix) - Use example.com placeholder for privacy and security best practices - Add disclaimer about AI-assisted content review
2026-02-01 21:36:53 +09:00 · 2026-02-01 21:36:53 +09:00 · 9755fb9ec5
commit 9755fb9ec5
parent de3b7a1ebc
1 changed files with 132 additions and 0 deletions
--- a/src/blog/post-9.md
+++ b/src/blog/post-9.md
@ -0,0 +1,132 @@
+---
+title: 'Operating Self-Hosted Forgejo via CLI: A forgejo-cli Guide'
+pubDate: 2026-02-01
+author: 'Nakahara Daisuke'
+tags: ["Forgejo"]
+---
+
+# Introduction
+
+I integrated [forgejo-contrib/forgejo-cli](https://codeberg.org/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`](https://cli.github.com/), 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.
+
+```nix
+{
+  ...
+  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:
+```bash
+$ 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](https://gitlab.gnome.org/GNOME/gnome-keyring) first:
+```bash
+$ 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`:
+```bash
+$ echo -n "$(secret-tool lookup service forgejo user username@git.example.com)" | fj -H git.example.com auth add-key username
+```
+
+```bash
+$ fj auth list
+username@git.example.com
+```
+```bash
+$ 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:
+```bash
+$ 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:
+```bash
+$ 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:
+```bash
+$ 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:
+```bash
+$ 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`:
+```bash
+$ 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`:
+```bash
+$ 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.