@bensandee/forgejo-cli
bst-fj: the Forgejo API commands, without the rest of bst. Most of these commands used to ship on
@bensandee/tooling's bst bin; issue:*, pr:create, pr:update, pr:ready, pr:reopen and
pr:retarget still do, and run the same code.
Installation
pnpm add -D @bensandee/forgejo-cli
# Or run directly
pnpm dlx @bensandee/forgejo-cli --help
Connection
Every command finds its repository and token the same way bst does. It reads the environment
first:
| Variable | Meaning |
|---|---|
FORGEJO_SERVER_URL | The forge's base URL, such as https://codeberg.org |
FORGEJO_REPOSITORY | The target repository as owner/repo |
RELEASE_TOKEN | The API token (FORGEJO_TOKEN is used when this is unset) |
When the server URL or repository is not set, it falls back to the origin git remote, then to
package.json#repository. A command that takes --repo targets that repository instead.
Environment file
Set BST_ENV_FILE to the path of an env file, and bst-fj loads it before anything else runs, the
same way bst does. A variable already set in the environment always wins over the file. A file
that cannot be read stops the command before it starts. This is for development only: a production
run should get every variable from its environment and leave BST_ENV_FILE unset.
Commands
Run bst-fj --help for the list and bst-fj <command> --help for each command's flags. Every
command takes --json, which prints exactly one JSON document, failures included.
| Command | What it does |
|---|---|
labels | list a repository's labels, or sync one named set from a --file (creates and updates, never deletes) |
secrets | set, list or delete Forgejo Actions secrets |
webhooks | List webhooks across an instance (system, user, org and repo) |
release:create | Create a release for a tag the forge already has; refuses a tag the forge lacks unless given --target |
pr:checks | Read a pull request's CI verdict, optionally --wait for it to settle |
pr:list | List a repository's pull requests |
commit:status | Read the status checks for a commit SHA, branch, tag or git ref |
issue:* | view, list, comment, create, update, download, label, unlabel, set-labels, close, reopen |
pr:create | Push the current branch and open a pull request, deriving the title and body when none is given; reports no closed-issue claims, which bst pr:create does |
pr:update | Push the current branch and update its open pull request |
branch:list | List a repository's branches |
branch:delete | Delete a branch through the API; reports the forge's reason when it refuses |
pr:files | List the files a pull request changes |
pr:merge | Merge an open, non-draft, mergeable PR pinned to the head it read; refuses closed, draft, conflicted, unconfirmed or non-green checks (zero statuses included) unless --ignore-checks; --delete-branch is opt-in |
pr:ready | Mark a draft pull request ready, dropping one WIP: prefix or taking --title, and confirm the forge no longer reports a draft; the number defaults to the current branch's open pull request |
pr:close | Close an open pull request, optionally posting --comment/--comment-file first; reports an already-closed or merged PR without writing; refuses an issue |
pr:reopen | Reopen a closed pull request and confirm the forge reports it open; reports an already-open PR without writing; refuses a merged PR and an issue; the number defaults to the current branch's closed, unmerged pull request |
pr:retarget | Repoint an open pull request at a new base branch, confirm the forge took it, and report its mergeability as advice; the number defaults to the current branch's open pull request |
workflow:dispatch | Dispatch a workflow with --workflow, --ref and repeatable --input; takes --repo owner/repo, not a URL |
ci:runs | List a repository's workflow runs with their jobs, filtered by workflow, ref, pull request, head SHA or status |
ci:log | Print one workflow job's whole log, or with --grep only the lines whose text matches |
Zero posted statuses reads as no-status, never as green. Every command is Forgejo-only: on
GitHub, use gh. The issue:*, pr:create, pr:update, pr:ready, pr:reopen and pr:retarget
commands take the same flags and print the
same --json documents as bst's, except that issue:create has no config default for assignees.