Allod/tools
2
0
Fork 0
Code Issues 3 Pull requests Projects Releases Packages Wiki Activity Actions

forge: adopt gh-style flags for content args #20

New issue
Closed
opened 2026-06-04 18:37:34 +01:00 by vnprc-agent · 0 comments
vnprc-agent commented 2026-06-04 18:37:34 +01:00
Member
Copy link

Motivation

gh has effectively become the industry standard CLI for git forges. Matching its flag conventions reduces cognitive load for both humans and agents — muscle memory transfers, and agents that know gh will use forge correctly without guessing.

The current forge uses positional args for content fields (title, body, base). This is fine for simple lookup commands but breaks down when fields are optional or multi-line — you can't skip title to update only body in pr edit, and long body strings are awkward positionally.

Proposed changes

All commands that accept a body string should support both --body <string> and --body-file <file>, matching gh. Pass - as the file to read from stdin. This avoids shell quoting gymnastics with backticks and multiline strings — agents write content to a file and pass the path.

forge pr create

# current
forge pr create <title> <head> [base] [body]

# proposed (matching gh pr create)
forge pr create --title <title> [--head <branch>] [--base <branch>] [--body <string> | --body-file <file>]

--head should default to the current branch, same as gh.

forge pr edit

# current
forge pr edit <number> [title] [body]

# proposed (matching gh pr edit)
forge pr edit <number> [--title <title>] [--body <string> | --body-file <file>]

forge pr comment

# current
forge pr comment <number> <body>

# proposed (matching gh pr comment)
forge pr comment <number> [--body <string> | --body-file <file>]

forge pr reply

No gh equivalent, but consistent with the above:

# current
forge pr reply <number> <comment-id> <body>

# proposed
forge pr reply <number> <comment-id> [--body <string> | --body-file <file>]

forge issue create (new — required)

forge issue create --title <title> [--body <string> | --body-file <file>]

Needed immediately: filing this issue required hitting the Forgejo API directly because forge had no issue create command.

forge issue edit (new — required)

forge issue edit <number> [--title <title>] [--body <string> | --body-file <file>]

Needed immediately: updating this issue required hitting the Forgejo API directly for the same reason. The lack of --body-file also forced writing a temp file and using jq --rawfile to avoid backtick quoting issues in shell heredocs.

Commands that stay as-is

Positional identifiers are already consistent with gh:

  • forge pr view <number>
  • forge pr list
  • forge pr review-comments <number>
  • forge pr find-by-head <branch>
  • forge issue view <number>
  • forge issue list

Future commands (add when there is a concrete need)

  • forge pr merge <number> — matches gh pr merge
  • forge pr close <number> — matches gh pr close
  • forge issue close <number> — matches gh issue close
## Motivation `gh` has effectively become the industry standard CLI for git forges. Matching its flag conventions reduces cognitive load for both humans and agents — muscle memory transfers, and agents that know `gh` will use `forge` correctly without guessing. The current `forge` uses positional args for content fields (title, body, base). This is fine for simple lookup commands but breaks down when fields are optional or multi-line — you can't skip `title` to update only `body` in `pr edit`, and long body strings are awkward positionally. ## Proposed changes All commands that accept a body string should support both `--body <string>` and `--body-file <file>`, matching `gh`. Pass `-` as the file to read from stdin. This avoids shell quoting gymnastics with backticks and multiline strings — agents write content to a file and pass the path. ### `forge pr create` ``` # current forge pr create <title> <head> [base] [body] # proposed (matching gh pr create) forge pr create --title <title> [--head <branch>] [--base <branch>] [--body <string> | --body-file <file>] ``` `--head` should default to the current branch, same as `gh`. ### `forge pr edit` ``` # current forge pr edit <number> [title] [body] # proposed (matching gh pr edit) forge pr edit <number> [--title <title>] [--body <string> | --body-file <file>] ``` ### `forge pr comment` ``` # current forge pr comment <number> <body> # proposed (matching gh pr comment) forge pr comment <number> [--body <string> | --body-file <file>] ``` ### `forge pr reply` No `gh` equivalent, but consistent with the above: ``` # current forge pr reply <number> <comment-id> <body> # proposed forge pr reply <number> <comment-id> [--body <string> | --body-file <file>] ``` ### `forge issue create` (new — required) ``` forge issue create --title <title> [--body <string> | --body-file <file>] ``` Needed immediately: filing this issue required hitting the Forgejo API directly because `forge` had no `issue create` command. ### `forge issue edit` (new — required) ``` forge issue edit <number> [--title <title>] [--body <string> | --body-file <file>] ``` Needed immediately: updating this issue required hitting the Forgejo API directly for the same reason. The lack of `--body-file` also forced writing a temp file and using `jq --rawfile` to avoid backtick quoting issues in shell heredocs. ## Commands that stay as-is Positional identifiers are already consistent with `gh`: - `forge pr view <number>` - `forge pr list` - `forge pr review-comments <number>` - `forge pr find-by-head <branch>` - `forge issue view <number>` - `forge issue list` ## Future commands (add when there is a concrete need) - `forge pr merge <number>` — matches `gh pr merge` - `forge pr close <number>` — matches `gh pr close` - `forge issue close <number>` — matches `gh issue close`
vnprc closed this issue 2026-06-06 18:30:16 +01:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
master
No results found.
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
Allod/tools#20
No description provided.