hub-api(1)

💅 hub-api(1) — the low-level GitHub API request interface, bestie ✨

okay so first things first: this is from the hub manual, and it's literally the page that teaches you how to talk directly to the GitHub API like a total main character. no cap, it's giving "I know what I'm doing" energy. let's get into it 🫶

---

🌸 SYNOPSIS 🌸

hub api [-it] [-X METHOD] [-H HEADER] [--cache TTL] ENDPOINT [-F
FIELD|--input FILE]

that's the whole vibe check right there. now let's break it down ✨

---

🎀 OPTIONS 🎀

• -X, --method METHOD — the HTTP method you wanna use for the request, default is "GET". but lowkey it's automatic: the method switches to "POST" if you use --field, --raw-field, or --input. and if you wanna force fields into the query string for a GET request instead of the JSON body of a POST, use -XGET. periodt 💅
• -F, --field KEY=VALUE — data to serialize with the request. here's where it gets iconic: VALUE has some magic handling, so if you want to send arbitrary string values, use --raw-field instead.
  • if VALUE starts with "@", the rest of that value is interpreted as a filename to read from. use "@-" to read from standard input.
  • if VALUE is "true", "false", "null", or looks like a number, an appropriate JSON type is used instead of a string. slay.
  • it is not possible to serialize VALUE as a nested JSON array or hash. instead, construct the request payload externally and pass it via --input. iykyk.

unless -XGET was used, all fields are sent serialized as JSON within the request body. when ENDPOINT is "graphql", all fields other than "query" are grouped under "variables". see ⟨https://graphql.org/learn/queries/#variables⟩ ✨

• -f, --raw-field KEY=VALUE — same as --field, except it allows values starting with "@", literal strings "true", "false", and "null", as well as strings that look like numbers. no magic, just raw vibes 🦋
• --input FILE — the filename to read the raw request body from. use "-" to read from standard input. use this when you wanna manually construct the request payload. you're the main character, you build it yourself 👑
• -H, --header KEY:VALUE — set an HTTP request header. simple, clean, iconic.
• -i, --include — include HTTP response headers in the output. so you can see everything the server is saying, not just the body 💖
• -t, --flat — parse response JSON and output the data in a line-based key-value format suitable for use in shell scripts. literally perfect for when you need things to just work in a script 🌈
• --paginate — automatically request and output the next page of results until all resources have been listed. for GET requests, this follows the <next> resource as indicated in the "Link" response header. for GraphQL queries, this utilizes pageInfo that must be present in the query; see EXAMPLES.

note that multiple JSON documents will be output as a result. if the API rate limit has been reached, the final document that is output will be the HTTP 403 notice, and the process will exit with a non-zero status. one way this can be avoided is by enabling --obey-ratelimit. 😭

• --color[=WHEN] — enable colored output even if stdout is not a terminal. WHEN can be one of "always" (default for --color), "never", or "auto" (default). give your terminal the aesthetic it deserves 💅🌸
• --cache TTL — cache valid responses to GET requests for TTL seconds. when using "graphql" as ENDPOINT, caching will apply to responses to POST requests as well. just make sure to not use --cache for any GraphQL mutations. not me warning you about mutations caching, that would be a disaster 💀
• --obey-ratelimit — after exceeding the API rate limit, pause the process until the reset time of the current rate limit window and retry the request. note that this may cause the process to hang for a long time (maximum of 1 hour). like, literally an hour. go touch grass while you wait 🌱
• ENDPOINT — the GitHub API endpoint to send the HTTP request to. default is "/".
  • to learn about available endpoints, see ⟨https://developer.github.com/v3/⟩. to make GraphQL queries, use "graphql" as ENDPOINT and pass -F query=QUERY.
  • if the literal strings "{owner}" or "{repo}" appear in ENDPOINT or in the GraphQL "query" field, fill in those placeholders with values read from the git remote configuration of the current git repository. so smart, lowkey genius 🧚

---

🔥 EXAMPLES 🔥

okay bestie, here are the actual examples, verbatim, no cap:

# fetch information about the currently authenticated user as JSON
$ hub api user

# list user repositories as line-based output
$ hub api --flat users/octocat/repos

# post a comment to issue #23 of the current repository
$ hub api repos/{owner}/{repo}/issues/23/comments --raw-field ´body=Nice job!´

# perform a GraphQL query read from a file
$ hub api graphql -F query=@path/to/myquery.graphql

# perform pagination with GraphQL
$ hub api --paginate graphql -f query=´
  query($endCursor: String) {
    repositoryOwner(login: "USER") {
      repositories(first: 100, after: $endCursor) {
        nodes {
          nameWithOwner
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }
´

those are literally the moves. use them wisely, queen 👑✨

---

💜 SEE ALSO 💜

• hub(1) — the main hub page, obviously. go read it if you haven't, bestie 🫶

---

and that's the whole page! this was hub version 2.14.2, dated 07 Jan 2024, so you know it's fresh-ish. now go forth and make those API calls with main character energy 💅✨🌸