vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
hyperhive/docs/tools/forge-cli.md

41 KiB
Raw Blame History

Command-Line Help for hive-forge

This document contains the help content for the hive-forge command-line program.

Command Overview:

hive-forge

Forgejo CLI wrapper for hyperhive

Usage: hive-forge [OPTIONS] <COMMAND>

Subcommands:
  • issue — Issue-scoped commands: issue <show|create|edit|view|comment|comments|close|reopen|labels|assign|dependency|reaction|timeline> …
  • pr — PR-scoped commands: pr <show|status|create|merge|reviews|assign-reviewer|commits|diff|view|edit|comment|comments|close|reopen|labels|assign-committer|dependency|reaction|timeline> …
  • comment-show — Print the body (or full JSON) of a single comment by id
  • comment-edit — Edit an existing comment by id
  • clone — Clone a forge repo (default -r/HIVE_FORGE_REPO) with credentials auto-injected. Pairs with pr-create --agit
  • repo-create — Create a forge repo under the current user (or --org). Prints the repo URL
  • repo-add-collaborator — Add a collaborator to the active repo (-r/HIVE_FORGE_REPO) with a permission level. Companion to repo-create
  • repo-labels — List every label defined on the repo (name + description), optionally filtered by a name substring
  • repo-search — Search the forge for repositories by keyword, topic, or description
  • lint — Triage lint queries (unassigned / no-reviewer / stale-branches / assignments / unlabeled)
  • list — List issues / PRs with filters (--kind, --state, --assignee, --author, --label, --limit). Pretty rows by default; pass --json for raw JSON
  • milestone — Manage milestones (list / create / close)
  • branches — List branches, optionally filtered
  • tree-sha — Print the tree SHA at a branch or commit
  • subscription — Get/set this user's watch subscription on a repo, or --list all watched repos
  • attach-issue — Upload a file as an attachment to an issue
  • attach-comment — Upload a file as an attachment to a comment
  • attachment-get — Download an attachment by UUID or URL. Saves to a temp file and prints the path (pass -o - to stream raw bytes to stdout)
  • artifact-get — Download a CI Actions artifact from a run (<name> --run <n>). Saves a zip, or pass -o - to stream to stdout
  • ci-log — Print a CI Actions run's job step logs (--run <n> [--job i] [--step i])
  • ci-rerun — Re-run CI without an empty commit. Pass one of --pr <n>, --run <n>, or --branch <name>; --workflow defaults to ci.yml
  • ci-runs — List CI Actions runs, newest first (--workflow, --branch, --limit, --page) — the run numbers ci-log/ci-rerun --run/ artifact-get --run take
Options:
  • -r, --repo <REPO> — Repo to act on, as owner/name (default: inferred from the cwd's git origin remote, then HIVE_FORGE_REPO). Works with any verb
  • -f, --forge <FORGE> — Act as a dashboard-provisioned external forge account (by its FORGES-tab label) instead of the internal forge. Independent of -r/--repo
  • --json — Emit JSON instead of the default human-readable output (for verbs that support both)

hive-forge issue

Issue-scoped commands: issue <show|create|edit|view|comment|comments|close|reopen|labels|assign|dependency|reaction|timeline> …

Usage: hive-forge issue <COMMAND>

Subcommands:
  • show — Show issue metadata as JSON
  • create — Create an issue
  • edit — Edit an issue's title / body / state / milestone
  • view — Show title + body + comments
  • comment — Post a comment on the issue
  • comments — List comments on the issue
  • close — Close the issue
  • reopen — Reopen a closed issue
  • labels — List / add / remove labels
  • assign — Assign or unassign a user
  • dependency — List / add / remove dependencies (issues this one is blocked by)
  • reaction — List / add / remove emoji reactions on the issue, or on one of its comments with --comment <id>
  • timeline — List timeline events

hive-forge issue show

Show issue metadata as JSON

Usage: hive-forge issue show <NUMBER>

Arguments:
  • <NUMBER> — Issue number

hive-forge issue create

Create an issue

Usage: hive-forge issue create [OPTIONS] --title <TITLE>

Options:
  • --title <TITLE> — Issue title (required)
  • --body <BODY> — Inline body text
  • --body-file <BODY_FILE> — Read body from a file. - means stdin
  • --assignee <ASSIGNEE> — Initial assignee login
  • --label <LABELS> — Label name to attach, repeatable (e.g. --label area/ops --label type/bug). Same spelling labels add accepts. An unresolved name errors out (before the issue is created) rather than silently attaching fewer labels than asked for

hive-forge issue edit

Edit an issue's title / body / state / milestone

Usage: hive-forge issue edit [OPTIONS] <NUMBER>

Arguments:
  • <NUMBER> — Issue (or PR — shares the same /issues/<n> endpoint) number
Options:

  • --title <TITLE> — New title (omit to leave unchanged)

  • --body <BODY> — Inline body text (omit to leave unchanged)

  • --body-file <BODY_FILE> — Read body from a file. - means stdin

  • --state <STATE> — New state

    Possible values: open, closed

  • --milestone <MILESTONE> — Milestone id (0 to unset)

hive-forge issue view

Show title + body + comments

Usage: hive-forge issue view <NUMBER>

Arguments:
  • <NUMBER> — Issue or PR number

hive-forge issue comment

Post a comment on the issue

Usage: hive-forge issue comment [OPTIONS] <NUMBER>

Arguments:
  • <NUMBER> — Issue or PR number
Options:
  • --body <BODY> — Inline body text
  • --body-file <BODY_FILE> — Read body from a file. - means stdin
  • --force — Post even when the thread has unread activity (skips the read-before-comment guard)

hive-forge issue comments

List comments on the issue

Usage: hive-forge issue comments [OPTIONS] <NUMBER>

Arguments:
  • <NUMBER> — Issue or PR number
Options:

  • --limit <LIMIT> — Number of comments from the start of the thread, or (with --since) the most this call returns — capped at [crate::verbs::MAX_LIMIT] in the latter case. Mutually exclusive with --tail

    Default value: 10

  • --tail <TAIL> — Return the last N comments (chronological). Mutually exclusive with --limit/--since

  • --since <SINCE> — Only show comments at or after this RFC3339 timestamp (same format this verb's own output prints). Mutually exclusive with --tail

  • --show-reactions — Fetch + display each shown comment's reaction summary. Costs one extra request per comment shown — opt-in, not the default

hive-forge issue close

Close the issue

Usage: hive-forge issue close <NUMBER>

Arguments:
  • <NUMBER> — Issue or PR number

hive-forge issue reopen

Reopen a closed issue

Usage: hive-forge issue reopen <NUMBER>

Arguments:
  • <NUMBER> — Issue or PR number

hive-forge issue labels

List / add / remove labels

Usage: hive-forge issue labels <NUMBER> [COMMAND]

Subcommands:
  • list — List labels (default when no action is given)
  • add — Add labels by name
  • remove — Remove labels by name
Arguments:
  • <NUMBER> — Issue or PR number

hive-forge issue labels list

List labels (default when no action is given)

Usage: hive-forge issue labels list

hive-forge issue labels add

Add labels by name

Usage: hive-forge issue labels add [LABELS]...

Arguments:
  • <LABELS> — Label names to add

hive-forge issue labels remove

Remove labels by name

Usage: hive-forge issue labels remove [LABELS]...

Arguments:
  • <LABELS> — Label names to remove

hive-forge issue assign

Assign or unassign a user

Usage: hive-forge issue assign [OPTIONS] <NUMBER> <USER>

Arguments:
  • <NUMBER> — Issue or PR number
  • <USER> — User login to assign (or unassign with --remove)
Options:
  • --remove — Remove the user instead of adding

hive-forge issue dependency

List / add / remove dependencies (issues this one is blocked by)

Usage: hive-forge issue dependency <NUMBER> [COMMAND]

Subcommands:
  • list — List dependencies (default when no action is given) — the issues/PRs this one is blocked by
  • add — Add one or more issues/PRs this one is blocked by
  • remove — Remove one or more dependency links
Arguments:
  • <NUMBER> — Issue or PR number

hive-forge issue dependency list

List dependencies (default when no action is given) — the issues/PRs this one is blocked by

Usage: hive-forge issue dependency list

hive-forge issue dependency add

Add one or more issues/PRs this one is blocked by

Usage: hive-forge issue dependency add [DEPS]...

Arguments:
  • <DEPS> — Issue/PR numbers to add as dependencies

hive-forge issue dependency remove

Remove one or more dependency links

Usage: hive-forge issue dependency remove [DEPS]...

Arguments:
  • <DEPS> — Issue/PR numbers to remove as dependencies

hive-forge issue reaction

List / add / remove emoji reactions on the issue, or on one of its comments with --comment <id>

Usage: hive-forge issue reaction [OPTIONS] <NUMBER> [COMMAND]

Subcommands:
  • list — List reactions (default when no action is given)
  • add — Add a reaction — a Forgejo shortcode, e.g. +1, heart, rocket
  • remove — Remove your own reaction with this content
Arguments:
  • <NUMBER> — Issue or PR number. Ignored (but still required) when --list-allowed is set
Options:
  • --comment <COMMENT> — Target a specific comment's reactions instead of the issue/PR itself — the comment's own id (from comments/comment-show), not its position in the thread
  • --list-allowed — Print the instance's actual configured reaction shortcodes (GET /settings/ui) instead of listing/adding/removing — instance-global, ignores number/--comment

hive-forge issue reaction list

List reactions (default when no action is given)

Usage: hive-forge issue reaction list

hive-forge issue reaction add

Add a reaction — a Forgejo shortcode, e.g. +1, heart, rocket

Usage: hive-forge issue reaction add <CONTENT>

Arguments:
  • <CONTENT>

hive-forge issue reaction remove

Remove your own reaction with this content

Usage: hive-forge issue reaction remove <CONTENT>

Arguments:
  • <CONTENT>

hive-forge issue timeline

List timeline events

Usage: hive-forge issue timeline [OPTIONS] <NUMBER>

Arguments:
  • <NUMBER> — Issue or PR number
Options:

  • --limit <LIMIT> — Return the first N events, capped at 49 (see the module doc comment for why). Default kept small on purpose

    Default value: 10

  • --since <SINCE> — Only show events at or after this RFC3339 timestamp (same format this verb's own output prints) — pass back the last-seen row's created_at to fetch only what's new

hive-forge pr

PR-scoped commands: pr <show|status|create|merge|reviews|assign-reviewer|commits|diff|view|edit|comment|comments|close|reopen|labels|assign-committer|dependency|reaction|timeline> …

Usage: hive-forge pr <COMMAND>

Subcommands:
  • show — Show PR metadata as JSON
  • commits — List the PR's commits as JSON
  • create — Create a pull request
  • status — PR health view: mergeable / CI / reviews
  • merge — Merge the PR
  • reviews — List a PR's reviews, or submit one
  • assign-reviewer — Request (or withdraw with --remove) a review from a user
  • diff — Print the PR's unified diff
  • view — Show title + body + comments
  • edit — Edit the PR's title / body / state / milestone. Fields not passed are left unchanged
  • comment — Post a comment on the PR
  • comments — List comments on the PR
  • close — Close the PR
  • reopen — Reopen a closed PR
  • labels — List / add / remove labels
  • assign-committer — Assign or unassign a user (the PR's assignee list)
  • dependency — List / add / remove dependencies (issues/PRs this one is blocked by)
  • reaction — List / add / remove emoji reactions on the PR, or on one of its comments with --comment <id>
  • timeline — List timeline events

hive-forge pr show

Show PR metadata as JSON

Usage: hive-forge pr show <NUMBER>

Arguments:
  • <NUMBER> — PR number

hive-forge pr commits

List the PR's commits as JSON

Usage: hive-forge pr commits <NUMBER>

Arguments:
  • <NUMBER> — PR number

hive-forge pr create

Create a pull request

Usage: hive-forge pr create [OPTIONS] --title <TITLE>

Options:

  • --title <TITLE> — PR title

  • --head <HEAD> — Head branch. Not required (and ignored) in --agit mode, which pushes the current HEAD

  • --base <BASE> — Base branch (default: main)

    Default value: main

  • --body <BODY> — Inline body text

  • --body-file <BODY_FILE> — Read body from a file. - means stdin

  • --draft — Open as draft. Ignored in --agit mode

  • --push — Push the local --head branch to --remote before creating the PR

  • --remote <REMOTE> — Remote to push to (default: forge, or origin in --agit mode)

  • --agit — Open the PR via Forgejo's AGit flow instead of pushing a branch — works for read-only collaborators. Run from inside a cloned repo

  • --topic <TOPIC> — AGit topic — groups repeated pushes into one PR (re-run with the same topic to update it). Defaults to the branch name. Only meaningful with --agit

  • --label <LABELS> — Label name to attach, repeatable (e.g. --label area/ops --label type/bug). Same spelling labels add accepts — an unresolved name errors out rather than silently attaching fewer labels than asked for. In --agit mode this is applied as a follow-up call once the PR number is known (the AGit push itself has no label field), so it's silently skipped (not a label-resolution error) if the PR URL couldn't be parsed back out of the push output — same fallback as the deferred multi-line body

hive-forge pr status

PR health view: mergeable / CI / reviews

Usage: hive-forge pr status [OPTIONS]

Options:
  • --pr <PR> — PR number — full health view (mergeable, CI, reviews, last comment). Mutually exclusive with --sha
  • --sha <SHA> — Explicit commit sha (or ref) — CI-only fast path. Mutually exclusive with --pr

hive-forge pr merge

Merge the PR

Usage: hive-forge pr merge [OPTIONS] <NUMBER>

Arguments:
  • <NUMBER> — PR number to merge
Options:

  • --method <METHOD> — Merge strategy (default: a merge commit). Squash is not offered

    Default value: merge

    Possible values:

    • merge: Create a merge commit
    • rebase: Rebase the head branch onto the base, then fast-forward

  • --keep-branch — Keep the head branch after merging (deleted by default)

  • --force — Merge even if the PR is not mergeable, CI is not green, or a review requests changes

hive-forge pr reviews

List a PR's reviews, or submit one

Usage: hive-forge pr reviews [OPTIONS] <NUMBER>

Arguments:
  • <NUMBER> — PR number
Options:
  • --approve — Approve the PR (submit an APPROVED review)
  • --request-changes — Request changes on the PR (submit a REQUEST_CHANGES review)
  • --comment — Leave a comment review (submit a COMMENT review)
  • -m, --body <BODY> — Optional body / message for the review (used with --approve, --request-changes, or --comment)

hive-forge pr assign-reviewer

Request (or withdraw with --remove) a review from a user

Usage: hive-forge pr assign-reviewer [OPTIONS] <NUMBER> <USER>

Arguments:
  • <NUMBER> — PR number
  • <USER> — User login to request a review from (or withdraw with --remove)
Options:
  • --remove — Withdraw the review request instead of adding it

hive-forge pr diff

Print the PR's unified diff

Usage: hive-forge pr diff [OPTIONS] <NUMBER>

Arguments:
  • <NUMBER> — PR number
Options:
  • --full — Print the unfiltered diff. By default, autogenerated-file hunks (flake.lock, Cargo.lock, …) are collapsed to a placeholder so human-authored changes stay readable

hive-forge pr view

Show title + body + comments

Usage: hive-forge pr view <NUMBER>

Arguments:
  • <NUMBER> — Issue or PR number

hive-forge pr edit

Edit the PR's title / body / state / milestone. Fields not passed are left unchanged

Usage: hive-forge pr edit [OPTIONS] <NUMBER>

Arguments:
  • <NUMBER> — Issue (or PR — shares the same /issues/<n> endpoint) number
Options:

  • --title <TITLE> — New title (omit to leave unchanged)

  • --body <BODY> — Inline body text (omit to leave unchanged)

  • --body-file <BODY_FILE> — Read body from a file. - means stdin

  • --state <STATE> — New state

    Possible values: open, closed

  • --milestone <MILESTONE> — Milestone id (0 to unset)

hive-forge pr comment

Post a comment on the PR

Usage: hive-forge pr comment [OPTIONS] <NUMBER>

Arguments:
  • <NUMBER> — Issue or PR number
Options:
  • --body <BODY> — Inline body text
  • --body-file <BODY_FILE> — Read body from a file. - means stdin
  • --force — Post even when the thread has unread activity (skips the read-before-comment guard)

hive-forge pr comments

List comments on the PR

Usage: hive-forge pr comments [OPTIONS] <NUMBER>

Arguments:
  • <NUMBER> — Issue or PR number
Options:

  • --limit <LIMIT> — Number of comments from the start of the thread, or (with --since) the most this call returns — capped at [crate::verbs::MAX_LIMIT] in the latter case. Mutually exclusive with --tail

    Default value: 10

  • --tail <TAIL> — Return the last N comments (chronological). Mutually exclusive with --limit/--since

  • --since <SINCE> — Only show comments at or after this RFC3339 timestamp (same format this verb's own output prints). Mutually exclusive with --tail

  • --show-reactions — Fetch + display each shown comment's reaction summary. Costs one extra request per comment shown — opt-in, not the default

hive-forge pr close

Close the PR

Usage: hive-forge pr close <NUMBER>

Arguments:
  • <NUMBER> — Issue or PR number

hive-forge pr reopen

Reopen a closed PR

Usage: hive-forge pr reopen <NUMBER>

Arguments:
  • <NUMBER> — Issue or PR number

hive-forge pr labels

List / add / remove labels

Usage: hive-forge pr labels <NUMBER> [COMMAND]

Subcommands:
  • list — List labels (default when no action is given)
  • add — Add labels by name
  • remove — Remove labels by name
Arguments:
  • <NUMBER> — Issue or PR number

hive-forge pr labels list

List labels (default when no action is given)

Usage: hive-forge pr labels list

hive-forge pr labels add

Add labels by name

Usage: hive-forge pr labels add [LABELS]...

Arguments:
  • <LABELS> — Label names to add

hive-forge pr labels remove

Remove labels by name

Usage: hive-forge pr labels remove [LABELS]...

Arguments:
  • <LABELS> — Label names to remove

hive-forge pr assign-committer

Assign or unassign a user (the PR's assignee list)

Usage: hive-forge pr assign-committer [OPTIONS] <NUMBER> <USER>

Arguments:
  • <NUMBER> — Issue or PR number
  • <USER> — User login to assign (or unassign with --remove)
Options:
  • --remove — Remove the user instead of adding

hive-forge pr dependency

List / add / remove dependencies (issues/PRs this one is blocked by)

Usage: hive-forge pr dependency <NUMBER> [COMMAND]

Subcommands:
  • list — List dependencies (default when no action is given) — the issues/PRs this one is blocked by
  • add — Add one or more issues/PRs this one is blocked by
  • remove — Remove one or more dependency links
Arguments:
  • <NUMBER> — Issue or PR number

hive-forge pr dependency list

List dependencies (default when no action is given) — the issues/PRs this one is blocked by

Usage: hive-forge pr dependency list

hive-forge pr dependency add

Add one or more issues/PRs this one is blocked by

Usage: hive-forge pr dependency add [DEPS]...

Arguments:
  • <DEPS> — Issue/PR numbers to add as dependencies

hive-forge pr dependency remove

Remove one or more dependency links

Usage: hive-forge pr dependency remove [DEPS]...

Arguments:
  • <DEPS> — Issue/PR numbers to remove as dependencies

hive-forge pr reaction

List / add / remove emoji reactions on the PR, or on one of its comments with --comment <id>

Usage: hive-forge pr reaction [OPTIONS] <NUMBER> [COMMAND]

Subcommands:
  • list — List reactions (default when no action is given)
  • add — Add a reaction — a Forgejo shortcode, e.g. +1, heart, rocket
  • remove — Remove your own reaction with this content
Arguments:
  • <NUMBER> — Issue or PR number. Ignored (but still required) when --list-allowed is set
Options:
  • --comment <COMMENT> — Target a specific comment's reactions instead of the issue/PR itself — the comment's own id (from comments/comment-show), not its position in the thread
  • --list-allowed — Print the instance's actual configured reaction shortcodes (GET /settings/ui) instead of listing/adding/removing — instance-global, ignores number/--comment

hive-forge pr reaction list

List reactions (default when no action is given)

Usage: hive-forge pr reaction list

hive-forge pr reaction add

Add a reaction — a Forgejo shortcode, e.g. +1, heart, rocket

Usage: hive-forge pr reaction add <CONTENT>

Arguments:
  • <CONTENT>

hive-forge pr reaction remove

Remove your own reaction with this content

Usage: hive-forge pr reaction remove <CONTENT>

Arguments:
  • <CONTENT>

hive-forge pr timeline

List timeline events

Usage: hive-forge pr timeline [OPTIONS] <NUMBER>

Arguments:
  • <NUMBER> — Issue or PR number
Options:

  • --limit <LIMIT> — Return the first N events, capped at 49 (see the module doc comment for why). Default kept small on purpose

    Default value: 10

  • --since <SINCE> — Only show events at or after this RFC3339 timestamp (same format this verb's own output prints) — pass back the last-seen row's created_at to fetch only what's new

hive-forge comment-show

Print the body (or full JSON) of a single comment by id

Usage: hive-forge comment-show <ID>

Arguments:
  • <ID> — Comment id

hive-forge comment-edit

Edit an existing comment by id

Usage: hive-forge comment-edit [OPTIONS] <ID>

Arguments:
  • <ID> — Comment id
Options:
  • --body <BODY> — Inline body text
  • --body-file <BODY_FILE> — Read body from a file. - means stdin

hive-forge clone

Clone a forge repo (default -r/HIVE_FORGE_REPO) with credentials auto-injected. Pairs with pr-create --agit

Usage: hive-forge clone [OPTIONS] [DEST]

Arguments:
  • <DEST> — Destination directory. Defaults to the repo's basename (e.g. internal/knowledge → knowledge)
Options:
  • --branch <BRANCH> — Branch to check out after cloning
  • --depth <DEPTH> — Shallow-clone depth (omit for a full clone)

hive-forge repo-create

Create a forge repo under the current user (or --org). Prints the repo URL

Usage: hive-forge repo-create [OPTIONS] <NAME>

Arguments:
  • <NAME> — Repository name (required). Created under the authenticated user unless --org is given
Options:
  • --description <DESCRIPTION> — Repository description
  • --private — Create the repo as private (default: public)
  • --default-branch <DEFAULT_BRANCH> — Default branch name (e.g. main). Only takes effect with --auto-init
  • --org <ORG> — Create under this organisation instead of your own namespace
  • --auto-init — Seed an initial commit (README) so the repo is non-empty and can be cloned immediately. Omit to create a bare repo you push into

hive-forge repo-add-collaborator

Add a collaborator to the active repo (-r/HIVE_FORGE_REPO) with a permission level. Companion to repo-create

Usage: hive-forge repo-add-collaborator [OPTIONS] <USER>

Arguments:
  • <USER> — Collaborator's forge login to add
Options:

  • --permission <PERMISSION> — Permission level to grant (default: write — a freshly added collaborator usually needs to push)

    Default value: write

    Possible values:

    • read: Pull (read-only) access
    • write: Push (read/write) access
    • admin: Full administrative access to the repo

hive-forge repo-labels

List every label defined on the repo (name + description), optionally filtered by a name substring

Usage: hive-forge repo-labels [PATTERN]

Arguments:
  • <PATTERN> — Substring pattern to filter label names (case-sensitive)

hive-forge repo-search

Search the forge for repositories by keyword, topic, or description

Usage: hive-forge repo-search [OPTIONS]

Options:

  • -q, --query <QUERY> — Keyword to search for (matches repo name by default; combine with --include-desc to also match description text)

  • --topic — Restrict matches to repositories that have the keyword as a topic tag rather than in the name

  • --include-desc — Extend the keyword search to repository descriptions (in addition to names, or topics when --topic is set)

  • --limit <LIMIT> — Maximum number of results to return (default: 30)

    Default value: 30

hive-forge lint

Triage lint queries (unassigned / no-reviewer / stale-branches / assignments / unlabeled)

Usage: hive-forge lint <COMMAND>

Subcommands:
  • unassigned — List issues or PRs without an assignee
  • no-reviewer — List PRs with no formally requested reviewer
  • stale-branches — List remote branches with no commits in N days, each with its merge outcome (skips branches that are heads of open PRs)
  • assignments — Group open issues + PRs by assignee
  • unlabeled — List issues/PRs with no exclusive scoped label in --scope (e.g. --scope type flags items missing any type/* label). Generic — the scope is whatever the repo's label taxonomy actually uses, nothing hardcoded here

hive-forge lint unassigned

List issues or PRs without an assignee

Usage: hive-forge lint unassigned [OPTIONS]

Options:

  • --type <TYPE> — Filter by item kind

    Default value: all

    Possible values: issues, pulls, all

  • --state <STATE> — Filter by item state

    Default value: open

    Possible values: open, closed, all

hive-forge lint no-reviewer

List PRs with no formally requested reviewer

Usage: hive-forge lint no-reviewer [OPTIONS]

Options:

  • --state <STATE> — Filter by PR state

    Default value: open

    Possible values: open, closed, all

  • --reviewer <REVIEWER> — Reviewer login to check for. Omit to flag any PR with zero formally requested reviewers; pass it to instead flag PRs where this specific login isn't among the requested reviewers

hive-forge lint stale-branches

List remote branches with no commits in N days, each with its merge outcome (skips branches that are heads of open PRs)

Usage: hive-forge lint stale-branches [OPTIONS]

Options:

  • --days <DAYS> — Threshold in days since the last commit

    Default value: 14

hive-forge lint assignments

Group open issues + PRs by assignee

Usage: hive-forge lint assignments [OPTIONS]

Options:
  • --user <USER> — Restrict to a single user

hive-forge lint unlabeled

List issues/PRs with no exclusive scoped label in --scope (e.g. --scope type flags items missing any type/* label). Generic — the scope is whatever the repo's label taxonomy actually uses, nothing hardcoded here

Usage: hive-forge lint unlabeled [OPTIONS] --scope <SCOPE>

Options:

  • --scope <SCOPE> — Label scope to check for — the part of a scoped label's name before the / (e.g. type for type/bug, type/feature). Required: this command has no built-in notion of a repo's label taxonomy, so there's no sane default to fall back to

  • --type <TYPE> — Filter by item kind

    Default value: all

    Possible values: issues, pulls, all

  • --state <STATE> — Filter by item state

    Default value: open

    Possible values: open, closed, all

hive-forge list

List issues / PRs with filters (--kind, --state, --assignee, --author, --label, --limit). Pretty rows by default; pass --json for raw JSON

Usage: hive-forge list [OPTIONS]

Command Aliases: issues, issue-list

Options:

  • --kind <KIND> — What to return: issues, PRs, or both (default: both)

    Default value: both

    Possible values:

    • issue: Issues only (excludes PRs)
    • pr: Pull requests only
    • both: Issues + pull requests (default)

  • --state <STATE> — Issue/PR state (default: open)

    Default value: open

    Possible values: open, closed, all

  • --assignee <ASSIGNEE> — Filter to items assigned to this user (single login)

  • --author <AUTHOR> — Filter to items authored by this user (single login)

  • --mention <MENTION> — Filter to items mentioning this user

  • --label <LABELS> — Filter to items carrying any of these label names. Repeatable. Validated client-side: a name the forge can't resolve is dropped from the filter rather than rejected, which returns MORE results than asked for, not fewer

  • --milestone <MILESTONES> — Filter to items in any of these milestones, by title or id. Repeatable. Validated client-side against the repo's milestones (closed ones included), since the forge would silently discard a name it can't resolve and return the UNFILTERED list

  • --search <SEARCH> — Full-text search over title AND body, server-side. Composes with every filter above — this is the duplicate-hunting path that grepping list output can't cover, since grep only ever sees the titles

  • --limit <LIMIT> — Page size — items per page (default: 30). The forge clamps this to its own api.MAX_RESPONSE_ITEMS (50 by default), so a large --limit silently returns a smaller page; the trailer reports the real total rather than trusting this number. Must be >= 1

    Default value: 30

  • --page <PAGE> — Page number to fetch (1-based, default 1). Combine with --limit to page through large result sets incrementally

    Default value: 1

hive-forge milestone

Manage milestones (list / create / close)

Usage: hive-forge milestone [COMMAND]

Subcommands:
  • list — List open milestones as JSON
  • create — Create a milestone, print {id,title}
  • close — Close a milestone by id

hive-forge milestone list

List open milestones as JSON

Usage: hive-forge milestone list

hive-forge milestone create

Create a milestone, print {id,title}

Usage: hive-forge milestone create [OPTIONS] --title <TITLE>

Options:
  • --title <TITLE> — Milestone title
  • --desc <DESC> — Description
  • --due <DUE> — Due date YYYY-MM-DD

hive-forge milestone close

Close a milestone by id

Usage: hive-forge milestone close <ID>

Arguments:
  • <ID> — Milestone id

hive-forge branches

List branches, optionally filtered

Usage: hive-forge branches [PATTERN]

Arguments:
  • <PATTERN> — Substring pattern to filter branch names

hive-forge tree-sha

Print the tree SHA at a branch or commit

Usage: hive-forge tree-sha <REFERENCE>

Arguments:
  • <REFERENCE> — Branch name or commit SHA

hive-forge subscription

Get/set this user's watch subscription on a repo, or --list all watched repos

Usage: hive-forge subscription [OPTIONS]

Options:
  • --watch — Subscribe (watch the repo)
  • --ignore — Mute (mark ignored)
  • --unwatch — Unsubscribe (clear watch + ignore)
  • --list — List every repo the current user watches (ignores [repo])

hive-forge attach-issue

Upload a file as an attachment to an issue

Usage: hive-forge attach-issue <NUMBER> <FILE>

Arguments:
  • <NUMBER> — Issue number
  • <FILE> — File path to upload

hive-forge attach-comment

Upload a file as an attachment to a comment

Usage: hive-forge attach-comment <ID> <FILE>

Arguments:
  • <ID> — Comment id
  • <FILE> — File path to upload

hive-forge attachment-get

Download an attachment by UUID or URL. Saves to a temp file and prints the path (pass -o - to stream raw bytes to stdout)

Usage: hive-forge attachment-get [OPTIONS] <ATTACHMENT>

Arguments:
  • <ATTACHMENT> — Attachment UUID or URL. Accepts a bare UUID (abc-123-...), a root-relative path (/attachments/abc-123-...), or a full URL (http://localhost:3000/attachments/abc-123-...)
Options:
  • -o, --output <OUTPUT> — Output path. Defaults to /tmp/forge-attachment-<uuid>. Pass - to write raw bytes to stdout (e.g. for piping to an image viewer)

hive-forge artifact-get

Download a CI Actions artifact from a run (<name> --run <n>). Saves a zip, or pass -o - to stream to stdout

Usage: hive-forge artifact-get [OPTIONS] --run <RUN> <NAME>

Arguments:
  • <NAME> — Artifact name, as shown on the run page (e.g. pr1ma-paper-pdf)
Options:
  • --run <RUN> — Workflow run number — the runs/<n> in the run-page URL, which pr-status surfaces as a CI context's target_url. (This is the per-repo run number, not the global run id; the verb translates.)
  • -o, --output <OUTPUT> — Output path. Defaults to /tmp/forge-artifact-<name>.zip (Forgejo serves artifacts zipped). Pass - to stream raw bytes to stdout

hive-forge ci-log

Print a CI Actions run's job step logs (--run <n> [--job i] [--step i])

Usage: hive-forge ci-log [OPTIONS] --run <RUN>

Options:

  • --run <RUN> — Workflow run number — the runs/<n> in the run-page URL (shown by pr-status)

  • --job <JOB> — Job index within the run (0-based, default 0)

    Default value: 0

  • --step <STEP> — Print only this step's log (0-based). Omit to print every step

  • --attempt <ATTEMPT> — Run attempt number (re-runs increment it; default 1)

    Default value: 1

hive-forge ci-rerun

Re-run CI without an empty commit. Pass one of --pr <n>, --run <n>, or --branch <name>; --workflow defaults to ci.yml

Usage: hive-forge ci-rerun [OPTIONS]

Options:

  • --pr <PR> — Re-run CI for this PR (its head branch). Mutually exclusive with --run / --branch

  • --run <RUN> — Re-run the same workflow on the same branch this run used. The run number is the runs/<n> in the run-page URL. Mutually exclusive with --pr / --branch

  • --branch <BRANCH> — Re-run --workflow on this branch. Mutually exclusive with --pr / --run

  • --workflow <WORKFLOW> — Workflow file to run (default ci.yml). Ignored for --run, which uses the run's own workflow

    Default value: ci.yml

hive-forge ci-runs

List CI Actions runs, newest first (--workflow, --branch, --limit, --page) — the run numbers ci-log/ci-rerun --run/ artifact-get --run take

Usage: hive-forge ci-runs [OPTIONS]

Options:

  • --workflow <WORKFLOW> — Only runs of this workflow file (e.g. ci.yml)

  • --branch <BRANCH> — Only runs on this ref. A branch name (main, damocles/foo) or a PR (#N) is qualified for you; a refs/… value is used as given. An all-digit value is read as a PR number — to filter a branch literally named that, pass refs/heads/<name>

  • --limit <LIMIT> — How many runs to print (default 20)

    Default value: 20

  • --page <PAGE> — Page number (1-based, default 1). Combine with --limit to page through further back than the default window

    Default value: 1

This document was generated automatically by clap-markdown.