0
# CLI Tools
1

2
Command-line interface tools providing direct GitHub API access from the command line, including endpoint calling, path-based access, and tab completion.
3

4
## Capabilities
5

6
### Command Functions
7

8
Core CLI functions for GitHub API access.
9

10
```python { .api }
11
def ghapi():
12
    """
13
    Python backend for the 'ghapi' command.
14
    Calls GitHub API endpoints by operation name.
15
    
16
    Usage from command line:
17
    ghapi operation.name [arguments] [--option=value]
18
    """
19

20
def ghpath():
21
    """
22
    Python backend for the 'ghpath' command.
23
    Calls GitHub API endpoints by path and HTTP verb.
24
    
25
    Usage from command line:
26
    ghpath /api/path HTTP_VERB [arguments] [--option=value]
27
    """
28

29
def ghraw():
30
    """
31
    Python backend for the 'ghraw' command.
32
    Calls fully-specified GitHub API endpoints.
33
    
34
    Usage from command line:
35
    ghraw /full/api/path [arguments] [--option=value]
36
    """
37

38
def completion_ghapi():
39
    """
40
    Python backend for 'completion-ghapi' command.
41
    Provides tab completion support for ghapi CLI.
42
    
43
    Usage from command line:
44
    completion-ghapi [--install]
45
    """
46
```
47

48
## Command Line Usage
49

50
### ghapi Command
51

52
Call GitHub API endpoints using operation names in dot notation.
53

54
```bash
55
# Basic repository information
56
ghapi repos.get --owner=octocat --repo=Hello-World
57

58
# List issues for a repository
59
ghapi issues.list_for_repo --owner=octocat --repo=Hello-World --state=open
60

61
# Create a new issue
62
ghapi issues.create --owner=octocat --repo=Hello-World --title="Bug report" --body="Description"
63

64
# Get authenticated user information
65
ghapi users.get_authenticated
66

67
# List repositories for authenticated user
68
ghapi repos.list_for_authenticated_user
69

70
# Get repository contents
71
ghapi repos.get_content --owner=octocat --repo=Hello-World --path=README.md
72

73
# List pull requests
74
ghapi pulls.list --owner=octocat --repo=Hello-World --state=all
75

76
# Create a pull request
77
ghapi pulls.create --owner=octocat --repo=Hello-World --title="New feature" --head=feature-branch --base=main
78

79
# List workflow runs
80
ghapi actions.list_workflow_runs --owner=octocat --repo=Hello-World
81

82
# Get organization information
83
ghapi orgs.get --org=github
84

85
# List organization repositories
86
ghapi repos.list_for_org --org=github --type=public
87
```
88

89
### ghpath Command
90

91
Call GitHub API endpoints using HTTP paths and verbs.
92

93
```bash
94
# GET requests (default verb)
95
ghpath /repos/octocat/Hello-World
96
ghpath /user
97
ghpath /orgs/github
98

99
# Explicit HTTP verbs
100
ghpath /repos/octocat/Hello-World/issues POST --title="New issue" --body="Issue description"
101
ghpath /repos/octocat/Hello-World/pulls/1 PATCH --state=closed
102
ghpath /repos/octocat/Hello-World/issues/1 DELETE
103

104
# With query parameters
105
ghpath "/repos/octocat/Hello-World/issues" --state=open --labels=bug
106
ghpath "/search/repositories" --q="language:python stars:>1000"
107

108
# Path parameters are automatically handled
109
ghpath /repos/octocat/Hello-World/contents/README.md
110
ghpath /repos/octocat/Hello-World/git/refs/heads/main
111
```
112

113
### ghraw Command
114

115
Make raw HTTP calls to GitHub API endpoints.
116

117
```bash
118
# Simple GET requests
119
ghraw https://api.github.com/repos/octocat/Hello-World
120
ghraw https://api.github.com/user
121

122
# POST requests with data
123
ghraw https://api.github.com/repos/octocat/Hello-World/issues POST --title="Raw issue" --body="Created via ghraw"
124

125
# Custom headers
126
ghraw https://api.github.com/repos/octocat/Hello-World --headers='{"Accept": "application/vnd.github.v3.raw"}'
127

128
# Full URL specification
129
ghraw "https://api.github.com/search/repositories?q=language:python&sort=stars"
130
```
131

132
### Authentication
133

134
All CLI tools use GitHub token authentication via environment variables or command-line options.
135

136
```bash
137
# Set token via environment variable
138
export GITHUB_TOKEN=ghp_your_personal_access_token
139

140
# Or pass token as argument
141
ghapi repos.get --token=ghp_your_token --owner=octocat --repo=Hello-World
142

143
# Use JWT token
144
export GITHUB_JWT_TOKEN=your_jwt_token
145
ghapi users.get_authenticated
146

147
# Debug mode
148
ghapi repos.get --debug --owner=octocat --repo=Hello-World
149
```
150

151
### Tab Completion
152

153
Install and use tab completion for the ghapi command.
154

155
```bash
156
# Install tab completion
157
completion-ghapi --install >> ~/.bashrc
158
source ~/.bashrc
159

160
# Now you can use tab completion
161
ghapi repos.<TAB>          # Shows available repository operations
162
ghapi issues.<TAB>         # Shows available issue operations  
163
ghapi users.get_<TAB>      # Shows user-related get operations
164

165
# Completion works for nested operations
166
ghapi actions.list_<TAB>   # Shows Actions list operations
167
ghapi pulls.create_<TAB>   # Shows pull request creation operations
168
```
169

170
## Usage Examples
171

172
### Repository Management
173

174
```bash
175
# Get repository information
176
ghapi repos.get --owner=fastai --repo=ghapi
177

178
# List repository branches
179
ghapi repos.list_branches --owner=fastai --repo=ghapi
180

181
# Get repository topics
182
ghapi repos.get_all_topics --owner=fastai --repo=ghapi
183

184
# Create repository (requires auth)
185
ghapi repos.create_for_authenticated_user --name=new-repo --description="My new repository"
186

187
# Update repository
188
ghapi repos.update --owner=username --repo=repo-name --description="Updated description"
189

190
# Delete repository (careful!)
191
ghapi repos.delete --owner=username --repo=old-repo
192
```
193

194
### Issue Management
195

196
```bash
197
# List all issues
198
ghapi issues.list_for_repo --owner=fastai --repo=ghapi --state=all --per_page=50
199

200
# Get specific issue
201
ghapi issues.get --owner=fastai --repo=ghapi --issue_number=123
202

203
# Create issue with labels
204
ghapi issues.create --owner=username --repo=repo --title="Bug report" --body="Description" --labels='["bug", "high-priority"]'
205

206
# Update issue
207
ghapi issues.update --owner=username --repo=repo --issue_number=123 --state=closed
208

209
# Add comment to issue
210
ghapi issues.create_comment --owner=username --repo=repo --issue_number=123 --body="This is fixed now"
211

212
# List issue comments
213
ghapi issues.list_comments --owner=fastai --repo=ghapi --issue_number=123
214
```
215

216
### Pull Request Operations
217

218
```bash
219
# List pull requests
220
ghapi pulls.list --owner=fastai --repo=ghapi --state=open
221

222
# Get specific pull request
223
ghapi pulls.get --owner=fastai --repo=ghapi --pull_number=456
224

225
# Create pull request
226
ghapi pulls.create --owner=username --repo=repo --title="New feature" --body="Feature description" --head=feature-branch --base=main
227

228
# Update pull request
229
ghapi pulls.update --owner=username --repo=repo --pull_number=456 --title="Updated title"
230

231
# Merge pull request
232
ghapi pulls.merge --owner=username --repo=repo --pull_number=456 --commit_title="Merge feature"
233

234
# Request reviewers
235
ghapi pulls.request_reviewers --owner=username --repo=repo --pull_number=456 --reviewers='["reviewer1", "reviewer2"]'
236
```
237

238
### User and Organization Operations
239

240
```bash
241
# Get authenticated user
242
ghapi users.get_authenticated
243

244
# Get user by username
245
ghapi users.get_by_username --username=octocat
246

247
# List user repositories
248
ghapi repos.list_for_user --username=octocat --type=public --sort=updated
249

250
# Get organization
251
ghapi orgs.get --org=github
252

253
# List organization members
254
ghapi orgs.list_members --org=github --per_page=50
255

256
# List organization repositories
257
ghapi repos.list_for_org --org=github --type=public --sort=stars
258
```
259

260
### Search Operations
261

262
```bash
263
# Search repositories
264
ghapi search.repos --q="language:python stars:>1000"
265

266
# Search users
267
ghapi search.users --q="location:london language:python"
268

269
# Search issues
270
ghapi search.issues --q="repo:fastai/ghapi is:open label:bug"
271

272
# Search code
273
ghapi search.code --q="def main in:file language:python"
274

275
# Search commits
276
ghapi search.commits --q="author:octocat repo:octocat/Hello-World"
277
```
278

279
### GitHub Actions
280

281
```bash
282
# List workflows
283
ghapi actions.list_repo_workflows --owner=fastai --repo=ghapi
284

285
# List workflow runs
286
ghapi actions.list_workflow_runs --owner=fastai --repo=ghapi --per_page=20
287

288
# Get workflow run
289
ghapi actions.get_workflow_run --owner=fastai --repo=ghapi --run_id=123456
290

291
# List jobs for workflow run
292
ghapi actions.list_jobs_for_workflow_run --owner=fastai --repo=ghapi --run_id=123456
293

294
# Download workflow run logs
295
ghapi actions.download_workflow_run_logs --owner=fastai --repo=ghapi --run_id=123456
296

297
# Trigger workflow dispatch
298
ghapi actions.create_workflow_dispatch --owner=username --repo=repo --workflow_id=workflow.yml --ref=main
299
```
300

301
### Release Management
302

303
```bash
304
# List releases
305
ghapi repos.list_releases --owner=fastai --repo=ghapi
306

307
# Get latest release
308
ghapi repos.get_latest_release --owner=fastai --repo=ghapi
309

310
# Create release
311
ghapi repos.create_release --owner=username --repo=repo --tag_name=v1.0.0 --name="Version 1.0.0" --body="Release notes"
312

313
# Update release
314
ghapi repos.update_release --owner=username --repo=repo --release_id=123 --name="Updated release name"
315

316
# Delete release
317
ghapi repos.delete_release --owner=username --repo=repo --release_id=123
318

319
# Upload release asset
320
ghapi repos.upload_release_asset --owner=username --repo=repo --release_id=123 --name=asset.zip
321
```
322

323
### Advanced Usage
324

325
```bash
326
# Output JSON for processing
327
ghapi repos.get --owner=fastai --repo=ghapi | jq '.stargazers_count'
328

329
# Pipe data between commands
330
ghapi repos.list_for_user --username=octocat | jq '.[].name' | head -10
331

332
# Use with environment variables
333
export REPO_OWNER=fastai
334
export REPO_NAME=ghapi
335
ghapi repos.get --owner=$REPO_OWNER --repo=$REPO_NAME
336

337
# Batch operations with shell scripting
338
for repo in $(ghapi repos.list_for_user --username=octocat | jq -r '.[].name'); do
339
    echo "Processing $repo..."
340
    ghapi repos.get --owner=octocat --repo=$repo
341
done
342

343
# Error handling
344
if ghapi repos.get --owner=nonexistent --repo=repo 2>/dev/null; then
345
    echo "Repository exists"
346
else
347
    echo "Repository not found"
348
fi
349
```