With the GitHub CLI's gh api, how do -f/--raw-field and -F/--field differ, and when does adding them change the HTTP method?
answer
- strings against typed values
- true, false, null and integers
- @file and placeholders
- parameters imply a write
- --method GET sends a query string
basics
~20 s-f always sends a string; -F converts true, false, null and integers to JSON types, fills {owner}/{repo}/{branch} and reads @file. Adding either switches gh api from GET to POST unless --method is given; --method GET sends them as a query string.
solid answer
~40 sBoth flags take `key=value` and build the request parameters. `-f`/`--raw-field` sends the value as a **string**, always. `-F`/`--field` applies "magic" conversion: `true`, `false`, `null` and integers become JSON types, `{owner}`, `{repo}` and `{branch}` are filled from the current repository, and `@path` (or `@-` for standard input) reads the value from a file as a string. Nested values use `key[subkey]=value`, arrays use repeated `key[]=value`, and a bare `key[]` sends an empty array. The method rule is the trap: gh uses `GET` by default and switches to `POST` as soon as any parameter is added, so a read endpoint with fields needs `--method GET` (`-X GET`), which sends them as a query string. For a body that is already JSON, use `--input file.json`; then any field flags go into the query string instead.
code
bash · 9 lines# Open an issue in the current repository (fields imply POST)
gh api repos/{owner}/{repo}/issues \
-f title='No branch ruleset' \
-F [email protected] \
-f 'labels[]=governance' -f 'labels[]=nightly'
# Fields on a read endpoint: force GET so they become a query string
gh api --method GET search/repositories \
-f q='org:acme archived:false' --jq '.total_count'go deeper
Remember the two flags by type: lower-case f for raw strings, upper-case F for typed values, files and placeholders.
Explain the conversion rules, the nested bracket syntax and why adding fields turns a GET into a POST unless --method GET is passed.
Show the failure modes you have debugged: a boolean sent as a string, an accidental POST on a read endpoint, and --input for large documents such as ruleset definitions.
Decide when a script's request bodies have grown complex enough to live in versioned JSON files fed through --input instead of long field lists.
## Two ways to add a parameter `gh api` builds a request body (or query string) from repeated `key=value` flags. There are two flavours and the difference is entirely about **type**. | Flag | Value sent | Conversions | Typical use | |---|---|---|---| | `-f` / `--raw-field` | Always a JSON string | None | Titles, bodies, search queries, anything textual | | `-F` / `--field` | String, boolean, null or integer | `true`/`false`/`null` and integers become JSON types; `{owner}`/`{repo}`/`{branch}` filled; `@file` read | Booleans, numbers, repository-derived values, file contents | So `-F private=true` sends the boolean `true`, while `-f private=true` sends the string `"true"`, which a boolean API field may reject with a validation error. In the other direction, `-F title=2026` sends the integer `2026` to a field that expects text; `-f` is the safe choice for anything that only looks numeric. Only whole numbers are converted: `-F ratio=1.5` stays the string `"1.5"`. ## What `-F` does beyond types - **Placeholders in values.** `-F owner='{owner}'` sends the real owner of the current repository; `-f owner='{owner}'` sends the literal text with braces. - **Files.** `-F [email protected]` sends the file's contents as a string, and `@-` reads standard input. The file is not parsed: a JSON file passed this way arrives as one long string, not as an object. - **GraphQL variables.** For the `graphql` endpoint, every field other than `query` and `operationName` becomes a GraphQL variable, so `-F number=42` arrives as an integer variable. ## Nested values and arrays The REST API often wants objects and arrays. gh builds them from bracket syntax: 1. `-f 'labels[]=governance' -f 'labels[]=nightly'` sends `"labels": ["governance", "nightly"]`. 2. `-F 'required_status_checks[strict]=true'` sends a nested object with a boolean inside. 3. `-f 'labels[]'` with no value sends an empty array, which is how you clear a list. 4. Arrays of objects combine both: `-F 'properties[][property_name]=environment'`, as in gh's own example for organisation custom properties. Quote these arguments: some shells treat brackets as glob patterns, and gh's help warns that shells such as PowerShell give braces their own meaning. ## The method rule The help text says it plainly: the default method is `GET` "normally and `POST` if any parameters were added". - `gh api repos/{owner}/{repo}/issues -f title='No branch ruleset'` is a `POST` and creates an issue. - `gh api search/repositories -f q='org:acme archived:false'` is **also** a `POST`, which the search endpoint does not accept. Add `--method GET` (or `-X GET`) and gh appends the fields to the URL as a query string instead. - `-X PATCH`, `-X PUT` and `-X DELETE` choose the other write methods, with the fields as the JSON body. - `--paginate` only works with `GET` (and with `graphql`), so a paginated read that passes fields needs an explicit `--method GET` as well. ## When the body is already JSON `--input file.json` (or `--input -` for standard input) sends the file as the request body verbatim, which is the cleanest way to send a large nested document such as a ruleset definition. Like fields, `--input` implies `POST` unless `--method` says otherwise. When `--input` is used, any `-f`/`-F` flags are added to the **query string** rather than merged into the body, which surprises people who try to "patch" a JSON file with an extra field. ## Seeing what was actually sent When a call is rejected with a validation error, the fastest check is to look at the request rather than re-read the flags: | Command shape | Method | Where the fields go | |---|---|---| | `gh api PATH -f a=1` | `POST` | JSON body, `"a": "1"` | | `gh api PATH -F a=1` | `POST` | JSON body, `"a": 1` | | `gh api -X GET PATH -f a=1` | `GET` | Query string, `?a=1` | | `gh api PATH --input body.json -f a=1` | `POST` | Body from the file; `a=1` in the query string | - `--verbose` prints the full request and response, so the body gh built is visible (it cannot be combined with `--jq`, `--template` or `--silent`). - `GH_DEBUG=api` logs the HTTP traffic of any gh command on standard error, which also helps when the call happens inside a script or an extension. ## Interview angle The question separates people who have scripted the API from people who have read the flag list. Good answers mention the silent type mistake (`"true"` against `true`), the accidental `POST` on a read endpoint, and `--input` for anything deeply nested.
- Why does gh api -F [email protected] not send the JSON object you wrote in the file?With `-F`, `@path` reads the file's contents as a string value for the key `body`, so the API receives one JSON string, not an object. To send a pre-built document as the whole request body, use `--input payload.json`.
- Your paginated read with -f filters fails although the endpoint is a list. What did you miss?Adding fields switched the request to `POST`, which a list endpoint does not serve, so there is nothing to page. Pass `--method GET` so the fields go into the query string and pagination follows the `next` links.
- How do you send an empty array to clear a list field with gh api?Declare the key with brackets and no value, for example `-f 'labels[]'`. gh sends `"labels": []`. A repeated `key[]=value` adds elements instead.
- -f and -F are aliases for the same flag
- -f private=true sends a JSON boolean
- gh api always uses GET unless you pass --method
- -F [email protected] sends the file as a JSON object
- Field flags are merged into the --input body