docs: move hive-forge cli reference to docs/tools/forge.md
This commit is contained in:
damocles
mara
parent
881f598c64
commit
d60414cde1
3 changed files with 70 additions and 37 deletions
|
|
@ -363,7 +363,7 @@ docs/
|
|||
inbox, live view, per-agent endpoints, stats)
|
||||
turn-loop.md claude invocation, wake prompt, MCP tool surface
|
||||
tools/ per-group tool docs (bash.md, lifecycle.md,
|
||||
scheduling.md, matrix.md)
|
||||
scheduling.md, matrix.md, forge.md)
|
||||
approvals.md approval flow, manager policy, helper events
|
||||
persistence.md sqlite dbs, retention, state dir layout
|
||||
terminal-rendering.md per-agent terminal row taxonomy (as built)
|
||||
|
|
@ -417,6 +417,9 @@ read them à la carte.
|
|||
- **"How do per-agent forge accounts work? What does forge_notify
|
||||
poll + how does it format wake messages?"** →
|
||||
[`docs/forge.md`](docs/forge.md).
|
||||
- **"What verbs does `hive-forge` support? How do I post a comment,
|
||||
upload an attachment, manage subscriptions?"** →
|
||||
[`docs/tools/forge.md`](docs/tools/forge.md).
|
||||
- **"How does the matrix-tuwunel container work? What about
|
||||
fluffychat-web and per-agent matrix accounts?"** →
|
||||
[`docs/matrix.md`](docs/matrix.md).
|
||||
|
|
|
|||
|
|
@ -195,42 +195,8 @@ instead of `meta#nixosConfigurations.argus.config…`. The fix:
|
|||
|
||||
## `hive-forge`: prefer over raw curl pipelines
|
||||
|
||||
Every agent container has `hive-forge` in PATH (installed via
|
||||
`harness-base.nix`; lives in `/hive-forge` as a proper Rust binary).
|
||||
Use it instead of ad-hoc curl pipelines:
|
||||
|
||||
```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 assign 42 damocles
|
||||
hive-forge close 42
|
||||
hive-forge labels 42 add feature
|
||||
hive-forge pr 42 # PR metadata as JSON
|
||||
hive-forge pr-create --title "..." --head my-branch --push # also `git push forge my-branch`, suppressing the post-push "Create a pull request" hint
|
||||
hive-forge diff 42 # unified diff (lockfile hunks collapsed by default)
|
||||
hive-forge diff 42 --full # include unfiltered lockfile hunks
|
||||
hive-forge branches deployed/ # filter branches by pattern
|
||||
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
|
||||
hive-forge attach-comment 18042 /path/to/file # upload a file attachment to a comment
|
||||
hive-forge attachment-get <uuid> # download an attachment; prints resolved path to stdout
|
||||
hive-forge subscription --watch # subscribe to repo notifications
|
||||
```
|
||||
|
||||
`hive-forge <verb> --help` prints the full signature for any verb.
|
||||
Credentials come from `$HYPERHIVE_STATE_DIR/forge-token`; default
|
||||
repo from `$HIVE_FORGE_REPO`, overridden per-invocation by the
|
||||
global `-r/--repo` flag.
|
||||
Full CLI reference: [`docs/tools/forge.md`](tools/forge.md).
|
||||
Never use raw `curl` for forge access.
|
||||
|
||||
## Containerized nix-daemon needs `sandbox-fallback = true`
|
||||
|
||||
|
|
|
|||
64
docs/tools/forge.md
Normal file
64
docs/tools/forge.md
Normal file
|
|
@ -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.
|
||||
Loading…
Reference in a new issue