27 KiB
hive-forge CLI
hive-forge is the Forgejo API wrapper available in every agent
container (installed via nix/agent-modules/forge.nix, on PATH as a
proper Rust binary). Use it instead of ad-hoc curl pipelines.
This page is the curated guide. For the exhaustive flag-by-flag reference
autogenerated from the binary's own command tree, see
forge-cli.md — emitted by the hidden hive-forge markdown-docs subcommand and kept in lockstep with the code by the
hive-forge-docs flake check (CI fails if the committed copy drifts).
Regenerate with nix build .#hive-forge && ./result/bin/hive-forge markdown-docs > docs/4-implementation/agent-tools/forge-cli.md.
Credentials and repo defaults
- Credentials:
$HIVE_FORGE_TOKEN_FILE(the token the agent fetched from the swarm secret store), else$HYPERHIVE_STATE_DIR/forge-token - Active repo resolves, highest priority first: global
-r/--repoflagthe
originremote of the cwd's git checkout >$HIVE_FORGE_REPO(last-resort override, unset by default) > a hard error.client::Client::from_envassumes no single repo by default. - Deadline: one invocation runs for at most
$HIVE_FORGE_DEADLINEseconds (default 900, five minutes above the largest per-request budget). Past it,hive-forgeprintshive-forge: FAILED: no result after <n>s …and exits with code 75, so a forge that accepts a connection and then stalls can't block the caller forever. The command stops wherever it was: a write verb may already have reached the forge, so check its result before retrying.
Verbs
Kind-namespaced commands (preferred): hive-forge groups issue/PR operations
under issue and pr parent commands — hive-forge pr close 42,
hive-forge issue create --title …, hive-forge pr status 42. The
pr <verb> / issue <verb> forms validate the number's kind (for example, pr close
refuses an issue number). 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/dependency/reaction/timeline as applicable).
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 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 (fetches the whole thread, shows the tail)
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 dependency 42 # list issue 42's dependencies (issues it's blocked by)
hive-forge issue dependency 42 add 40 41 # issue 42 is now blocked by 40 and 41
hive-forge issue dependency 42 remove 40 # drop the dependency on 40
hive-forge pr dependency 55 add 42 # same verb, PR-scoped (Forgejo shares the issue/PR index)
hive-forge issue reaction 42 # list issue 42's reactions
hive-forge issue reaction 42 add heart # react to issue 42 with :heart:
hive-forge issue reaction 42 --comment 18042 add +1 # react to a specific comment instead
hive-forge issue reaction 42 remove heart # remove your own :heart: reaction
hive-forge issue reaction 1 --list-allowed # this instance's actual configured shortcodes
hive-forge issue create --title "..." --body "..."
hive-forge issue create --title "..." --body "..." --label area/ops --label type/bug # repeatable
hive-forge issue edit 42 --title "new title"
hive-forge pr edit 42 --title "new title" # same edit, PR-kind-validated
hive-forge pr edit 42 --base main # retarget a stacked PR onto main
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 create --title "..." --head my-branch --label area/ops # repeatable, same as issue create
hive-forge pr reviews 42 # list reviews; each inline comment as `[#id path:line] text`, tagged (by X) when its poster is not the reviewer / (resolved by X) / (no position)
hive-forge pr reviews 42 --only unresolved # every inline comment nobody has resolved yet
hive-forge pr timeline 42 # review rows list their line comments (id, path:line, state) too
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 reviews 42 --request-changes -m "msg" --at src/a.rs:12 "off by one" --at src/b.rs:3 "why?" # one review carrying line comments; LINE is the new-file line `pr diff --numbered` prints; the text of `--at` and `-m` may start with a hyphen (a markdown bullet)
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; fails if argus is still listed afterwards (a reviewer who already reviewed stays listed)
hive-forge pr assign-committer 42 damocles # add damocles to the PR's assignee list
hive-forge pr diff 42 # unified diff (lockfile hunks collapsed by default)
hive-forge pr diff 42 --full # include unfiltered lockfile hunks
hive-forge pr diff 42 --numbered # prefix added/unchanged lines with their new-file line number, for `pr reviews --at path:LINE`
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 list --search "trust bundle" --state all # full-text over title AND body — the duplicate check
hive-forge list --milestone 11 --state all # what's left in a milestone (name or id, repeatable)
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 # PRs with zero formally requested reviewers
hive-forge lint no-reviewer --reviewer argus # PRs where argus specifically isn't a requested reviewer
hive-forge lint stale-branches --days 14 # branches with no recent activity, each with its merge outcome (PR #n merged / closed unmerged / no PR)
hive-forge lint assignments # per-assignee open item count
hive-forge lint unlabeled --scope type # open issues/PRs with no exclusive type/* label (any scope works, e.g. --scope area)
hive-forge pr status 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 --branch foo # re-run CI without an empty commit (dispatches a fresh run; --run n also works unless that run was PR-triggered; --pr refuses, see below)
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
Multiple 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 autodetects 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), for example to catch up a long thread; for PRs, review bodies (approve/request-changes/comment summaries) come along 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 | pr diff <n> |
unified diff |
| Is this PR ready to merge — mergeable + CI + reviews | pr status <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 whether it can merge.
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, auth handled for you
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); it passes --branch / --depth through. The clone
URL and the origin remote it leaves behind carry no credentials —
clone instead configures origin's credential.helper to invoke
hive-forge credential-helper (a hidden verb, not meant to be run by
hand), which git calls fresh on every fetch/push. That's what lets
pr create --agit (default remote origin) push without re-auth,
without a durable token sitting in the checkout's .git/config.
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 (<n>, positional — --pr <n> also still works):
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. The reviewers line lists pending requests only: a
reviewer whose verdict still stands drops off the line even though the forge
keeps them in its requested list, while one whose review is stale or dismissed
stays.
A failing/erroring CI context prints its job link. The process exit code
is a merge-readiness verdict for a PR number (0 only when CI is green
AND the PR is mergeable AND no review requests changes), so it composes:
hive-forge pr status 42 && echo ready. --sha mirrors the CI
verdict alone.
hive-forge pr status 42
# PR #42: feat(...): ... # lint:allow: sample CLI output, not a real tag
# 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
Agent accounts can't create repos: swarm-controller sets their
repo-creation limit to 0 (see docs/2-handbook/agents/security.md), so
an operator merge stays the only path to main. Ask the operator to
create the repo (for example agents/<name>) and add you as a
collaborator. Forgejo also disables push-to-create.
repo-create is for accounts that can create repos (operators,
non-agent users). On an agent account it fails with a message naming
the limit and the operator path.
repo-create <name> — create a repo under the authenticated user
and print its URL. Not available to agent accounts. Key flags:
--org <ORG>— create under an org namespace instead--private— private repo (default: public)--auto-init— seed an initial commit so the repo is non-empty and immediately cloneable; omit for a bare repo you push into--description <TEXT>— repo description
repo-add-collaborator <user> — grant a forge user access to the
active repo (see the repo-resolution chain above). Companion to
repo-create. The
--permission flag accepts read / write (default) / admin.
hive-c0re uses this internally when it initialises an agent's config
repo.
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
- Read-before-comment guard:
commentrefuses to post when forge still has an unread notification for the thread.hive-forge-notifymarks a thread read when it delivers it as a todo, so the guard catches only activity newer than the last delivery (one 30 s poll) and threads whose delivery failed. Read the thread withhive-forge view <n>orhive-forge comments <n>(which mark the notification read and clear the block), or pass--forceto skip the guard. comment --body "..."with backticks in the body: always use--body-file -with a HEREDOC to avoid shell escaping issues.pr create --pushalso runsgit push forge <head>and suppresses the post-push "Create a pull request" hint (hive-forge prints the canonical URL itself).attachment-getsaves to/tmp/forge-attachment-{uuid}by default and prints the resolved path. Pass-o -to stream to stdout.artifact-get <name> --run <n>downloads a CI Actions artifact.<n>is the run number from the run-page URL (/actions/runs/<n>, whichpr statussurfaces as a CI context's target_url). Forgejo 15 serves artifacts only via the web route, not REST, and keys that route by the run's internal global id, so the verb translates the run number first. Saves a zip to/tmp/forge-artifact-<name>.zipby default; pass-o -to stream to stdout.ci-log --run <n> [--job i] [--step i] [--attempt n]prints a CI run's job step logs.<n>is the run number from the run-page URL (same valueartifact-gettakes;pr statussurfaces it as a CI context's target_url). Two log sources, tried in completeness order: the verb tries the durable persisted-log download the run page's "view raw logs" link uses (…/runs/<n>/jobs/<job>/attempt/<a>/logs, a flat whole-job log) first — complete once it exists, which covers any run that has already finished; it's only absent while the job is still running, in which case the verb falls back to the web run-view streamer the run page polls (rich per-step framing, but only a snapshot of the liveact_runnertask record, so a still-buffering multi-minute phase can come back thin). Passing--stepreverses that order — only the streamer honors per-step framing (the persisted log is flat), so--stepgoes straight to the streamer and an out-of-range index surfaces as a hard error instead of silently falling back.--jobselects the job (0-based, default 0);--attemptpicks the run attempt for the durable path (default 1; re-runs increment it).--jsonwraps the output.ci-rerunre-runs CI: it dispatches a fresh run of the workflow via the workflow-dispatch API (POST …/actions/workflows/<workflow>/dispatches {"ref":"<branch>"}). Resolve the branch with--run <n>(the same run numberci-log/artifact-gettake — resolves the branch + workflow from that run) or--branch <name>(directly).--pr <n>, and--run <n>against a run that was itself PR-triggered, both refuse instead of dispatching: a workflow-dispatch run writes no commit status, so it can't clear a red(pull_request)check on that PR's sha — re-run from the web UI instead.--workflow <file>picks the workflow file for--branch(defaultci.yml). Dispatch re-runs the whole workflow — there is no single-job variant.issue dependency <n> add <dep...>/pr dependency <n> add <dep...>set "blocked by" links via Forgejo's dependency feature — the operator's preferred way to track blocking relationships over labels (labels can go stale; dependencies are structured and show in the forge UI's dependency panel). Same-repo only, matching the web UI (no cross-repo dependency support).list(the default action) andadd/removeall print the resulting dependency list as JSON.issue reaction <n> add <content>/pr reaction <n> add <content>add an emoji reaction (Forgejo's shortcode vocabulary —+1,heart,rocket, …, same set the web UI's picker offers, not a raw emoji character);--comment <id>targets a specific comment's reactions instead of the issue/PR itself.list/add/removeall print the resulting reaction list as JSON, same shape asdependency.view,issue,pr, andcomment-showalways show a reaction summary;comments --show-reactionsadds one per comment shown (opt-in — one extra request per comment, no server-side inline count).reaction <n> --list-allowedprints the instance's actual configured shortcode list (GET /settings/ui'sallowed_reactions) instead of guessing — instance-global, this path ignores<n>/--comment.- Don't use raw
curlfor forge access -- the CLI handles auth, error checking, and output formatting. issue create --label <name>/pr create --label <name>are repeatable and take the same spellinglabels <n> adddoes. An unknown name is an error, not a silent drop — the command fails listing the names that didn't resolve plus every label the repo has, so it's fixable from the message without a second call. Onpr create --agit, hive-forge applies labels as a follow-up call once it parses the PR number back out of the push output (the AGit push itself has no label field), so they're silently skipped if that parse fails — same fallback as the deferred multi-line body.list --label <name>/list --milestone <name>are repeatable and validated the same way, for a sharper reason: the forge discards a filter value it doesn't recognise, so a typo returns the unfiltered list rather than an empty one. That doesn't waste a query, it inverts the answer — "is anything open in this milestone" comes back as every open issue.--milestonetakes a title or an id, and closed milestones count as valid (filtering on a shipped one is a normal query).- ⚠️
--assignee/--authorare deliberately not validated: someone who has left still legitimately appears on old issues, so a login that isn't a current member isn't necessarily a typo. list --limit Nis a request: the forge clamps page size to its ownapi.MAX_RESPONSE_ITEMS(50 by default), so--limit 400returns at most 50 rows. The stderr trailer (printed in--jsonmode too) is driven by the forge's ownLink: rel="next"/X-HasMoresignal, so it stays right when the forge clamps--limit: while a next page exists it prints the rows shown so far (out of the response'sX-Total-Countwhen sent,… 50 of 187 shown … 137 more) and are-run with --page N+1hint. The last page prints no trailer, so silence means the list is complete. Two cases stay ambiguous: withoutX-Total-Countthe headers didn't come through, and it falls back toN shown … more results may existon a page of exactly--limitrows (silent on a clamped one); a proxy that strips onlyLinkwhile keepingX-Total-Countreads as a last page.repo-searchreadsX-Total-Countthe same waylistdoes and warns with the real remaining count when it's present (… 50 of 187 shown … 137 more exist); without it (an older forge, a stripping proxy) it falls back to the crudercount == limitheuristic, same trust-the-trailer-not-the-row-count principle aslistabove. Unlikelist, this verb has no--page— so once the forge's own page cap has clamped the result (count < limit), raising--limitagain asks for the same clamp and gets nothing new; the warning says to narrow--queryinstead in that case, and only suggests raising--limitwhile still under the cap. Either way it can't tell "doesn't exist" from "you lack permission to see it" — both render as an absent row with no signal either way — and it matches repo name only, not owner, so there's no way to enumerate an org's repos through this verb.