hub-api(1)

1hub-api(1)                        hub manual                        hub-api(1)
2
3
4

NAME

6       hub-api - Low-level GitHub API request interface.
7

SYNOPSIS

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

OPTIONS

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
18           Use -XGET to force serializing fields into the query string for the
19           GET request instead of JSON body of the POST request.
20
21       -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
25           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
29           If VALUE is "true", "false", "null", or looks like a number, an
30           appropriate JSON type is used instead of a string.
31
32           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
36           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
41       -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
46       --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
51       -H, --header KEY:VALUE
52           Set an HTTP request header.
53
54       -i, --include
55           Include HTTP response headers in the output.
56
57       -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
61       --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           <next> resource as indicated in the "Link" response header. For
65           GraphQL queries, this utilizes pageInfo that must be present in the
66           query; see EXAMPLES.
67
68           Note that multiple JSON documents will be output as a result. If
69           the API rate limit has been reached, the final document that is
70           output will be the HTTP 403 notice, and the process will exit with
71           a non-zero status. One way this can be avoided is by enabling
72           --obey-ratelimit.
73
74       --color[=WHEN]
75           Enable colored output even if stdout is not a terminal. WHEN can be
76           one of "always" (default for --color), "never", or "auto"
77           (default).
78
79       --cache TTL
80           Cache valid responses to GET requests for TTL seconds.
81
82           When using "graphql" as ENDPOINT, caching will apply to responses
83           to POST requests as well. Just make sure to not use --cache for any
84           GraphQL mutations.
85
86       --obey-ratelimit
87           After exceeding the API rate limit, pause the process until the
88           reset time of the current rate limit window and retry the request.
89           Note that this may cause the process to hang for a long time
90           (maximum of 1 hour).
91
92       ENDPOINT
93           The GitHub API endpoint to send the HTTP request to (default: "/").
94
95           To learn about available endpoints, see
96           ⟨https://developer.github.com/v3/⟩.  To make GraphQL queries, use
97           "graphql" as ENDPOINT and pass -F query=QUERY.
98
99           If the literal strings "{owner}" or "{repo}" appear in ENDPOINT or
100           in the GraphQL "query" field, fill in those placeholders with
101           values read from the git remote configuration of the current git
102           repository.
103

EXAMPLES

105           # fetch information about the currently authenticated user as JSON
106           $ hub api user
107
108           # list user repositories as line-based output
109           $ hub api --flat users/octocat/repos
110
111           # post a comment to issue #23 of the current repository
112           $ hub api repos/{owner}/{repo}/issues/23/comments --raw-field ´body=Nice job!´
113
114           # perform a GraphQL query read from a file
115           $ hub api graphql -F query=@path/to/myquery.graphql
116
117           # perform pagination with GraphQL
118           $ hub api --paginate graphql -f query=´
119             query($endCursor: String) {
120               repositoryOwner(login: "USER") {
121                 repositories(first: 100, after: $endCursor) {
122                   nodes {
123                     nameWithOwner
124                   }
125                   pageInfo {
126                     hasNextPage
127                     endCursor
128                   }
129                 }
130               }
131             }
132           ´
133

NAME

SYNOPSIS

OPTIONS

EXAMPLES

SEE ALSO