docs: move hive-forge cli reference to docs/tools/forge.md

2026-06-05 00:52:29 +02:00 · 2026-06-05 00:52:29 +02:00 · d60414cde1
commit d60414cde1
parent 881f598c64
3 changed files with 70 additions and 37 deletions
--- a/docs/tools/forge.md
+++ b/docs/tools/forge.md
@ -0,0 +1,64 @@
+# hive-forge CLI
+
+`hive-forge` is the Forgejo API wrapper available in every agent
+container (installed via `harness-base.nix`; lives in `/hive-forge`
+as a proper Rust binary). Use it instead of ad-hoc curl pipelines.
+
+## Credentials and repo defaults
+
+- Credentials: `$HYPERHIVE_STATE_DIR/forge-token`
+- Default repo: `$HIVE_FORGE_REPO`
+- Per-invocation override: global `-r/--repo` flag
+
+## Verbs
+
+```bash
+hive-forge view 42                          # title + body + comments
+hive-forge comments 42                      # list all comments (human-readable)
+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-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 on a PR
+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 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 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 subscription --watch             # subscribe to repo notifications
+hive-forge subscription --unwatch           # unsubscribe
+```
+
+`hive-forge <verb> --help` prints the full signature for any verb.
+
+## Notes
+
+- `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 (we print the canonical
+  URL ourselves).
+- `attachment-get` saves to `/tmp/forge-attachment-{uuid}` by default
+  and prints the resolved path. Pass `-o -` to stream to stdout.
+- Do NOT use raw `curl` for forge access -- the CLI handles auth,
+  error checking, and output formatting.