Watch
0
0
Fork
You've already forked hyperhive
0
hyperhive/docs/4-implementation/agent-tools/forge.md
atlas 1edeb5c55d agents get a per-agent repo limit in their permissions record, orgs are locked
max_repos (default 0, 0..=100) lives in the agent's agent-permissions record and is edited on its permissions panel. The controller applies each agent's own value as max_repo_creation at CreateForgeUser and to existing accounts on change, restart and every five minutes; agent accounts may not create organizations.
2026-11-16 01:21:25 +01:00

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/--repo flag

    the origin remote of the cwd's git checkout > $HIVE_FORGE_REPO (last-resort override, unset by default) > a hard error. client::Client::from_env assumes no single repo by default.

  • Deadline: one invocation runs for at most $HIVE_FORGE_DEADLINE seconds (default 900, five minutes above the largest per-request budget). Past it, hive-forge prints hive-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 unless the operator allows it for that agent: swarm-controller sets the account's repo-creation limit to the agent's own max_repos, which is 0 until the operator raises it (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: comment refuses to post when forge still has an unread notification for the thread. hive-forge-notify marks 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 with hive-forge view <n> or hive-forge comments <n> (which mark the notification read and clear the block), or pass --force to skip the guard.
  • comment --body "..." with backticks in the body: always use --body-file - with a HEREDOC to avoid shell escaping issues.
  • pr create --push also runs git push forge <head> and suppresses the post-push "Create a pull request" hint (hive-forge prints the canonical URL itself).
  • attachment-get saves 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>, which pr status surfaces 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>.zip by 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 value artifact-get takes; pr status surfaces 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 live act_runner task record, so a still-buffering multi-minute phase can come back thin). Passing --step reverses that order — only the streamer honors per-step framing (the persisted log is flat), so --step goes straight to the streamer and an out-of-range index surfaces as a hard error instead of silently falling back. --job selects the job (0-based, default 0); --attempt picks the run attempt for the durable path (default 1; re-runs increment it). --json wraps the output.
  • ci-rerun re-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 number ci-log / artifact-get take — 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 (default ci.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) and add/ remove all 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/remove all print the resulting reaction list as JSON, same shape as dependency. view, issue, pr, and comment-show always show a reaction summary; comments --show-reactions adds one per comment shown (opt-in — one extra request per comment, no server-side inline count). reaction <n> --list-allowed prints the instance's actual configured shortcode list (GET /settings/ui's allowed_reactions) instead of guessing — instance-global, this path ignores <n>/--comment.
  • Don't use raw curl for 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 spelling labels <n> add does. 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. On pr 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. --milestone takes a title or an id, and closed milestones count as valid (filtering on a shipped one is a normal query).
  • ⚠️ --assignee / --author are 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 N is a request: the forge clamps page size to its own api.MAX_RESPONSE_ITEMS (50 by default), so --limit 400 returns at most 50 rows. The stderr trailer (printed in --json mode too) is driven by the forge's own Link: rel="next" / X-HasMore signal, 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's X-Total-Count when sent, … 50 of 187 shown … 137 more) and a re-run with --page N+1 hint. The last page prints no trailer, so silence means the list is complete. Two cases stay ambiguous: without X-Total-Count the headers didn't come through, and it falls back to N shown … more results may exist on a page of exactly --limit rows (silent on a clamped one); a proxy that strips only Link while keeping X-Total-Count reads as a last page.
  • repo-search reads X-Total-Count the same way list does 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 cruder count == limit heuristic, same trust-the-trailer-not-the-row-count principle as list above. Unlike list, this verb has no --page — so once the forge's own page cap has clamped the result (count < limit), raising --limit again asks for the same clamp and gets nothing new; the warning says to narrow --query instead in that case, and only suggests raising --limit while 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.