# 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`](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 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 ` / `issue ` 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). ```bash 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 - < # 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 # 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 ` | prose dump; **marks the thread read** (clears the read-before-comment guard). Top-level `view` autodetects issue-or-PR by number; scoped `issue view ` / `pr view ` do the same when you already know the kind | | Just the structured metadata of one item (state, labels, assignees, head sha…) | `issue ` / `pr ` | 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 ` [`--tail N`] | comment + review-body list; **marks read** | | One specific comment by its id | `comment-show ` | single comment | | The audit trail — closes, label/assignee changes, commit refs, merges (no comment bodies) | `timeline ` | event list | | The code change | `pr diff ` | unified diff | | Is this PR ready to merge — mergeable + CI + reviews | `pr status ` | health view; exit code = merge-readiness | | The review verdicts + inline review comments | `pr reviews ` | 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//`. 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 --help` prints the full signature for any verb. ### `pr status` One-stop PR health view (``, positional — `--pr ` 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 ` 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/`) 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 `** — create a repo under the authenticated user and print its URL. Not available to agent accounts. Key flags: - `--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 ` — repo description **`repo-add-collaborator `** — 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 ` 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 ` or `hive-forge comments ` (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 ` 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 --run ` downloads a CI Actions artifact. `` is the run number from the run-page URL (`/actions/runs/`, 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-.zip` by default; pass `-o -` to stream to stdout. - `ci-log --run [--job i] [--step i] [--attempt n]` prints a CI run's job step logs. `` 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//jobs//attempt//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//dispatches {"ref":""}`). Resolve the branch with `--run ` (the same run number `ci-log` / `artifact-get` take — resolves the branch + workflow from that run) or `--branch ` (directly). `--pr `, and `--run ` 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 ` picks the workflow file for `--branch` (default `ci.yml`). Dispatch re-runs the whole workflow — there is no single-job variant. - `issue dependency add ` / `pr dependency add ` 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 add ` / `pr reaction add ` 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 ` 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 --list-allowed` prints the instance's actual configured shortcode list (`GET /settings/ui`'s `allowed_reactions`) instead of guessing — instance-global, this path ignores ``/`--comment`. - **Don't** use raw `curl` for forge access -- the CLI handles auth, error checking, and output formatting. - `issue create --label ` / `pr create --label ` are repeatable and take the same spelling `labels 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 ` / `list --milestone ` 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.