@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 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 | | 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 | | 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:retarget | Repoint an open pull request at a new base branch, confirm the forge took it, and report its mergeability as advice | | 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 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.