1hub-api(1) hub manual hub-api(1)
2
6 hub-api - Low-level GitHub API request interface.
7
9 hub api [-it] [-X METHOD] [-H HEADER] [--cache TTL] ENDPOINT [-F
10 FIELD|--input FILE]
11
13 -X, --method METHOD
14 The HTTP method to use for the request (default: "GET"). The method
15 is automatically set to "POST" if --field, --raw-field, or --input
16 are used.
17 Use -XGET to force serializing fields into the query string for the
19 GET request instead of JSON body of the POST request.
20 -F, --field KEY=VALUE
22 Data to serialize with the request. VALUE has some magic handling;
23 use --raw-field for sending arbitrary string values.
24 If VALUE starts with "@", the rest of the value is interpreted as a
26 filename to read the value from. Use "@-" to read from standard
27 input.
28 If VALUE is "true", "false", "null", or looks like a number, an
30 appropriate JSON type is used instead of a string.
31 It is not possible to serialize VALUE as a nested JSON array or
33 hash. Instead, construct the request payload externally and pass
34 it via --input.
35 Unless -XGET was used, all fields are sent serialized as JSON
37 within the request body. When ENDPOINT is "graphql", all fields
38 other than "query" are grouped under "variables". See
39 ⟨https://graphql.org/learn/queries/#variables⟩
40 -f, --raw-field KEY=VALUE
42 Same as --field, except that it allows values starting with "@",
43 literal strings "true", "false", and "null", as well as strings
44 that look like numbers.
45 --input FILE
47 The filename to read the raw request body from. Use "-" to read
48 from standard input. Use this when you want to manually construct
49 the request payload.
50 -H, --header KEY:VALUE
52 Set an HTTP request header.
53 -i, --include
55 Include HTTP response headers in the output.
56 -t, --flat
58 Parse response JSON and output the data in a line-based key-value
59 format suitable for use in shell scripts.
60 --paginate
62 Automatically request and output the next page of results until all
63 resources have been listed. For GET requests, this follows the
64 <var>next</var> resource as indicated in the "Link" response
65 header. For GraphQL queries, this utilizes pageInfo that must be
66 present in the query; see EXAMPLES.
67 Note that multiple JSON documents will be output as a result.
69 --color[=WHEN]
71 Enable colored output even if stdout is not a terminal. WHEN can be
72 one of "always" (default for --color), "never", or "auto"
73 (default).
74 --cache TTL
76 Cache valid responses to GET requests for TTL seconds.
77 When using "graphql" as ENDPOINT, caching will apply to responses
79 to POST requests as well. Just make sure to not use --cache for any
80 GraphQL mutations.
81 ENDPOINT
83 The GitHub API endpoint to send the HTTP request to (default: "/").
84 To learn about available endpoints, see
86 ⟨https://developer.github.com/v3/⟩. To make GraphQL queries, use
87 "graphql" as ENDPOINT and pass -F query=QUERY.
88 If the literal strings "{owner}" or "{repo}" appear in ENDPOINT or
90 in the GraphQL "query" field, fill in those placeholders with
91 values read from the git remote configuration of the current git
92 repository.
93
95 # fetch information about the currently authenticated user as JSON
96 $ hub api user
97 # list user repositories as line-based output
99 $ hub api --flat users/octocat/repos
100 # post a comment to issue #23 of the current repository
102 $ hub api repos/{owner}/{repo}/issues/23/comments --raw-field "body=Nice job!"
103 # perform a GraphQL query read from a file
105 $ hub api graphql -F query=@path/to/myquery.graphql
106 # perform pagination with GraphQL
108 $ hub api --paginate graphql -f query='
109 query($endCursor: String) {
110 repositoryOwner(login: "USER") {
111 repositories(first: 100, after: $endCursor) {
112 nodes {
113 nameWithOwner
114 }
115 pageInfo {
116 hasNextPage
117 endCursor
118 }
119 }
120 }
121 }'
122
124 hub(1)
125hub version 2.12.8 03 Oct 2019 hub-api(1)