The gh for Forgejo — works with any instance, stores your data locally, and speaks Forgejo natively.
fj brings GitHub CLI-level ergonomics to every Forgejo instance: multi-host auth with OAuth2 device flow, offline-searchable local SQLite, cross-repo dashboards, and Forgejo-specific features (runner management, ActivityPub, repo migration) that no other tool exposes. Works with Codeberg, self-hosted instances, and Forgejo Cloud with the same command surface.
Printed by @jrimmer (jrimmer).
Authentication
Set your Forgejo personal access token via the FORGEJO_TOKEN environment variable or forgejo-pp-cli auth set-token <token>. Use auth setup to print the steps for generating a token, auth status to verify the current credential, and auth logout to clear it. Multi-host profiles and OAuth2 device flow are not yet implemented.
Quick Start
# Verify fj is configured and reachable
fj doctor --dry-run
# Check CI status across all repos (dry-run shows what would be fetched)
fj ci status --all-repos --dry-run
# See your open issues across all repos
fj issue dashboard --all-repos --assignee @me
# See PRs waiting for your review
fj pr queue --all-repos
# Check unread notifications
fj notification inbox --unread
Unique Features
These capabilities aren't available in any other tool for this API.
Local state that compounds
-
issue dashboard — See all your open issues across every repo (and every Forgejo host) in one sorted table — no browser, no tab-switching.
Use this when you need a triage-ready list of issues spanning multiple repos or instances without opening a browser.
fj issue dashboard --all-hosts --assignee @me --label bug --agent
-
notification inbox — One inbox for all your Forgejo instances — Codeberg, company Forgejo, university instance — sorted by recency with a host column.
Use when a contributor works across multiple Forgejo instances and needs to triage notifications without switching browser profiles.
fj notification inbox --all-hosts --unread --since 24h --agent
-
issue sweep — Find issues with no activity past a threshold, label them, post a comment, and optionally close — with --dry-run and confirmation before acting.
Use during weekly triage automation to keep the issue tracker clean without per-issue web UI clicks.
fj issue sweep --stale-after 90d --label stale --comment 'No activity in 90 days. Closing unless updated.' --dry-run --agent
-
pr queue — Your pending reviews across all repos in one view — PRs where you are a requested reviewer, with CI check status and approval counts.
Use to surface your pending review obligations across multiple repos without opening each repo's PR list individually.
fj pr queue --all-repos --review-requested @me --json --agent
Forgejo-native admin
-
runner sweep — See the status of every Actions runner across all your orgs in one pass — flag offline runners, watch live with --watch.
Use when administering a self-hosted Forgejo instance with multiple org-scoped runners that need monitoring.
fj runner sweep --all-orgs --watch --json --agent
-
ci status — Pass/fail status of the latest CI run per repo (or per branch) across all watched repos, with --watch for live tailing.
Use before cutting a release to confirm all repos are green, or to monitor CI state across a multi-repo service.
fj ci status --all-repos --branch main --watch --json --agent
Release pipeline automation
-
release changelog — Auto-generate a grouped changelog between two tags from closed issues and merged PRs — label-grouped, markdown or JSON output.
Use to generate release notes during a publish workflow without manually scanning the PR list.
fj release changelog v1.2.0 v1.3.0 --owner myorg --repo myproject --format md --section bug,feature,break --agent
-
release upload — Upload release assets with a real progress bar, automatic retry on failure, and post-upload size verification — not silent curl.
Use during release pipelines where large binary uploads need to be reliable and observable.
fj release upload v1.3.0 ./dist/*.tar.gz --owner myorg --repo myproject --retry 3 --progress
Recipes
Triage morning inbox
fj issue dashboard --all-hosts --assignee @me --label bug --agent --select title,repo,updated_at,url
Pulls all bug-labeled issues assigned to you across every configured host into a compact agent-readable list.
Cut a release with changelog
fj release changelog v1.2.0 v1.3.0 --format md | fj release create --tag v1.3.0 --notes-from-stdin
Generates a changelog from closed issues and merged PRs between two tags, pipes it into a new release.
Upload release assets reliably
fj release upload v1.3.0 ./dist/*.tar.gz --retry 3 --progress
Uploads binaries with progress bar and automatic retry on network failure.
Sweep stale issues dry-run
fj issue sweep --stale-after 90d --label stale --dry-run --agent --select number,title,last_activity
Shows which issues would be labeled stale without making any changes — review before running without --dry-run.
Monitor runners across orgs
fj runner sweep --all-orgs --watch --json --agent --select name,status,last_online,org
Streams runner status across all org scopes every 10 seconds; pipe to a Slack webhook for alerts.
Usage
Run forgejo-pp-cli --help for the full command reference and flag list.
Commands
activitypub
Manage activitypub
forgejo-pp-cli activitypub instance-actor - Returns the instance's Actorforgejo-pp-cli activitypub instance-actor-inbox - Send to the inboxforgejo-pp-cli activitypub instance-actor-outbox - Display the outbox (always empty)forgejo-pp-cli activitypub person - Returns the Person actor for a userforgejo-pp-cli activitypub person-activity - Get a specific activity of the userforgejo-pp-cli activitypub person-activity-note - Get a specific activity object of the userforgejo-pp-cli activitypub person-feed - List the user's recorded activityforgejo-pp-cli activitypub person-inbox - Send to the inboxforgejo-pp-cli activitypub repository - Returns the Repository actor for a repoforgejo-pp-cli activitypub repository-inbox - Send to the inboxforgejo-pp-cli activitypub repository-outbox - Display the outbox
admin
Manage admin
forgejo-pp-cli admin add-rule-to-quota-group - Adds a rule to a quota groupforgejo-pp-cli admin add-user-to-quota-group - Add a user to a quota groupforgejo-pp-cli admin adopt-repository - Adopt unadopted files as a repositoryforgejo-pp-cli admin create-hook - Create a hookforgejo-pp-cli admin create-org - Create an organizationforgejo-pp-cli admin create-public-key - Add an SSH public key to user's accountforgejo-pp-cli admin create-quota-group - Create a new quota groupforgejo-pp-cli admin create-quota-rule - Create a new quota ruleforgejo-pp-cli admin create-repo - Create a repository on behalf of a userforgejo-pp-cli admin create-user - Create a user accountforgejo-pp-cli admin cron-list - List cron tasksforgejo-pp-cli admin cron-run - Run cron taskforgejo-pp-cli admin delete-hook - Delete a hookforgejo-pp-cli admin delete-quota-group - Delete a quota groupforgejo-pp-cli admin delete-quota-rule - Deletes a quota ruleforgejo-pp-cli admin delete-runner - Delete a particular runner, no matter whether it is a global runner or scoped to an organization, user, or repositoryforgejo-pp-cli admin delete-unadopted-repository - Delete unadopted filesforgejo-pp-cli admin delete-user - Delete user accountforgejo-pp-cli admin delete-user-emails - Delete email addresses from a user's accountforgejo-pp-cli admin delete-user-public-key - Remove a public key from user's accountforgejo-pp-cli admin edit-hook - Update a hookforgejo-pp-cli admin edit-quota-rule - Change an existing quota ruleforgejo-pp-cli admin edit-user - Edit an existing userforgejo-pp-cli admin get-action-run-jobs - Get action run jobsforgejo-pp-cli admin get-all-emails - List all users' email addressesforgejo-pp-cli admin get-all-orgs - List all organizationsforgejo-pp-cli admin get-hook - Get a hookforgejo-pp-cli admin get-quota-group - Get information about the quota groupforgejo-pp-cli admin get-quota-rule - Get information about a quota ruleforgejo-pp-cli admin get-registration-token - This operation has been deprecated in Forgejo 15. Use the web UI or /admin/actions/runners instead.forgejo-pp-cli admin get-runner - Get a particular runner, no matter whether it is a global runner or scoped to an organization, user, or repositoryforgejo-pp-cli admin get-runner-registration-token - This operation has been deprecated in Forgejo 15. Use the web UI or /admin/actions/runners instead.forgejo-pp-cli admin get-runners - Get all runners, no matter whether they are global runners or scoped to an organization, user, or repositoryforgejo-pp-cli admin get-user-quota - Get the user's quota infoforgejo-pp-cli admin list-hooks - List global (system) webhooksforgejo-pp-cli admin list-quota-groups - List the available quota groupsforgejo-pp-cli admin list-quota-rules - List the available quota rulesforgejo-pp-cli admin list-user-emails - List all email addresses for a userforgejo-pp-cli admin list-users-in-quota-group - List users in a quota groupforgejo-pp-cli admin register-runner - Register a new global runnerforgejo-pp-cli admin remove-rule-from-quota-group - Removes a rule from a quota groupforgejo-pp-cli admin remove-user-from-quota-group - Remove a user from a quota groupforgejo-pp-cli admin rename-user - Rename a userforgejo-pp-cli admin search-emails - Search users' email addressesforgejo-pp-cli admin search-run-jobs - This operation has been deprecated in Forgejo 15. Use /admin/actions/runners/jobs instead.forgejo-pp-cli admin search-users - Search users according filter conditionsforgejo-pp-cli admin set-user-quota-groups - Set the user's quota groups to a given list.forgejo-pp-cli admin unadopted-list - List unadopted repositories
forgejo-version
Manage forgejo version
forgejo-pp-cli forgejo-version - Returns the version of the running application
gitignore
Manage gitignore
forgejo-pp-cli gitignore get-template-info - Returns information about a gitignore templateforgejo-pp-cli gitignore list-templates - Returns a list of all gitignore templates
label
Manage label
forgejo-pp-cli label get-template-info - Returns all labels in a templateforgejo-pp-cli label list-templates - Returns a list of all label templates
licenses
Manage licenses
forgejo-pp-cli licenses get-template-info - Returns information about a license templateforgejo-pp-cli licenses list-templates - Returns a list of all license templates
markdown
Manage markdown
forgejo-pp-cli markdown render - Render a markdown document as HTMLforgejo-pp-cli markdown render-raw - Render raw markdown as HTML
markup
Manage markup
forgejo-pp-cli markup - Render a markup document as HTML
nodeinfo
Manage nodeinfo
forgejo-pp-cli nodeinfo - Returns the nodeinfo of the Forgejo application
notifications
Manage notifications
forgejo-pp-cli notifications notify-get-list - List users's notification threadsforgejo-pp-cli notifications notify-get-thread - Get notification thread by IDforgejo-pp-cli notifications notify-new-available - Check if unread notifications existforgejo-pp-cli notifications notify-read-list - Mark notification threads as read, pinned or unreadforgejo-pp-cli notifications notify-read-thread - Mark notification thread as read by ID
org
Manage org
orgs
Manage orgs
forgejo-pp-cli orgs create - Create an organizationforgejo-pp-cli orgs delete - Delete an organizationforgejo-pp-cli orgs edit - Edit an organizationforgejo-pp-cli orgs get - Get an organizationforgejo-pp-cli orgs get-all - List all organizations
packages
Manage packages
forgejo-pp-cli packages delete - Delete a packageforgejo-pp-cli packages get - Gets a packageforgejo-pp-cli packages link - Link a package to a repositoryforgejo-pp-cli packages list - Gets all packages of an ownerforgejo-pp-cli packages unlink - Unlink a package from a repository
repos
Manage repos
forgejo-pp-cli repos delete - Delete a repositoryforgejo-pp-cli repos edit - Edit a repository's properties. Only fields that are set will be changed.forgejo-pp-cli repos get - Get a repositoryforgejo-pp-cli repos issue-search-issues - Search for issues across the repositories that the user has access toforgejo-pp-cli repos migrate - Migrate a remote git repositoryforgejo-pp-cli repos search - Search for repositories
repositories
Manage repositories
forgejo-pp-cli repositories <id> - Get a repository by id
settings
Manage settings
forgejo-pp-cli settings get-general-apisettings - Get instance's global settings for apiforgejo-pp-cli settings get-general-attachment - Get instance's global settings for Attachmentforgejo-pp-cli settings get-general-repository - Get instance's global settings for repositoriesforgejo-pp-cli settings get-general-uisettings - Get instance's global settings for ui
signing-key-gpg
Manage signing key gpg
forgejo-pp-cli signing-key-gpg - Get default signing-key.gpg
signing-key-ssh
Manage signing key ssh
forgejo-pp-cli signing-key-ssh - Get default signing-key.ssh
teams
Manage teams
forgejo-pp-cli teams org-delete - Delete a teamforgejo-pp-cli teams org-edit - Edit a teamforgejo-pp-cli teams org-get - Get a team
topics
Manage topics
forgejo-pp-cli topics - Search for topics by keyword
user
Manage user
forgejo-pp-cli user add-email - Add an email addresses to the current user's accountforgejo-pp-cli user block - Blocks a user from the doerforgejo-pp-cli user check-quota - Check if the authenticated user is over quota for a given subjectforgejo-pp-cli user create-current-repo - Create a repositoryforgejo-pp-cli user create-hook - Create a hookforgejo-pp-cli user create-oauth2-application - Creates a new OAuth2 applicationforgejo-pp-cli user create-variable - Create a user-level variableforgejo-pp-cli user current-check-following - Check whether a user is followed by the authenticated userforgejo-pp-cli user current-check-starring - Whether the authenticated is starring the repoforgejo-pp-cli user current-delete-follow - Unfollow a userforgejo-pp-cli user current-delete-gpgkey - Remove a GPG public key from current user's accountforgejo-pp-cli user current-delete-key - Delete a public keyforgejo-pp-cli user current-delete-star - Unstar the given repoforgejo-pp-cli user current-get-gpgkey - Get a GPG keyforgejo-pp-cli user current-get-key - Get a public keyforgejo-pp-cli user current-list-followers - List the authenticated user's followersforgejo-pp-cli user current-list-following - List the users that the authenticated user is followingforgejo-pp-cli user current-list-gpgkeys - List the authenticated user's GPG keysforgejo-pp-cli user current-list-keys - List the authenticated user's public keysforgejo-pp-cli user current-list-repos - List the repos that the authenticated user ownsforgejo-pp-cli user current-list-starred - The repos that the authenticated user has starredforgejo-pp-cli user current-list-subscriptions - List repositories watched by the authenticated userforgejo-pp-cli user current-post-gpgkey - Add a GPG public key to current user's accountforgejo-pp-cli user current-post-key - Create a public keyforgejo-pp-cli user current-put-follow - Follow a userforgejo-pp-cli user current-put-star - Star the given repoforgejo-pp-cli user current-tracked-times - List the current user's tracked timesforgejo-pp-cli user delete-avatar - Delete avatar of the current user. It will be replaced by a default oneforgejo-pp-cli user delete-email - Delete email addresses from the current user's accountforgejo-pp-cli user delete-hook - Delete a hookforgejo-pp-cli user delete-oauth2-application - Delete an OAuth2 applicationforgejo-pp-cli user delete-runner - Delete a particular user-level runnerforgejo-pp-cli user delete-secret - Delete a secret in a user scopeforgejo-pp-cli user delete-variable - Delete a user-level variable which is created by current doerforgejo-pp-cli user edit-hook - Update a hookforgejo-pp-cli user get-current - Get the authenticated userforgejo-pp-cli user get-hook - Get a hookforgejo-pp-cli user get-oauth2-application - Get an OAuth2 applicationforgejo-pp-cli user get-oauth2-applications - List the authenticated user's oauth2 applicationsforgejo-pp-cli user get-quota - Get quota information for the authenticated userforgejo-pp-cli user get-runner - Get a particular runner that belongs to the userforgejo-pp-cli user get-runner-registration-token - This operation has been deprecated in Forgejo 15. Use the web UI or /user/actions/runners instead.forgejo-pp-cli user get-runners - Get the user's runnersforgejo-pp-cli user get-settings - Get current user's account settingsforgejo-pp-cli user get-stop-watches - Get list of all existing stopwatchesforgejo-pp-cli user get-variable - Get a user-level variable which is created by current doerforgejo-pp-cli user get-variables-list - Get the user-level list of variables which is created by current doerforgejo-pp-cli user get-verification-token - Get a Token to verifyforgejo-pp-cli user list-blocked - List the authenticated user's blocked usersforgejo-pp-cli user list-emails - List all email addresses of the current userforgejo-pp-cli user list-hooks - List the authenticated user's webhooksforgejo-pp-cli user list-quota-artifacts - List the artifacts affecting the authenticated user's quotaforgejo-pp-cli user list-quota-attachments - List the attachments affecting the authenticated user's quotaforgejo-pp-cli user list-quota-packages - List the packages affecting the authenticated user's quotaforgejo-pp-cli user list-teams - List all the teams a user belongs toforgejo-pp-cli user org-list-current-orgs - List the current user's organizationsforgejo-pp-cli user register-runner - Register a new user-level runnerforgejo-pp-cli user search-run-jobs - Search for user's action jobs according filter conditionsforgejo-pp-cli user unblock - Unblocks a user from the doerforgejo-pp-cli user update-avatar - Update avatar of the current userforgejo-pp-cli user update-oauth2-application - Update an OAuth2 application, this includes regenerating the client secretforgejo-pp-cli user update-secret - Create or Update a secret value in a user scopeforgejo-pp-cli user update-settings - Update settings in current user's accountforgejo-pp-cli user update-variable - Update a user-level variable which is created by current doerforgejo-pp-cli user verify-gpgkey - Verify a GPG key
users
Manage users
forgejo-pp-cli users get - Get a userforgejo-pp-cli users search - Search for users
Output Formats
# Human-readable table (default in terminal, JSON when piped)
forgejo-pp-cli forgejo-version
# JSON for scripting and agents
forgejo-pp-cli forgejo-version --json
# Filter to specific fields
forgejo-pp-cli forgejo-version --json --select id,name,status
# Dry run — show the request without sending
forgejo-pp-cli forgejo-version --dry-run
# Agent mode — JSON + compact + no prompts in one flag
forgejo-pp-cli forgejo-version --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
forgejo-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/forgejo-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
FORGEJO_TOKEN | per_call | Yes | Set to your API credential. |
Troubleshooting
Authentication errors (exit code 4)
- Run
forgejo-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $FORGEJO_TOKEN
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- auth: 401 Unauthorized — Run
fj auth status to see which token is active; re-run fj auth login --host <url> to refresh.
- pr queue returns nothing — Run
fj sync --resources pulls first to populate the local cache.
- release upload fails on large files — Use
fj release upload <tag> <file> --retry 3 --progress for retry and progress tracking.
- notification inbox empty across hosts — Run
fj sync --resources notifications --all-hosts to pull from all configured instances.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press