Create repositories, PRs and more on your self-hosted forgejo instance from the command line
  • Go 99.6%
  • Makefile 0.4%
Find a file
2026-11-21 11:24:42 +00:00
cmd/fgj Add fgj, a CLI for self-hosted Forgejo (v15 LTS) 2026-11-07 18:31:07 +00:00
internal Add pr list and pr merge commands 2026-11-21 11:19:40 +00:00
.gitignore Add fgj, a CLI for self-hosted Forgejo (v15 LTS) 2026-11-07 18:31:07 +00:00
AGENTS.md Add pr list and pr merge commands 2026-11-21 11:19:40 +00:00
go.mod Add fgj, a CLI for self-hosted Forgejo (v15 LTS) 2026-11-07 18:31:07 +00:00
go.sum Add fgj, a CLI for self-hosted Forgejo (v15 LTS) 2026-11-07 18:31:07 +00:00
LICENSE Add MIT license 2026-11-07 19:10:26 +00:00
Makefile Add fgj, a CLI for self-hosted Forgejo (v15 LTS) 2026-11-07 18:31:07 +00:00
mise.toml Add fgj, a CLI for self-hosted Forgejo (v15 LTS) 2026-11-07 18:31:07 +00:00
README.md Add pr list and pr merge commands 2026-11-21 11:19:40 +00:00

fgj — a CLI for self-hosted Forgejo

this was entirely vibe-coded with Opus 5.5 - use with caution

fgj talks to your Forgejo instance over the Forgejo REST API (/api/v1). It can:

  • create repositories (personal or in an organisation)
  • open, list and merge pull requests, using your local git checkout to fill in the defaults

It targets the current Forgejo LTS release, v15. Every request field it sends exists in the v15 API schema. Older servers still work for basic use, and fgj auth login warns you when the server is older than v15.

Install

go install git.markow.dev/daniel/Forgejo-CLI/cmd/fgj@latest

If the repository is private, first set GOPRIVATE=git.markow.dev and make sure git can authenticate to the server.

To build from a checkout, use mise to install the pinned Go toolchain:

mise install      # installs the Go version from mise.toml
make build        # -> bin/fgj
make install      # -> $(go env GOPATH)/bin/fgj

Without mise, you need Go 1.26 or newer.

Authenticate

Create an access token in Forgejo under Settings → Applications. These are the scopes Forgejo v15 requires (from routers/api/v1/api.go):

scope needed for
read:user always: auth login / auth status identify the token owner
write:repository pr create, pr merge; also repo create for personal repositories
read:repository pr list (included in write:repository)
write:user repo create for personal repositories (with write:repository)
write:organization repo create ORG/NAME
read:issue --label / --milestone on pr create and pr list
read:organization --label with organisation-wide labels (optional)

If a command fails with 403 token does not have at least one of required scope(s): [...], the message names the missing scope. Create a token that includes it and run fgj auth login again.

fgj auth login --url https://git.example.com          # prompts for the token (hidden input)
echo "$TOKEN" | fgj auth login --url git.example.com --with-token
fgj auth status                                        # lists hosts and re-checks each token
fgj auth logout git.example.com

You can save several instances. The first one you log in to becomes the default; pass --default to change it. Credentials are stored in ~/.config/fgj/config.json with mode 0600. Set FGJ_CONFIG to use a different path.

Choosing the instance

For each command, fgj picks the instance in this order:

  1. --host (a saved host name such as git.example.com, or a URL)
  2. $FORGEJO_URL
  3. the saved host whose hostname matches the current git remote
  4. the default saved host

--token or $FORGEJO_TOKEN overrides the saved token. In CI you can skip auth login entirely:

FORGEJO_URL=https://git.example.com FORGEJO_TOKEN=... fgj repo create build-cache

Instances served under a sub-path, such as https://example.com/forgejo, are supported.

Create a repository

fgj repo create my-tool -d "A small tool"                      # private, empty
fgj repo create my-tool --init --license MIT --gitignores Go   # with an initial commit
fgj repo create acme/service --public                          # in organisation "acme"
fgj repo create scratch --object-format sha256 --default-branch trunk
fgj repo create my-tool --json                                 # machine-readable output

Repositories are private by default. --license, --gitignores, --readme and --issue-labels name templates that ship with your instance, and any of them implies --init. Run fgj repo create --help to see every flag (--template, --trust-model, …).

Create a pull request

From inside a checkout whose origin points at the Forgejo instance:

git push -u origin my-feature
fgj pr create --fill                        # title and body come from the last commit
fgj pr create -t "Add retries" -b "Fixes #12" -l bug -l backend -a alice -m v1.2

Defaults:

  • repository: parsed from --remote (default origin). HTTPS, ssh:// and scp-style URLs all work.
  • head: the current branch
  • base: the repository's default branch

Outside a checkout, or to target a different repository:

fgj pr create -R acme/api -H my-feature -B main -t "Title" -F description.md
fgj pr create -R upstream/proj -H myfork:fix-typo -t "Fix typo"   # PR from a fork
git log -1 --format=%b | fgj pr create -t "Title" -F -             # body from stdin

--label accepts label names (case-insensitive). It looks in the repository's labels first, then the organisation's. --milestone accepts a milestone name or ID, and --due takes YYYY-MM-DD or RFC 3339.

List pull requests

fgj pr list                                   # open PRs of the repository in the current checkout
fgj pr list --state merged --limit 10         # states: open (default), closed, merged, all
fgj pr list -R acme/api --author alice --label bug --milestone v1.2
fgj pr list --sort recentupdate --json

--label can be repeated, and a PR must have all the given labels to be listed. --limit defaults to 30; --limit 0 lists everything. The API has no "merged" state, so --state merged fetches closed PRs and keeps the merged ones.

Merge a pull request

fgj pr merge 12                               # repository's default merge style
fgj pr merge                                  # the open PR whose head is the current branch
fgj pr merge 12 --style squash --delete-branch -t "Add retries (#12)"
fgj pr merge 12 --auto                        # merge once required checks pass
fgj pr merge 12 --cancel-auto
  • --style is one of merge, rebase, rebase-merge, squash or fast-forward-only. It defaults to the repository's default style. Styles the repository doesn't allow are rejected before anything is sent.
  • --delete-branch defaults to the repository's "delete branch after merge" setting. Use --delete-branch=false to keep the branch anyway.
  • Safety: fgj sends the head commit it looked at, so if someone pushes to the branch in the meantime the merge fails with head out of date instead of merging commits you haven't seen. In an interactive terminal it asks for confirmation first. --yes skips that, and scripts (no terminal) are never prompted.
  • --auto asks Forgejo to merge once all required status checks have passed. If they already have, it merges straight away.

Development

mise install
make test   # unit and end-to-end tests (needs git on PATH)
make vet

The end-to-end tests in internal/cmd run the real command tree against an in-process fake Forgejo server. That server rejects any request field missing from the Forgejo v15 swagger schema, so these tests catch requests the LTS API would not understand.

Layout:

cmd/fgj/                 entry point (main package)
internal/cmd/            cobra commands (auth, repo, pr)
internal/forgejo/        minimal typed API client
internal/config/         saved hosts and tokens
internal/gitutil/        reads remotes, branches and commits from the local checkout

License

MIT. See LICENSE.