hive-forge CLI

hive-forge is the Forgejo API wrapper available in every agent container (installed via nix/agent-modules/forge.nix; lives in /hive-forge as a proper Rust binary). Use it instead of ad-hoc curl pipelines.

Credentials and repo defaults

Verbs

Kind-namespaced commands (preferred): issue/PR operations are grouped under issue and pr parent commands — hive-forge pr close 42, hive-forge issue create --title …, hive-forge pr status --pr 42. The pr <verb> / issue <verb> forms validate the number's kind (e.g. pr close refuses an issue number, which the old generic close couldn't). Run hive-forge pr --help / hive-forge issue --help for the full subcommand list (show/create/edit/status/merge/reviews/commits/diff/view/comment/ comments/close/reopen/labels/assign/timeline as applicable).

The flat forms below (close 42, pr-create …, pr-status …, …) still work as hidden back-compat aliases during the transition and are dropped from --help; prefer the namespaced form. They'll be removed in a later sweep.

hive-forge pr close 42                      # close a PR (kind-validated)
hive-forge pr reopen 42                      # reopen a closed PR (kind-validated)
hive-forge issue close 42                   # close an issue (kind-validated)
hive-forge issue reopen 42                   # reopen a closed issue (kind-validated)
hive-forge pr status --pr 42                # PR health (mergeable / CI / reviews)
hive-forge issue create --title "..." --body "..."
# --- flat aliases below remain valid (hidden) ---
hive-forge view 42                          # title + body + comments (marks thread read)
hive-forge comments 42                      # list all comments (human-readable; marks thread read); for PRs, review bodies merged in
hive-forge comments 42 --tail 10            # last 10 comments (count-then-page; efficient on long threads)
hive-forge --json comments 42               # same as above, JSON array (global flag)
hive-forge comment 42 --body "..."          # post comment (inline body)
hive-forge comment 42 --body-file - <<EOF   # ...or pipe a HEREDOC
multi-line body
EOF
hive-forge comment 42 --body "..." --force  # post even if thread has unread activity
hive-forge comment-show 18042               # fetch one comment by id
hive-forge comment-edit 18042 --body "..."  # edit a comment
hive-forge assign 42 damocles
hive-forge close 42
hive-forge labels 42 add feature
hive-forge issue-create --title "..." --body "..."
hive-forge issue-edit 42 --title "new title"
hive-forge pr 42                            # PR metadata as JSON
hive-forge pr-create --title "..." --head my-branch --push    # also `git push forge my-branch`
hive-forge pr-reviews 42                    # list reviews; inline comments included per review
hive-forge pr-reviews 42 --approve         # submit APPROVED review
hive-forge pr-reviews 42 --request-changes -m "msg"  # submit REQUEST_CHANGES review
hive-forge pr-reviews 42 --comment -m "msg"  # submit COMMENT review
hive-forge pr assign-reviewer 42 argus      # set argus as a requested reviewer on the PR
hive-forge pr assign-reviewer 42 argus --remove  # withdraw the request
hive-forge pr assign-committer 42 damocles  # add damocles to the PR's assignee list
hive-forge diff 42                          # unified diff (lockfile hunks collapsed by default)
hive-forge diff 42 --full                   # include unfiltered lockfile hunks
hive-forge list                             # open issues/PRs
hive-forge list --kind pr --state all --page 2  # page 2 of all PRs (walk --page 1,2,… with --limit as page size for a repo-wide sweep)
hive-forge milestone                        # list milestones
hive-forge branches deployed/               # filter branches by pattern
hive-forge tree-sha main                    # git tree SHA for a ref
hive-forge -r other-org/other-repo pr 7     # target a different repo
hive-forge lint unassigned                  # open issues/PRs with no assignee
hive-forge lint no-reviewer --reviewer argus  # PRs missing a reviewer comment from argus
hive-forge lint stale-branches --days 14    # branches with no recent activity
hive-forge lint assignments                 # per-assignee open item count
hive-forge pr-status --pr 42                # PR health: mergeable, CI, reviews, last comment (exit 0 = ready)
hive-forge pr-status --sha <sha>            # CI-only fast path for an explicit commit sha
hive-forge pr-merge 42                       # merge (refuses unless mergeable + CI not red + no changes-requested); deletes head branch
hive-forge pr-merge 42 --method rebase       # rebase-merge instead of a merge commit (no squash option)
hive-forge pr-merge 42 --keep-branch --force # keep the head branch; override the readiness gate
hive-forge timeline 42                      # audit trail: closes, label changes, assignments, commit refs
hive-forge attach-issue 42 /path/to/file    # upload a file attachment to an issue; prints download URL
hive-forge attach-comment 18042 /path/to/file  # upload a file attachment to a comment; prints download URL
hive-forge attachment-get <uuid>            # download an attachment; prints resolved path to stdout
hive-forge artifact-get pr1ma-paper-pdf --run 51  # download a CI run's Actions artifact zip (run number from the run-page URL)
hive-forge ci-log --run 51                   # print a CI run's job step logs (run number from the run-page URL); --job i / --step i to narrow
hive-forge ci-rerun --pr 42                   # re-run CI without an empty commit (dispatches a fresh run; --run n / --branch name also work)
hive-forge subscription --watch             # subscribe to repo notifications
hive-forge subscription --unwatch           # unsubscribe
hive-forge subscription --list              # list every repo you watch (audit the notification firehose)
hive-forge -r internal/knowledge clone      # clone with creds auto-injected
hive-forge -r internal/knowledge pr-create --agit --topic foo --title "..."  # open PR via AGit (no fork)
# --- repo management ---
hive-forge repo-create my-repo                                   # create under authenticated user; prints URL
hive-forge repo-create my-repo --org myorg --private --auto-init # under an org, private, with initial commit
hive-forge repo-add-collaborator alice                           # add write collaborator (default permission)
hive-forge repo-add-collaborator alice --permission read         # read-only collaborator
hive-forge repo-labels                                           # list every label defined on the repo
hive-forge repo-labels bug                                       # filter by name substring
hive-forge repo-labels --json                                    # full label objects (id, name, color, description)

Which read verb when

Several verbs read an issue/PR and look overlapping, but each has a distinct output shape — pick by what you need:

Need Verb Shape
The full human view of one item — title, body, and every comment in order view <n> prose dump; marks the thread read (clears the read-before-comment guard). Top-level view auto-detects issue-or-PR by number; scoped issue view <n> / pr view <n> do the same when you already know the kind
Just the structured metadata of one item (state, labels, assignees, head sha…) issue <n> / pr <n> JSON object
Only the comments (skip the body), e.g. to catch up a long thread; for PRs, review bodies (approve/request-changes/comment summaries) are merged in too comments <n> [--tail N] comment + review-body list; marks read
One specific comment by its id comment-show <id> single comment
The audit trail — closes, label/assignee changes, commit refs, merges (no comment bodies) timeline <n> event list
The code change diff <n> unified diff
Is this PR ready to merge — mergeable + CI + reviews pr-status --pr <n> health view; exit code = merge-readiness
The review verdicts + inline review comments pr-reviews <n> review list

Rule of thumb: view first when you're about to act on a thread (it shows everything and clears the unread guard so your follow-up comment isn't rejected); the JSON verbs (issue/pr) when a script needs one field; pr-status when the only question is "can I merge it".

Contributing to a read-only repo (clone + pr-create --agit)

Agents are read-only collaborators on some repos (e.g. internal/knowledge) and so can't push branches. Forgejo's AGit flow lets a read-only user open a PR by pushing the current HEAD to the magic ref refs/for/<base>/<topic>. Two verbs cover the workflow:

hive-forge -r internal/knowledge clone          # clone with token auto-injected
cd knowledge
# add / edit / delete any files, then commit normally
git add -A && git commit -m "add foo runbook"
hive-forge -r internal/knowledge pr-create --agit \
  --topic foo-runbook \    # groups pushes into ONE PR; reuse to update it
  --title "add foo runbook" \
  [--body "details"]       # PR description (also accepts --body-file)

clone derives the dest dir from the repo basename (override with a positional arg); --branch / --depth are passed through. The token is injected into the clone's origin remote so pr-create --agit (default remote origin) can push without re-auth.

pr-create --agit prints the PR URL. Re-running with the same --topic force-updates the existing open PR (the AGit ref is agent-owned scratch). Opens a reviewable PR the operator merges — never commits straight to main.

hive-forge <verb> --help prints the full signature for any verb.

pr-status

One-stop PR health view (--pr <n>): mergeable state, CI checks, requested reviewers + review verdicts, and the last-comment timestamp — the things you need to know whether a PR is ready to merge (CI must pass before merge). --sha <sha> is a CI-only fast path for a raw commit.

A failing/erroring CI context prints its job link. The process exit code is a merge-readiness verdict for --pr (0 only when CI is green AND the PR is mergeable AND no review requests changes), so it composes: hive-forge pr-status --pr 42 && echo ready. --sha mirrors the CI verdict alone.

hive-forge pr-status --pr 42
# PR #42: feat(...): ...
#   state:        open (mergeable: yes)
#   CI:           e39a87ea3949: ✅ success (1 context(s))
#   ✅ CI / nix flake check (pull_request): success — Successful in 1m50s
#   reviewers:    (none requested)
#   reviews:      ✅ argus: APPROVED
#   last comment: 2026-06-05T19:13:28+02:00 by argus

Note: review verdicts come from formal Forgejo reviews (the approve / request-changes API). Reviewers who post their verdict as a plain comment show under last comment, not reviews.

Repo management

Agents cannot create repos directly via forge token — Forgejo disables push-to-create and the agent token doesn't have the Create scope. Two paths exist depending on where the repo should live:

Agent repos (agents/<name>) — Use the mcp__hyperhive__create_repo MCP tool (requires the forge tool group). hive-c0re creates the repo in the c0re-owned agents/ org, adds you as a write collaborator (not owner), and enables branch protection (operator-team merge approval required — you cannot self-merge). Clone URL is returned immediately. This is the standard path for agents that need a working repo.

Other repos — Use the CLI verbs below (repo-create / repo-add-collaborator). These use the agent's own forge token so the repo lands under the agent's user account or an org the agent belongs to.

repo-create <name> — create a repo under the authenticated user and print its URL. Key flags:

repo-add-collaborator <user> — grant a forge user access to the active repo (-r/HIVE_FORGE_REPO). Companion to repo-create. The --permission flag accepts read / write (default) / admin. hive-c0re uses this internally when an agent's config repo is initialised.

repo-labels [PATTERN] — list every label defined on the repo, optionally filtered by a name substring (case-sensitive). Distinct from labels <n> which shows the labels on one specific issue/PR. Use this to discover valid label names before triaging or to audit the label set. --json emits full label objects (id, name, color, description).

Notes