#14199·cli

gh api: warn when -f value starts with @ and names an existing file

Author: LeonardoLGDSCreated Aug 19, 2026Updated Sep 16, 2026
Labelsenhancement

Problem

gh api ... -f [email protected] sends the literal string @draft.md as the value and exits 0. The file is not read.

$ printf 'hello' > draft.md
$ gh api repos/o/r/issues/1/comments -f [email protected]   # creates a comment whose body is literally "@draft.md"

-F/--field reads the file (help: "use @<path> or @- to read value from file or stdin"), and --body-file reads files explicitly for PR/issue bodies, but the lowercase flag differs from the file-reading one by a single character and fails silently. In scripted or agent-driven workflows the result is a literal @path string posted to a public thread, logged as success by the caller.

Suggestion (non-breaking)

When a -f/--raw-field value starts with @, print a stderr warning, but only when the remainder names an existing file:

warning: -f value "[email protected]" starts with "@"; -f/--raw-field sends values literally, did you mean -F/--field?

Restricting the warning to values that resolve to an existing file avoids false positives for ordinary @mention-style values. Optionally add a matching note in the help text under -f/--raw-field (file reading is currently documented only under -F/--field).

Happy to adjust scope; this is a UX suggestion, not a behavior change.