thfg CLI Reference

thfg is a gh-style CLI for Forgejo. The authoritative inventory of runnable commands lives in the checked-in generated manifest and the CLI to API Mapping page. This page stays hand-written and family-oriented: it covers every public command family, shows common subcommands, and points you to thfg <command> --help for the exact leaf-command and flag surface.

All commands accept --repo owner/repo to target a repository explicitly and --output-format table|json|yaml to control output.

thfg api targets the normalized proxy /api/v1 surface. Root exceptions stay separate: use curl for /health and thfg activitypub for /activitypub/**.

issue

issue list

thfg issue list [flags]

List issues in a repository.

Flag	Description
`--state open\|closed\|all`	Filter by state (default: `open`)
`--search <query>`	Full-text search across title and body
`--sort <field>`	Sort by: `oldest`, `newest`, `recentupdate`, `leastupdate`, `mostcomment`, `leastcomment`, `priority`
`--creator <username>`	Filter by issue creator
`--milestone <name>`	Filter by milestone
`--label <name>`	Filter by label (repeatable)
`--since <date>`	Only issues updated after this date (RFC3339 or `YYYY-MM-DD`)
`--before <date>`	Only issues updated before this date
`--org <org>`	Cross-repo search across all repositories in an org
`--me`	Issues assigned to the authenticated user

issue view

thfg issue view <number>

Show full issue details including body, labels, milestone, assignees, and reactions.

issue create

thfg issue create [flags]

Flag	Description
`--title <text>`	Issue title (required)
`--body <text>`	Issue body (Markdown)
`--label <name>`	Apply label (repeatable)
`--assignee <username>`	Assign to user (repeatable)
`--milestone <name>`	Assign to milestone
`--project <id>`	Add to project

issue edit

thfg issue edit <number> [flags]

Flag	Description
`--title <text>`	New title
`--body <text>`	New body
`--state open\|closed`	Change state
`--milestone <name>`	Set milestone
`--add-assignee <username>`	Add assignee
`--remove-assignee <username>`	Remove assignee
`--add-label <name>`	Add label
`--remove-label <name>`	Remove label

issue close / reopen

thfg issue close <number>
thfg issue reopen <number>

issue search

thfg issue search --org <org> [--query <text>] [--state <state>]

Cross-repository issue search across all repos in an organisation.

issue comment

issue comment list

thfg issue comment list <issue-number>

issue comment view

thfg issue comment view <comment-id>

issue comment create

thfg issue comment create <issue-number> --body <text>

issue comment edit

thfg issue comment edit <comment-id> --body <text>

issue comment delete

thfg issue comment delete <comment-id>

issue deadline

thfg issue deadline set <number> --date <YYYY-MM-DD>
thfg issue deadline clear <number>

thfg issue subscribe <number>
thfg issue unsubscribe <number>
thfg issue subscription <number>    # show current subscription state

issue block / unblock / blocks / deps

Manage issue dependency graph.

thfg issue block <number> --blocked-by <number>
thfg issue unblock <number> --blocked-by <number>
thfg issue blocks <number>          # list issues this issue blocks
thfg issue deps <number>            # list issues this issue depends on

issue time

thfg issue time log <number> --duration <minutes>
thfg issue time list <number>
thfg issue time delete <number> --id <tracking-id>

issue stopwatch

thfg issue stopwatch start <number>
thfg issue stopwatch stop <number>

issue reaction

thfg issue reaction list <number>
thfg issue reaction add <number> --reaction <emoji>
thfg issue reaction remove <number> --reaction <emoji>

issue timeline

thfg issue timeline <number>

Show the full event timeline for an issue (comments, state changes, label changes, assignments, etc.).

issue templates

thfg issue templates

List available issue templates for the repository.

issue pin / unpin / pinned

thfg issue pin <number>
thfg issue unpin <number>
thfg issue pinned

issue attachment

thfg issue attachment list <number>
thfg issue attachment download <number> --id <attachment-id> [--output <path>]
thfg issue attachment upload <number> --file <path>
thfg issue attachment delete <number> --id <attachment-id>

pr

pr list

thfg pr list [flags]

Flag	Description
`--state open\|closed\|all`	Filter by state
`--sort <field>`	Sort by: `oldest`, `newest`, `recentupdate`, `leastupdate`, `mostcomment`, `leastcomment`
`--milestone <name>`	Filter by milestone
`--label <name>`	Filter by label (repeatable)
`--poster <username>`	Filter by PR author

pr view

thfg pr view <number>

Full PR details: title, body, labels, milestone, assignees, reviewers, diff stats, checks.

pr create

thfg pr create [flags]

Flag	Description
`--title <text>`	PR title
`--body <text>`	PR body
`--base <branch>`	Target branch
`--head <branch>`	Source branch
`--draft`	Create as draft
`--assignee <username>`	Assignee (repeatable)
`--label <name>`	Label (repeatable)
`--milestone <name>`	Milestone

pr edit

thfg pr edit <number> [flags]

Flag	Description
`--title <text>`	New title
`--body <text>`	New body
`--draft`	Toggle draft state
`--assignee <username>`	Set assignee
`--label <name>`	Set label
`--milestone <name>`	Set milestone

pr merge

thfg pr merge <number> [flags]

Flag	Description
`--merge-style merge\|squash\|rebase`	Merge strategy
`--delete-branch`	Delete head branch after merge
`--force`	Force merge even if not mergeable
`--auto-merge`	Enable auto-merge (merges when checks pass)

pr update

thfg pr update <number>

Sync the PR’s head branch with the latest base branch commits.

pr cancel-auto-merge

thfg pr cancel-auto-merge <number>

pr commits

thfg pr commits <number>

List commits included in the PR.

pr files

thfg pr files <number>

List changed files in the PR.

pr is-merged

thfg pr is-merged <number>

Exit 0 if merged, 1 otherwise.

pr pinned

thfg pr pinned

List pinned PRs in the repository.

pr find

thfg pr find --branch <branch>

Find the PR associated with a branch.

pr review

thfg pr review create <number> --event APPROVE|REQUEST_CHANGES|COMMENT [--body <text>]
thfg pr review list <number>
thfg pr review view <number> --id <review-id>
thfg pr review edit <number> --id <review-id> --body <text>
thfg pr review submit <number> --id <review-id> --event APPROVE|REQUEST_CHANGES|COMMENT
thfg pr review delete <number> --id <review-id>
thfg pr review dismiss <number> --id <review-id> --message <text>

pr request-review / remove-reviewer

thfg pr request-review <number> --reviewer <username>
thfg pr remove-reviewer <number> --reviewer <username>

repo

repo list

thfg repo list [--org <org>] [--type all|public|private|forks|sources|mirror]

repo view

thfg repo view [owner/repo]

repo create

thfg repo create <name> [--description <text>] [--private] [--org <org>]

repo edit

thfg repo edit [owner/repo] [flags]

Flag	Description
`--name <text>`	Rename the repository
`--description <text>`	New description
`--website <url>`	Repository website
`--private` / `--no-private`	Toggle visibility
`--archived` / `--no-archived`	Toggle archived state
`--issues` / `--no-issues`	Enable/disable issues
`--wiki` / `--no-wiki`	Enable/disable wiki
`--template` / `--no-template`	Toggle template status
`--default-merge-style merge\|squash\|rebase`	Default merge strategy
`--allow-squash` / `--allow-rebase`	Toggle merge options

repo clone

thfg repo clone owner/repo [path]

repo transfer

thfg repo transfer owner/repo --new-owner <username-or-org>

Transfer repository ownership.

repo convert

thfg repo convert owner/repo

Convert a mirror repository to a regular (non-mirror) repository.

repo topic

thfg repo topic list [owner/repo]
thfg repo topic add [owner/repo] --topic <name>
thfg repo topic remove [owner/repo] --topic <name>
thfg repo topic set [owner/repo] --topics <name,name,...>

repo watch / unwatch / watchers / stargazers

thfg repo watch [owner/repo]
thfg repo unwatch [owner/repo]
thfg repo watchers [owner/repo]
thfg repo stargazers [owner/repo]

repo collaborator

thfg repo collaborator list [owner/repo]
thfg repo collaborator add [owner/repo] --user <username> [--permission read|write|admin]
thfg repo collaborator remove [owner/repo] --user <username>
thfg repo collaborator check [owner/repo] --user <username>

repo team

thfg repo team list [owner/repo]
thfg repo team add [owner/repo] --team <team-name>
thfg repo team remove [owner/repo] --team <team-name>

repo hook

thfg repo hook list [owner/repo]
thfg repo hook get [owner/repo] --id <hook-id>
thfg repo hook create [owner/repo] --url <webhook-url> --events <push,issues,...>
thfg repo hook edit [owner/repo] --id <hook-id> [flags]
thfg repo hook delete [owner/repo] --id <hook-id>
thfg repo hook test [owner/repo] --id <hook-id>

repo branch-protection

thfg repo branch-protection list [owner/repo]
thfg repo branch-protection get [owner/repo] --branch <pattern>
thfg repo branch-protection create [owner/repo] --branch <pattern> [flags]
thfg repo branch-protection edit [owner/repo] --branch <pattern> [flags]
thfg repo branch-protection delete [owner/repo] --branch <pattern>

repo tag-protection

thfg repo tag-protection list [owner/repo]
thfg repo tag-protection get [owner/repo] --id <id>
thfg repo tag-protection create [owner/repo] --name-pattern <pattern>
thfg repo tag-protection edit [owner/repo] --id <id> --name-pattern <pattern>
thfg repo tag-protection delete [owner/repo] --id <id>

repo wiki

thfg repo wiki list [owner/repo]
thfg repo wiki view [owner/repo] --page <title>
thfg repo wiki create [owner/repo] --title <text> --content <text>
thfg repo wiki edit [owner/repo] --page <title> [--new-title <text>] --content <text>
thfg repo wiki delete [owner/repo] --page <title>
thfg repo wiki revisions [owner/repo] --page <title>

repo push-mirror

thfg repo push-mirror list [owner/repo]
thfg repo push-mirror add [owner/repo] --remote-url <url> [--remote-name <name>]
thfg repo push-mirror remove [owner/repo] --id <id>
thfg repo push-mirror sync [owner/repo]

repo file

thfg repo file list owner/repo [--path <dir>] [--ref <branch-or-sha>]
thfg repo file get owner/repo --path <file> [--ref <branch-or-sha>]

org

org create

thfg org create <name> [--email <email>] [--visibility public|private|limited]

org edit

thfg org edit <org> [--email <email>] [--repo-admin-change-team-access] [flags]

org rename

thfg org rename <org> --new-name <name>

org member

thfg org member list <org>
thfg org member remove <org> --user <username>
thfg org member check <org> --user <username>
thfg org member publicize <org> --user <username>    # make membership public
thfg org member conceal <org> --user <username>      # hide membership

org repo

thfg org repo list <org>

org label

thfg org label list <org>
thfg org label view <org> --id <id>
thfg org label create <org> --name <name> --color <#rrggbb>
thfg org label edit <org> --id <id> [--name <name>] [--color <#rrggbb>]
thfg org label delete <org> --id <id>

org team

thfg org team list <org>
thfg org team view <org> --id <id>
thfg org team create <org> --name <name> [--permission read|write|admin|owner]
thfg org team edit <org> --id <id> [flags]
thfg org team delete <org> --id <id>
thfg org team members <org> --id <id>
thfg org team repos <org> --id <id>

org hook

thfg org hook list <org>
thfg org hook get <org> --id <id>
thfg org hook create <org> --url <webhook-url> --events <push,issues,...>
thfg org hook edit <org> --id <id> [flags]
thfg org hook delete <org> --id <id>

org block / unblock / list-blocked

thfg org block <org> --user <username>
thfg org unblock <org> --user <username>
thfg org list-blocked <org>

run

thfg run list [--repo owner/repo] [--workflow <filename>] [--branch <branch>] [--latest]
thfg run view <run-id>
thfg run latest [owner/repo] [--workflow <filename>]
thfg run jobs [owner/repo] <run> | --latest [--workflow <id>]
thfg run performance [owner/repo] <run> | --latest [--workflow <id>]
thfg run logs [--repo owner/repo] [--job <job-name>]
thfg run logs-latest [owner/repo] [--job <job-name>]
thfg run summary [owner/repo] <run> | --latest [--workflow <id>]
thfg run watch <run-id>
thfg run diagnose <run-id>           # proxy-only: AI-aided failure analysis
thfg run rerun <run-id>
thfg run cancel <run-id>
thfg run delete <run-id>
thfg run download <run-id>

thfg run jobs exposes the proxy-enriched jobs payload, including job_index, attempt, log_url, and step lists. thfg run performance turns those step timings into a readable summary of slow jobs and steps.

workflow

thfg workflow list [--repo owner/repo]
thfg workflow run <filename.yml> [--repo owner/repo] [--field key=value]

variable

thfg variable list [--repo owner/repo] [--org <org>]
thfg variable set <NAME>=<value> [--repo owner/repo] [--org <org>]
thfg variable delete <NAME> [--repo owner/repo] [--org <org>]

Use --org <org> to manage organisation-level variables.

secret

thfg secret list [--repo owner/repo] [--org <org>]
thfg secret set <NAME>=<value> [--repo owner/repo] [--org <org>]
thfg secret delete <NAME> [--repo owner/repo] [--org <org>]

project

thfg project list --org <org>
thfg project list-repo [--repo owner/repo]
thfg project view --id <id>
thfg project delete --id <id>
thfg project columns --id <id>
thfg project cards --id <id> --column <col-id>
thfg project create --org <org> --title <text>
thfg project edit --id <id> [--title <text>] [--description <text>]
thfg project close --id <id>
thfg project open --id <id>
thfg project create-column --id <id> --title <text>
thfg project add-issue <project-id> <owner/repo#issue-number>
thfg project move-card <project-id> <column-id> <owner/repo#issue-number>

These commands require proxyUrl in your host config. Raw HTTP fallbacks use the normalized /api/v1/projects/... routes.

activitypub

thfg activitypub instance actor
thfg activitypub instance outbox
thfg activitypub instance inbox send (--field key=value | --raw-field key=value | --input -|<file>)
thfg activitypub user actor [user] [--user-id <id>]
thfg activitypub user outbox [user] [--user-id <id>]
thfg activitypub user activity <activity-id> [user] [--user-id <id>]
thfg activitypub user object <activity-id> [user] [--user-id <id>]
thfg activitypub user inbox send [user] [--user-id <id>] (--field key=value | --raw-field key=value | --input -|<file>)
thfg activitypub repo actor [owner/repo] [--repo-id <id>]
thfg activitypub repo outbox [owner/repo] [--repo-id <id>]
thfg activitypub repo inbox send [owner/repo] [--repo-id <id>] (--field key=value | --raw-field key=value | --input -|<file>)

These commands talk to the proxy’s canonical /api/v1/activitypub/... aliases. The rooted /activitypub/** URLs still exist as the published federation surface, but thfg activitypub keeps API clients on the unified /api/v1 base while handling id lookup for you.

api

api spec

thfg api spec [--output-format json|yaml]

View the full OpenAPI specification served by the proxy (/openapi.json).

api <path>

thfg api <path> [--method GET|POST|PATCH|PUT|DELETE] [--field key=value] [--raw-field key=value] [--input -|<file>] [--header Name=Value] [--paginate] [--silent]

Authenticated escape hatch for normalized /api/v1 endpoints. The path must start with / and is joined onto the active Forgejo or proxy /api/v1 base URL. Output is always raw JSON.

thfg api /repos/myorg/myrepo/topics
thfg api /user/repos --paginate
thfg api /repos/myorg/myrepo --method PATCH --field description="New desc"
thfg api /activitypub/actor
thfg api spec

Use raw curl for /health and other cases where you need low-level HTTP control. For ActivityPub, prefer thfg activitypub; thfg api /activitypub/... is available when you want the raw canonical alias payload without the dedicated command wrapper.

auth

thfg auth login [--token <token>] [--username <user>] [--password <pass>]
thfg auth status
thfg auth logout

config

thfg config list
thfg config init
thfg config set <key> <value>
thfg config get <key>
thfg config edit          # open config file in $EDITOR

doctor

thfg doctor

Check connectivity, auth, and config health across all configured hosts.

ac

thfg ac list <owner/repo> <issue>
thfg ac add <owner/repo> <issue> <text>
thfg ac edit <owner/repo> <issue> <index> [--text <text>] [--done|--open]
thfg ac check <owner/repo> <issue> <index>
thfg ac uncheck <owner/repo> <issue> <index>
thfg ac delete <owner/repo> <issue> <index>

Manage acceptance criteria attached to issues through the proxy extension endpoints.

label

thfg label list [owner/repo]
thfg label create <owner/repo> --name <name> --color <#hex>
thfg label edit <owner/repo> --id <id> [--name <name>] [--color <#hex>]
thfg label delete <owner/repo> --id <id>
thfg label clone <source-owner/repo> <target-owner/repo>
thfg label list-org --org <org>

Use the top-level label family for repository and organisation label management outside the issue-focused shortcuts.

milestone

thfg milestone list <owner/repo>
thfg milestone create <owner/repo> --title <title>
thfg milestone edit <owner/repo> --id <id> [--title <title>] [--description <text>] [--due-on <date>]
thfg milestone close <owner/repo> --id <id>
thfg milestone reopen <owner/repo> --id <id>
thfg milestone delete <owner/repo> --id <id>

Manage repository milestones directly when you do not want to work through issue shortcuts.

notification

thfg notification list [owner/repo]
thfg notification view <thread-id>
thfg notification check-new
thfg notification mark <thread-id> [--status <read|unread|pinned>]
thfg notification mark-all [owner/repo] [--status <read|unread|pinned>]

Inspect and update notification-thread state without dropping to raw API calls.

release

thfg release list <owner/repo>
thfg release create <owner/repo>
thfg release edit <owner/repo> --id <id> [flags]
thfg release download <owner/repo> --id <release-id>
thfg release delete <owner/repo> <tag>
thfg release delete-asset <owner/repo> --release-id <id> --asset-id <id>

The release family covers release lifecycle actions plus release-asset download and deletion flows.

package

thfg package list <owner> [--type <package-type>] [--query <name>]
thfg package view <owner> <type> <name> <version>
thfg package files <owner> <type> <name> <version>
thfg package link <owner> <type> <name> <repo-name>
thfg package unlink <owner> <type> <name>
thfg package delete <owner> <type> <name> <version> --confirm

Use these commands for package-registry inspection and cleanup across Forgejo package ecosystems.

search

thfg search repos <query>
thfg search issues <query>
thfg search prs <query>
thfg search code <query> [--repo owner/repo]
thfg search commits <query> --repo owner/repo

The search family gathers the cross-resource search entrypoints that do not fit a single repo or issue command family.

settings

thfg settings api
thfg settings attachment
thfg settings repository
thfg settings ui

Read the instance settings documents exposed by the Forgejo API.

instance

thfg instance version
thfg instance nodeinfo
thfg instance signing-key ssh
thfg instance signing-key gpg

These commands inspect instance-wide metadata and published signing keys.

render

thfg render markdown --text "# Hello"
thfg render markdown-raw --input README.md
thfg render markup --text "<b>Hello</b>" --mode html

Use render when you want the Forgejo renderer to resolve Markdown or markup the same way the server UI would.

template

thfg template list [--type <type>]
thfg template get <type>/<name>
thfg template lookup <name>
thfg template types

Browse and retrieve the shared project-template catalog exposed by the proxy.

ssh-key

thfg ssh-key list
thfg ssh-key view <id>
thfg ssh-key add --title <title> --key-file <path>
thfg ssh-key delete <id>

Manage the authenticated user’s SSH keys.

gpg-key

thfg gpg-key list
thfg gpg-key view <id>
thfg gpg-key add --key-file <path>
thfg gpg-key verification-token
thfg gpg-key verify --key-id <key-id> [--armored-signature <signature>]
thfg gpg-key delete <id>

Manage the authenticated user’s GPG keys and verification flow.

user

thfg user view <username>
thfg user search <query>
thfg user activity <username>
thfg user token list
thfg user runner jobs
thfg user quota check

thfg user covers both current-user management and public-user lookup flows, including tokens, hooks, quotas, runners, repos, avatars, follows, and activity.

admin

thfg admin user list
thfg admin user create --username <name> --email <email> --password <password>
thfg admin cron list
thfg admin cron run <task>
thfg admin runner jobs
thfg admin quota rule list

The admin family groups privileged instance-administration surfaces. Expect many subcommands here; use thfg admin --help and nested --help output for the exact leaf-command flags.