flagon-io/g1t

public

Where people and agents ship software together. The open-source git platform for the whole job: issues, agents, checks and deploys to the edge.

git agents cloudflare rust forge mcp

1,567 linesCode BlameRaw

1	---
2	title: CLI commands
3	description: Every g1t command with its arguments and flags, written from the CLI's own definitions.
4	---
5
6	<!-- Generated from crates/g1t by `G1T_WRITE_DOCS=1 cargo test -p g1t cli_reference`. Do not edit by hand. -->
7
8	Every command of the [g1t CLI](/guides/cli/), with its arguments and flags.
9	`g1t <command> --help` prints the same at a terminal. Each command that talks
10	to the API names the operations it calls, which link to the
11	[API reference](/reference/api/); [`g1t api`](#g1t-api) calls any other.
12
13	## Flags every command takes
14
15	\| Flag \| \|
16	\| --- \| --- \|
17	\| `-R, --repo <[HOST/]OWNER/NAME>` \| The repository, as [HOST/]OWNER/NAME, instead of the current directory's. \|
18	\| `--hostname <HOST>` \| The g1t host, such as g1t.sh or git.example.com. \|
19	\| `--json [FIELDS]` \| Print JSON: every field, or only the comma-separated FIELDS. \|
20	\| `--jq <EXPRESSION>` \| Run a jq expression over the JSON and print what it gives. \|
21
22	## g1t auth
23
24	Sign in, sign out, and set git up to use g1t's credentials.
25
26	### g1t auth login
27
28	Sign in to a g1t host.
29
30	```text
31	g1t auth login [OPTIONS]
32	```
33
34	\| Argument or flag \| \|
35	\| --- \| --- \|
36	\| `--with-token` \| Read a token from stdin instead of approving in the browser. \|
37	\| `--insecure-storage` \| Keep the token in the config file, not the system keychain. \|
38	\| `--no-browser` \| Do not open the browser; just print the link. \|
39	\| `--git` \| Also set git up to use g1t's credentials (see `g1t auth setup-git`). \|
40
41	```text
42	Without --with-token, g1t shows a code and a link; approve it in the browser, signed in.
43	With --with-token, the token is read from stdin:
44	g1t auth login --with-token < token.txt
45	```
46
47	Calls [`device_code`](/reference/api/accounts/device-code/), [`device_token`](/reference/api/accounts/device-token/), [`whoami`](/reference/api/accounts/whoami/).
48
49	### g1t auth logout
50
51	Sign out of an account on a host.
52
53	```text
54	g1t auth logout [OPTIONS]
55	```
56
57	\| Argument or flag \| \|
58	\| --- \| --- \|
59	\| `-u, --user <USER>` \| The account, when more than one is signed in on the host. \|
60
61	### g1t auth status
62
63	Show which accounts are signed in, and whether their tokens work.
64
65	```text
66	g1t auth status [OPTIONS]
67	```
68
69	\| Argument or flag \| \|
70	\| --- \| --- \|
71	\| `--show-token` \| Print each token too. \|
72
73	Calls [`whoami`](/reference/api/accounts/whoami/).
74
75	### g1t auth token
76
77	Print the token in use, for another program.
78
79	```text
80	g1t auth token [OPTIONS]
81	```
82
83	\| Argument or flag \| \|
84	\| --- \| --- \|
85	\| `-u, --user <USER>` \| The account, when more than one is signed in on the host. \|
86
87	### g1t auth switch
88
89	Make another signed-in account on a host the active one.
90
91	```text
92	g1t auth switch [OPTIONS]
93	```
94
95	\| Argument or flag \| \|
96	\| --- \| --- \|
97	\| `-u, --user <USER>` \| The account, when more than one is signed in on the host. \|
98
99	### g1t auth setup-git
100
101	Make git use g1t's credentials for pushing and fetching over HTTPS.
102
103	```text
104	g1t auth setup-git [OPTIONS]
105	```
106
107	\| Argument or flag \| \|
108	\| --- \| --- \|
109	\| `--dry-run` \| Print the git config commands instead of running them. \|
110
111	## g1t repo
112
113	Repositories: view, clone, create, list, fork, sync.
114
115	### g1t repo view
116
117	Show a repository.
118
119	```text
120	g1t repo view [OPTIONS] [REPOSITORY]
121	```
122
123	\| Argument or flag \| \|
124	\| --- \| --- \|
125	\| `[REPOSITORY]` \| OWNER/NAME; the current repository when left out. \|
126	\| `-w, --web` \| Open it in the browser. \|
127
128	Calls [`get_repo`](/reference/api/repositories/get-repo/), [`list_projects`](/reference/api/projects/list-projects/).
129
130	### g1t repo clone
131
132	Clone a repository.
133
134	```text
135	g1t repo clone [OPTIONS] <REPOSITORY> [DIRECTORY] [-- <GIT_FLAGS>...]
136	```
137
138	\| Argument or flag \| \|
139	\| --- \| --- \|
140	\| `<REPOSITORY>` \| OWNER/NAME, or NAME for one of your own. \|
141	\| `[DIRECTORY]` \| Where to clone it. \|
142	\| `[GIT_FLAGS]` \| After `--`. Flags for git clone, after --. \|
143
144	Calls [`whoami`](/reference/api/accounts/whoami/).
145
146	### g1t repo create
147
148	Make a repository.
149
150	```text
151	g1t repo create [OPTIONS] [NAME]
152	```
153
154	\| Argument or flag \| \|
155	\| --- \| --- \|
156	\| `[NAME]` \| NAME, or WORKSPACE/NAME. \|
157	\| `--public` \| Anyone can see it. Repositories are private unless this is given. \|
158	\| `--private` \| Only people with a role on it can see it (the default). \|
159	\| `-d, --description <DESCRIPTION>` \| What it is, in a line: its project's description. \|
160	\| `-c, --clone` \| Clone it once it is made. \|
161	\| `--source <DIR>` \| Add it as a remote of this directory's repository and push it there. \|
162	\| `--remote <REMOTE>` \| The remote's name, with --source. Default: `origin`. \|
163	\| `--deploy` \| Turn on its g1t.page deployments once it is made, so its first push deploys production. \|
164
165	Calls [`create_repo`](/reference/api/repositories/create-repo/).
166
167	### g1t repo list
168
169	List repositories you can see.
170
171	```text
172	g1t repo list [OPTIONS] [WORKSPACE]
173	```
174
175	\| Argument or flag \| \|
176	\| --- \| --- \|
177	\| `[WORKSPACE]` \| Only this workspace's. \|
178	\| `-q, --query <QUERY>` \| Only those whose name holds this. \|
179	\| `-L, --limit <LIMIT>` \| Default: `20`. \|
180
181	Calls [`list_repos`](/reference/api/repositories/list-repos/), [`list_projects`](/reference/api/projects/list-projects/).
182
183	### g1t repo fork
184
185	Fork a repository into one of your workspaces.
186
187	```text
188	g1t repo fork [OPTIONS] [REPOSITORY]
189	```
190
191	\| Argument or flag \| \|
192	\| --- \| --- \|
193	\| `[REPOSITORY]` \| OWNER/NAME; the current repository when left out. \|
194	\| `-w, --workspace <WORKSPACE>` \| The workspace to fork it into; your personal workspace when left out. \|
195	\| `--name <NAME>` \| The fork's name; the repository's own when left out. \|
196	\| `--all-branches` \| Copy every branch and tag, not only the default branch. \|
197	\| `-c, --clone` \| Clone the fork, with the repository it came from as the remote upstream. \|
198
199	Calls [`fork_repo`](/reference/api/repositories/fork-repo/).
200
201	### g1t repo forks
202
203	List a repository's forks.
204
205	```text
206	g1t repo forks [OPTIONS] [REPOSITORY]
207	```
208
209	\| Argument or flag \| \|
210	\| --- \| --- \|
211	\| `[REPOSITORY]` \| OWNER/NAME; the current repository when left out. \|
212	\| `-L, --limit <LIMIT>` \| Default: `30`. \|
213
214	Calls [`list_forks`](/reference/api/repositories/list-forks/), [`list_projects`](/reference/api/projects/list-projects/).
215
216	### g1t repo sync
217
218	Bring a fork's branch up to date with the repository it was forked from.
219
220	```text
221	g1t repo sync [OPTIONS] [REPOSITORY]
222	```
223
224	\| Argument or flag \| \|
225	\| --- \| --- \|
226	\| `[REPOSITORY]` \| The fork, OWNER/NAME; the one this directory pushes to (origin) when left out. \|
227	\| `-b, --branch <BRANCH>` \| The fork's branch to sync; its default branch when left out. \|
228
229	Calls [`sync_fork`](/reference/api/repositories/sync-fork/).
230
231	### g1t repo detach
232
233	Make a fork an ordinary repository, no longer linked to its parent.
234
235	```text
236	g1t repo detach [OPTIONS] [REPOSITORY]
237	```
238
239	\| Argument or flag \| \|
240	\| --- \| --- \|
241	\| `[REPOSITORY]` \| The fork, OWNER/NAME; the one this directory pushes to (origin) when left out. \|
242	\| `-y, --yes` \| Do not ask first. \|
243
244	Calls [`detach_fork`](/reference/api/repositories/detach-fork/).
245
246	## g1t issue
247
248	Issues: list, view, create, comment, close, reopen, edit.
249
250	### g1t issue list
251
252	List issues.
253
254	```text
255	g1t issue list [OPTIONS]
256	```
257
258	\| Argument or flag \| \|
259	\| --- \| --- \|
260	\| `-s, --state <STATE>` \| One of `open`, `closed`, `all`. Default: `open`. \|
261	\| `-l, --label <LABEL>` \| Only issues with this label. \|
262	\| `-m, --milestone <MILESTONE>` \| Only issues in the milestone of this number. \|
263	\| `-a, --assignee <ASSIGNEE>` \| Only issues assigned to this person (@me for you). \|
264	\| `-A, --author <AUTHOR>` \| Only issues opened by this person (@me for you). \|
265	\| `-L, --limit <LIMIT>` \| Default: `20`. \|
266
267	Calls [`list_issues`](/reference/api/issues/list-issues/).
268
269	### g1t issue view
270
271	Show an issue, with its comments.
272
273	```text
274	g1t issue view [OPTIONS] <NUMBER>
275	```
276
277	\| Argument or flag \| \|
278	\| --- \| --- \|
279	\| `<NUMBER>` \| The issue's number. \|
280	\| `-c, --comments` \| Show its comments too. \|
281	\| `-w, --web` \| Open it in the browser. \|
282
283	Calls [`get_issue`](/reference/api/issues/get-issue/).
284
285	### g1t issue create
286
287	Open an issue.
288
289	```text
290	g1t issue create [OPTIONS]
291	```
292
293	\| Argument or flag \| \|
294	\| --- \| --- \|
295	\| `-t, --title <TITLE>` \| \|
296	\| `-b, --body <BODY>` \| The text. Markdown. \|
297	\| `-F, --body-file <FILE>` \| Read the text from a file, or - for stdin. \|
298	\| `--attach <FILE>` \| An image to show after the text (PNG, JPEG, GIF or WebP, at most 10 MB): uploaded, and its Markdown added. Repeat for more. \|
299	\| `-l, --label <LABEL>` \| A label; repeat for more. \|
300	\| `-a, --assignee <ASSIGNEE>` \| Someone to assign; repeat for more (@me for you). \|
301	\| `-m, --milestone <MILESTONE>` \| A milestone's number. \|
302	\| `-w, --web` \| Open the new-issue page in the browser instead. \|
303
304	Calls [`create_issue`](/reference/api/issues/create-issue/), [`update_issue`](/reference/api/issues/update-issue/), [`upload_attachment`](/reference/api/issues/upload-attachment/).
305
306	### g1t issue comment
307
308	Comment on an issue.
309
310	```text
311	g1t issue comment [OPTIONS] [NUMBER]
312	```
313
314	\| Argument or flag \| \|
315	\| --- \| --- \|
316	\| `[NUMBER]` \| The number; for a pull request, the current branch's when left out. \|
317	\| `-b, --body <BODY>` \| The text. Markdown. \|
318	\| `-F, --body-file <FILE>` \| Read the text from a file, or - for stdin. \|
319	\| `--attach <FILE>` \| An image to show after the text (PNG, JPEG, GIF or WebP, at most 10 MB): uploaded, and its Markdown added. Repeat for more. \|
320
321	Calls [`add_comment`](/reference/api/issues/add-comment/), [`upload_attachment`](/reference/api/issues/upload-attachment/).
322
323	### g1t issue close
324
325	Close an issue.
326
327	```text
328	g1t issue close [OPTIONS] <NUMBER>
329	```
330
331	\| Argument or flag \| \|
332	\| --- \| --- \|
333	\| `<NUMBER>` \| \|
334	\| `-r, --reason <REASON>` \| One of `completed`, `not_planned`. \|
335	\| `-c, --comment <COMMENT>` \| Leave a comment as it closes. \|
336	\| `--commit <COMMIT>` \| The commit on the default branch that closed it: its message names the issue after a closing keyword (Fixes #12). Its full hash. \|
337
338	Calls [`close_issue`](/reference/api/issues/close-issue/), [`add_comment`](/reference/api/issues/add-comment/).
339
340	### g1t issue reopen
341
342	Reopen an issue.
343
344	```text
345	g1t issue reopen [OPTIONS] <NUMBER>
346	```
347
348	\| Argument or flag \| \|
349	\| --- \| --- \|
350	\| `<NUMBER>` \| \|
351	\| `-c, --comment <COMMENT>` \| Leave a comment as it reopens. \|
352
353	Calls [`reopen_issue`](/reference/api/issues/reopen-issue/), [`add_comment`](/reference/api/issues/add-comment/).
354
355	### g1t issue edit
356
357	Change an issue's title, body, labels, assignees or milestone.
358
359	```text
360	g1t issue edit [OPTIONS] <NUMBER>
361	```
362
363	\| Argument or flag \| \|
364	\| --- \| --- \|
365	\| `<NUMBER>` \| \|
366	\| `-t, --title <TITLE>` \| \|
367	\| `-b, --body <BODY>` \| The text. Markdown. \|
368	\| `-F, --body-file <FILE>` \| Read the text from a file, or - for stdin. \|
369	\| `--add-label <LABEL>` \| \|
370	\| `--remove-label <LABEL>` \| \|
371	\| `--add-assignee <LOGIN>` \| \|
372	\| `--remove-assignee <LOGIN>` \| \|
373	\| `-m, --milestone <MILESTONE>` \| A milestone's number. \|
374	\| `--remove-milestone` \| Take it out of its milestone. \|
375
376	Calls [`update_issue`](/reference/api/issues/update-issue/), [`get_issue`](/reference/api/issues/get-issue/).
377
378	## g1t pr
379
380	Pull requests: list, view, create, check out, diff, checks, review, merge.
381
382	### g1t pr list
383
384	List pull requests.
385
386	```text
387	g1t pr list [OPTIONS]
388	```
389
390	\| Argument or flag \| \|
391	\| --- \| --- \|
392	\| `-s, --state <STATE>` \| One of `open`, `closed`, `merged`, `all`. Default: `open`. \|
393	\| `-B, --base <BASE>` \| Only those merging into this branch. \|
394	\| `-l, --label <LABEL>` \| \|
395	\| `-A, --author <AUTHOR>` \| Only those opened by this person (@me for you). \|
396	\| `-d, --draft` \| Only drafts. \|
397	\| `-L, --limit <LIMIT>` \| Default: `20`. \|
398
399	Calls [`list_pull_requests`](/reference/api/pull-requests/list-pull-requests/).
400
401	### g1t pr view
402
403	Show a pull request.
404
405	```text
406	g1t pr view [OPTIONS] [NUMBER]
407	```
408
409	\| Argument or flag \| \|
410	\| --- \| --- \|
411	\| `[NUMBER]` \| The number; the current branch's when left out. \|
412	\| `-c, --comments` \| \|
413	\| `-w, --web` \| \|
414
415	Calls [`get_pull_request`](/reference/api/pull-requests/get-pull-request/), [`list_pull_requests`](/reference/api/pull-requests/list-pull-requests/).
416
417	### g1t pr create
418
419	Open a pull request from a branch, or start one for an issue.
420
421	```text
422	g1t pr create [OPTIONS]
423	```
424
425	\| Argument or flag \| \|
426	\| --- \| --- \|
427	\| `-t, --title <TITLE>` \| \|
428	\| `-b, --body <BODY>` \| The text. Markdown. \|
429	\| `-F, --body-file <FILE>` \| Read the text from a file, or - for stdin. \|
430	\| `--attach <FILE>` \| An image to show after the text (PNG, JPEG, GIF or WebP, at most 10 MB): uploaded, and its Markdown added. Repeat for more. \|
431	\| `-B, --base <BASE>` \| The branch to merge into; the default branch when left out. \|
432	\| `-H, --head <HEAD>` \| The branch with the changes; the current one when left out. \|
433	\| `-i, --issue <ISSUE>` \| The issue it is for. Without a branch, starts a draft in a working copy of its own. \|
434	\| `-f, --fill` \| Take the title and body from the branch's commits. \|
435	\| `-d, --draft` \| Open it as a draft. \|
436	\| `--no-push` \| Do not push the branch first. \|
437	\| `--head-repo <OWNER/NAME>` \| The fork, OWNER/NAME, that holds the branch. In a clone of your fork (origin) whose upstream is the repository, origin when left out. \|
438
439	Calls [`create_pull_request`](/reference/api/pull-requests/create-pull-request/), [`get_repo`](/reference/api/repositories/get-repo/), [`convert_pull_request_to_draft`](/reference/api/pull-requests/convert-pull-request-to-draft/), [`upload_attachment`](/reference/api/issues/upload-attachment/).
440
441	### g1t pr checkout
442
443	Check a pull request's changes out locally.
444
445	```text
446	g1t pr checkout [OPTIONS] <NUMBER>
447	```
448
449	\| Argument or flag \| \|
450	\| --- \| --- \|
451	\| `<NUMBER>` \| \|
452	\| `-b, --branch <BRANCH>` \| The local branch's name; pr-NUMBER when left out. \|
453	\| `-f, --force` \| Reset the local branch to the pull request's head even if it has other commits. \|
454
455	Calls [`get_pull_request`](/reference/api/pull-requests/get-pull-request/).
456
457	### g1t pr diff
458
459	Show a pull request's changes as a diff.
460
461	```text
462	g1t pr diff [OPTIONS] [NUMBER]
463	```
464
465	\| Argument or flag \| \|
466	\| --- \| --- \|
467	\| `[NUMBER]` \| \|
468	\| `--name-only` \| Only the changed files' names. \|
469	\| `--color <COLOR>` \| Color: auto, always or never. Default: `auto`. \|
470
471	Calls [`get_pull_request_changes`](/reference/api/pull-requests/get-pull-request-changes/).
472
473	### g1t pr checks
474
475	Show a pull request's checks; --watch waits for them.
476
477	```text
478	g1t pr checks [OPTIONS] [NUMBER]
479	```
480
481	\| Argument or flag \| \|
482	\| --- \| --- \|
483	\| `[NUMBER]` \| \|
484	\| `-w, --watch` \| Wait until every check has finished. \|
485	\| `--fail-fast` \| With --watch, stop at the first failing check. \|
486	\| `-i, --interval <INTERVAL>` \| Seconds between looks, with --watch. Default: `10`. \|
487
488	Calls [`get_pull_request`](/reference/api/pull-requests/get-pull-request/), [`list_check_runs_for_ref`](/reference/api/checks/list-check-runs-for-ref/), [`get_combined_status`](/reference/api/checks/get-combined-status/).
489
490	### g1t pr review
491
492	Approve a pull request, or ask for changes.
493
494	```text
495	g1t pr review [OPTIONS] <--approve\|--request-changes\|--comment> [NUMBER]
496	```
497
498	\| Argument or flag \| \|
499	\| --- \| --- \|
500	\| `[NUMBER]` \| \|
501	\| `-a, --approve` \| \|
502	\| `-r, --request-changes` \| \|
503	\| `-c, --comment` \| Comment without approving or asking for changes. \|
504	\| `-b, --body <BODY>` \| The text. Markdown. \|
505	\| `-F, --body-file <FILE>` \| Read the text from a file, or - for stdin. \|
506
507	Calls [`review_pull_request`](/reference/api/pull-requests/review-pull-request/), [`add_comment`](/reference/api/issues/add-comment/).
508
509	### g1t pr merge
510
511	Merge a pull request, now or with auto-merge.
512
513	```text
514	g1t pr merge [OPTIONS] [NUMBER]
515	```
516
517	\| Argument or flag \| \|
518	\| --- \| --- \|
519	\| `[NUMBER]` \| \|
520	\| `-m, --merge` \| Merge with a merge commit. The repository's default method when no method is given. \|
521	\| `-s, --squash` \| Squash its commits into one. \|
522	\| `-r, --rebase` \| Make each of its commits again on top of the base. \|
523	\| `--ff` \| Fast-forward: move the base to its head, with no new commit. \|
524	\| `-t, --subject <SUBJECT>` \| The merge or squash commit's title; the repository's default when left out. \|
525	\| `-b, --body <BODY>` \| The text. Markdown. \|
526	\| `-F, --body-file <FILE>` \| Read the text from a file, or - for stdin. \|
527	\| `--auto` \| Merge on its own once its checks, reviews and rules allow. \|
528	\| `--disable-auto` \| Turn its auto-merge off. \|
529	\| `--keep-issue-open` \| Leave the issue it is for open. \|
530	\| `--admin` \| Merge past failing required checks and rules (needs the Admin role). \|
531	\| `-d, --delete-branch` \| Delete its branch once merged, and the local branch. The repository's setting when left out. \|
532	\| `--keep-branch` \| Keep its branch, whatever the repository's setting. \|
533	\| `--match-head-commit <SHA>` \| Refuse to merge unless its head is still this commit. \|
534
535	Calls [`merge_pull_request`](/reference/api/pull-requests/merge-pull-request/), [`enable_pull_request_auto_merge`](/reference/api/pull-requests/enable-pull-request-auto-merge/), [`disable_pull_request_auto_merge`](/reference/api/pull-requests/disable-pull-request-auto-merge/).
536
537	### g1t pr update-branch
538
539	Bring a pull request's branch up to date with its base.
540
541	```text
542	g1t pr update-branch [OPTIONS] [NUMBER]
543	```
544
545	\| Argument or flag \| \|
546	\| --- \| --- \|
547	\| `[NUMBER]` \| The number; the current branch's when left out. \|
548	\| `--rebase` \| Rebase its commits onto the base instead of merging the base in. Rewrites its branch. \|
549
550	Calls [`update_pull_request_branch`](/reference/api/pull-requests/update-pull-request-branch/).
551
552	### g1t pr ready
553
554	Mark a draft ready for review, or turn it back into a draft.
555
556	```text
557	g1t pr ready [OPTIONS] [NUMBER]
558	```
559
560	\| Argument or flag \| \|
561	\| --- \| --- \|
562	\| `[NUMBER]` \| \|
563	\| `-s, --summary <SUMMARY>` \| What changed and why; it becomes the description. The current one when left out. \|
564	\| `--attach <FILE>` \| An image to show after the summary (PNG, JPEG, GIF or WebP, at most 10 MB): uploaded, and its Markdown added. Repeat for more. \|
565	\| `--undo` \| Turn it back into a draft. \|
566
567	Calls [`mark_pull_request_ready`](/reference/api/pull-requests/mark-pull-request-ready/), [`convert_pull_request_to_draft`](/reference/api/pull-requests/convert-pull-request-to-draft/), [`upload_attachment`](/reference/api/issues/upload-attachment/).
568
569	### g1t pr comment
570
571	Comment on a pull request.
572
573	```text
574	g1t pr comment [OPTIONS] [NUMBER]
575	```
576
577	\| Argument or flag \| \|
578	\| --- \| --- \|
579	\| `[NUMBER]` \| The number; for a pull request, the current branch's when left out. \|
580	\| `-b, --body <BODY>` \| The text. Markdown. \|
581	\| `-F, --body-file <FILE>` \| Read the text from a file, or - for stdin. \|
582	\| `--attach <FILE>` \| An image to show after the text (PNG, JPEG, GIF or WebP, at most 10 MB): uploaded, and its Markdown added. Repeat for more. \|
583
584	Calls [`add_comment`](/reference/api/issues/add-comment/), [`upload_attachment`](/reference/api/issues/upload-attachment/).
585
586	### g1t pr close
587
588	Close a pull request without merging it.
589
590	```text
591	g1t pr close [OPTIONS] [NUMBER]
592	```
593
594	\| Argument or flag \| \|
595	\| --- \| --- \|
596	\| `[NUMBER]` \| The number; the current branch's when left out. \|
597
598	Calls [`close_pull_request`](/reference/api/pull-requests/close-pull-request/).
599
600	### g1t pr reopen
601
602	Reopen a closed pull request.
603
604	```text
605	g1t pr reopen [OPTIONS] [NUMBER]
606	```
607
608	\| Argument or flag \| \|
609	\| --- \| --- \|
610	\| `[NUMBER]` \| The number; the current branch's when left out. \|
611
612	Calls [`reopen_pull_request`](/reference/api/pull-requests/reopen-pull-request/).
613
614	## g1t run
615
616	Workflow runs: list, view, watch, logs, rerun, cancel.
617
618	### g1t run list
619
620	List workflow runs, newest first.
621
622	```text
623	g1t run list [OPTIONS]
624	```
625
626	\| Argument or flag \| \|
627	\| --- \| --- \|
628	\| `-w, --workflow <WORKFLOW>` \| Only this workflow's: its file name or id. \|
629	\| `-b, --branch <BRANCH>` \| \|
630	\| `-e, --event <EVENT>` \| Only runs for this event: push, pull_request, schedule... \|
631	\| `-c, --commit <COMMIT>` \| Only runs of this commit. \|
632	\| `--pr <PR>` \| Only runs for this pull request. \|
633	\| `-L, --limit <LIMIT>` \| Default: `20`. \|
634
635	Calls [`list_workflow_runs`](/reference/api/actions/list-workflow-runs/).
636
637	### g1t run view
638
639	Show a run's jobs and steps.
640
641	```text
642	g1t run view [OPTIONS] [RUN]
643	```
644
645	\| Argument or flag \| \|
646	\| --- \| --- \|
647	\| `[RUN]` \| \|
648	\| `-j, --job <JOB>` \| Show this job's steps only. \|
649	\| `--log` \| Print the log too. \|
650	\| `--log-failed` \| Print the failing steps' logs too. \|
651	\| `-w, --web` \| \|
652	\| `--exit-status` \| Exit 1 when the run failed. \|
653
654	Calls [`get_workflow_run`](/reference/api/actions/get-workflow-run/), [`get_job_logs`](/reference/api/actions/get-job-logs/).
655
656	### g1t run watch
657
658	Follow a run until it finishes; exits 1 if it fails.
659
660	```text
661	g1t run watch [OPTIONS] [RUN]
662	```
663
664	\| Argument or flag \| \|
665	\| --- \| --- \|
666	\| `[RUN]` \| \|
667	\| `-i, --interval <INTERVAL>` \| Seconds between looks. Default: `3`. \|
668
669	Calls [`get_workflow_run`](/reference/api/actions/get-workflow-run/).
670
671	### g1t run logs
672
673	Print a run's logs; --failed prints only the failing steps' tails.
674
675	```text
676	g1t run logs [OPTIONS] [RUN]
677	```
678
679	\| Argument or flag \| \|
680	\| --- \| --- \|
681	\| `[RUN]` \| \|
682	\| `-j, --job <JOB>` \| Only this job's (its id, key or name). \|
683	\| `-f, --failed` \| Only the failing steps, and only their last lines. \|
684	\| `-n, --tail <TAIL>` \| How many lines of each failing step to print, with --failed. Default: `60`. \|
685
686	Calls [`get_workflow_run`](/reference/api/actions/get-workflow-run/), [`get_job_logs`](/reference/api/actions/get-job-logs/).
687
688	### g1t run rerun
689
690	Run a run again: all of it, its failed jobs, or one job.
691
692	```text
693	g1t run rerun [OPTIONS] [RUN]
694	```
695
696	\| Argument or flag \| \|
697	\| --- \| --- \|
698	\| `[RUN]` \| \|
699	\| `--failed` \| Only the jobs that failed. \|
700	\| `-j, --job <JOB>` \| Only this job (its id). \|
701	\| `-d, --debug` \| With debug logging. \|
702
703	Calls [`rerun_workflow_run`](/reference/api/actions/rerun-workflow-run/), [`rerun_failed_jobs`](/reference/api/actions/rerun-failed-jobs/), [`rerun_job`](/reference/api/actions/rerun-job/).
704
705	### g1t run cancel
706
707	Cancel a run.
708
709	```text
710	g1t run cancel [OPTIONS] [RUN]
711	```
712
713	\| Argument or flag \| \|
714	\| --- \| --- \|
715	\| `[RUN]` \| The run's id (run_…) or number; the current branch's latest when left out. \|
716
717	Calls [`cancel_workflow_run`](/reference/api/actions/cancel-workflow-run/).
718
719	## g1t workflow
720
721	Workflows in .g1t/workflows: list, view, run, enable, disable.
722
723	### g1t workflow list
724
725	List the workflows in .g1t/workflows, with whether each is on.
726
727	```text
728	g1t workflow list [OPTIONS]
729	```
730
731	\| Argument or flag \| \|
732	\| --- \| --- \|
733	\| `-a, --all` \| Include the workflows that are turned off. \|
734	\| `-L, --limit <LIMIT>` \| Default: `50`. \|
735
736	Calls [`list_workflows`](/reference/api/actions/list-workflows/).
737
738	### g1t workflow view
739
740	Show a workflow and its latest runs; --yaml prints its file.
741
742	```text
743	g1t workflow view [OPTIONS] [WORKFLOW]
744	```
745
746	\| Argument or flag \| \|
747	\| --- \| --- \|
748	\| `[WORKFLOW]` \| Its file name (ci.yml), id (wfl_…) or name; asked for at a terminal when left out. \|
749	\| `-y, --yaml` \| Print the workflow's file. \|
750	\| `-g, --ref <REF>` \| The branch or tag to read the file on, with --yaml; the default branch when left out. \|
751	\| `-w, --web` \| Open it in the browser. \|
752
753	Calls [`list_workflows`](/reference/api/actions/list-workflows/), [`get_workflow`](/reference/api/actions/get-workflow/), [`list_workflow_runs`](/reference/api/actions/list-workflow-runs/).
754
755	### g1t workflow run
756
757	Run a workflow that has `on: workflow_dispatch`, and print its run's address.
758
759	```text
760	g1t workflow run [OPTIONS] [WORKFLOW]
761	```
762
763	\| Argument or flag \| \|
764	\| --- \| --- \|
765	\| `[WORKFLOW]` \| Its file name (ci.yml), id (wfl_…) or name; asked for at a terminal when left out. \|
766	\| `-g, --ref <REF>` \| The branch or tag to run it on; the default branch when left out. \|
767	\| `-f, --raw-field <KEY=VALUE>` \| An input, key=value; repeat for more. \|
768	\| `-F, --field <KEY=VALUE>` \| An input, key=value, where @FILE reads the value from a file (@- from stdin). \|
769
770	```text
771	Inputs are given with -f (or -F, where @FILE reads a file), or as a JSON object on
772	stdin with --json. At a terminal, with none given, g1t asks for each input.
773
774	Examples:
775	g1t workflow run release.yml
776	g1t workflow run release.yml --ref v1.4.0 -f channel=stable -f dry_run=true
777	echo '{"channel":"stable"}' \| g1t workflow run Release --json
778	```
779
780	Calls [`list_workflows`](/reference/api/actions/list-workflows/), [`dispatch_workflow`](/reference/api/actions/dispatch-workflow/), [`list_workflow_runs`](/reference/api/actions/list-workflow-runs/).
781
782	### g1t workflow enable
783
784	Turn a workflow on again.
785
786	```text
787	g1t workflow enable [OPTIONS] [WORKFLOW]
788	```
789
790	\| Argument or flag \| \|
791	\| --- \| --- \|
792	\| `[WORKFLOW]` \| Its file name (ci.yml), id (wfl_…) or name; asked for at a terminal when left out. \|
793
794	Calls [`list_workflows`](/reference/api/actions/list-workflows/), [`enable_workflow`](/reference/api/actions/enable-workflow/).
795
796	### g1t workflow disable
797
798	Turn a workflow off: its file stays, and nothing starts it until it is turned on.
799
800	```text
801	g1t workflow disable [OPTIONS] [WORKFLOW]
802	```
803
804	\| Argument or flag \| \|
805	\| --- \| --- \|
806	\| `[WORKFLOW]` \| Its file name (ci.yml), id (wfl_…) or name; asked for at a terminal when left out. \|
807
808	Calls [`list_workflows`](/reference/api/actions/list-workflows/), [`disable_workflow`](/reference/api/actions/disable-workflow/).
809
810	## g1t secret
811
812	Secrets for workflows and deployments, a repository's or a workspace's.
813
814	### g1t secret list
815
816	List secrets' names (never their values).
817
818	```text
819	g1t secret list [OPTIONS]
820	```
821
822	\| Argument or flag \| \|
823	\| --- \| --- \|
824	\| `-w, --workspace <WORKSPACE>` \| A workspace's secrets instead of the repository's. \|
825	\| `-e, --env <ENVIRONMENT>` \| Only the value for this environment (production, preview...). \|
826
827	Calls [`list_actions_secrets`](/reference/api/secrets-and-variables/list-actions-secrets/), [`list_actions_secrets_for_workspace`](/reference/api/secrets-and-variables/list-actions-secrets-for-workspace/).
828
829	### g1t secret set
830
831	Set a secret. The value is read from stdin when not given.
832
833	```text
834	g1t secret set [OPTIONS] <NAME>
835	```
836
837	\| Argument or flag \| \|
838	\| --- \| --- \|
839	\| `<NAME>` \| The secret's name; uppercased. \|
840	\| `-b, --body <BODY>` \| The value. Read from stdin when left out, so it stays out of your shell's history. \|
841	\| `-w, --workspace <WORKSPACE>` \| A workspace's secrets instead of the repository's. \|
842	\| `-e, --env <ENVIRONMENT>` \| Only the value for this environment (production, preview...). \|
843	\| `--available-to <WHO>` \| Who can read it: workflows, deployments, or both (repeat). \|
844	\| `--brokered-host <HOST>` \| Broker it: jobs get a stand-in, and g1t fills the value in only on requests to this host. Repeat for more. \|
845	\| `--note <NOTE>` \| A note for whoever reads the list. \|
846
847	Calls [`set_actions_secret`](/reference/api/secrets-and-variables/set-actions-secret/), [`set_actions_secret_for_workspace`](/reference/api/secrets-and-variables/set-actions-secret-for-workspace/).
848
849	### g1t secret delete
850
851	Delete a secret.
852
853	```text
854	g1t secret delete [OPTIONS] <NAME>
855	```
856
857	\| Argument or flag \| \|
858	\| --- \| --- \|
859	\| `<NAME>` \| \|
860	\| `-w, --workspace <WORKSPACE>` \| A workspace's secrets instead of the repository's. \|
861	\| `-e, --env <ENVIRONMENT>` \| Only the value for this environment (production, preview...). \|
862
863	Calls [`delete_actions_secret`](/reference/api/secrets-and-variables/delete-actions-secret/), [`delete_actions_secret_for_workspace`](/reference/api/secrets-and-variables/delete-actions-secret-for-workspace/).
864
865	## g1t cache
866
867	The repository's actions/cache entries: list, usage, delete.
868
869	### g1t cache list
870
871	List the repository's cache entries, least recently used last.
872
873	```text
874	g1t cache list [OPTIONS]
875	```
876
877	\| Argument or flag \| \|
878	\| --- \| --- \|
879	\| `-k, --key <KEY>` \| Only entries whose key starts with this. \|
880	\| `-g, --ref <REF>` \| Only entries saved by this ref's runs, e.g. refs/heads/main. \|
881	\| `-S, --sort <SORT>` \| One of `last-accessed-at`, `created-at`, `size-in-bytes`. Default: `last-accessed-at`. \|
882	\| `-O, --order <ORDER>` \| One of `asc`, `desc`. Default: `desc`. \|
883	\| `-L, --limit <LIMIT>` \| Default: `30`. \|
884
885	Calls [`list_caches`](/reference/api/actions/list-caches/).
886
887	### g1t cache usage
888
889	What the repository's cache entries hold, against its quota.
890
891	```text
892	g1t cache usage [OPTIONS]
893	```
894
895	Calls [`get_cache_usage`](/reference/api/actions/get-cache-usage/).
896
897	### g1t cache delete
898
899	Delete cache entries: one by its id, or every entry with a key.
900
901	```text
902	g1t cache delete [OPTIONS] <ENTRY>
903	```
904
905	\| Argument or flag \| \|
906	\| --- \| --- \|
907	\| `<ENTRY>` \| An entry's id (a number, from `g1t cache list`), or a key: every entry with exactly that key. \|
908	\| `-g, --ref <REF>` \| With a key, only the entries this ref's runs saved. \|
909
910	Calls [`delete_cache`](/reference/api/actions/delete-cache/), [`delete_caches_by_key`](/reference/api/actions/delete-caches-by-key/).
911
912	## g1t deploy
913
914	Deployments: list and view, and turn a project's g1t.page deployments on or off.
915
916	### g1t deploy list
917
918	List deployments, newest first.
919
920	```text
921	g1t deploy list [OPTIONS]
922	```
923
924	\| Argument or flag \| \|
925	\| --- \| --- \|
926	\| `-e, --env <ENV>` \| \|
927	\| `-s, --state <STATE>` \| queued, in_progress, success, failure, error or inactive. \|
928	\| `--source <SOURCE>` \| api, actions or g1t_page. \|
929	\| `-L, --limit <LIMIT>` \| Default: `20`. \|
930
931	Calls [`list_deployments`](/reference/api/deployments/list-deployments/).
932
933	### g1t deploy view
934
935	Show a deployment and its statuses.
936
937	```text
938	g1t deploy view [OPTIONS] <ID>
939	```
940
941	\| Argument or flag \| \|
942	\| --- \| --- \|
943	\| `<ID>` \| \|
944	\| `-w, --web` \| \|
945
946	Calls [`get_deployment`](/reference/api/deployments/get-deployment/).
947
948	### g1t deploy settings
949
950	Show a project's g1t.page deployment settings, or change them with flags.
951
952	```text
953	g1t deploy settings [OPTIONS]
954	```
955
956	\| Argument or flag \| \|
957	\| --- \| --- \|
958	\| `-p, --project <PROJECT>` \| The project, as SLUG or WORKSPACE/SLUG; the current repository's when left out. \|
959	\| `--production <SWITCH>` \| Deploy the default branch on every push. One of `on`, `off`. \|
960	\| `--previews <SWITCH>` \| A preview for every branch with an open pull request. One of `on`, `off`. \|
961	\| `--build-as <KIND>` \| auto, static, workers or docker. \|
962	\| `--build-command <COMMAND>` \| Runs instead of the project's own build script; "" for its own. \|
963	\| `--output-dir <DIR>` \| What a static site serves; "" to find it by itself. \|
964	\| `--dockerfile <PATH>` \| A container's Dockerfile, inside the project; "" for Dockerfile or Containerfile. \|
965	\| `--instance-type <SIZE>` \| A container's size: lite, basic, standard-1 to standard-4. \|
966	\| `--idle-days <DAYS>` \| A preview no one visits this many days comes down: 1 to 90. \|
967	\| `--via-workflow <SWITCH>` \| Build through the deploy workflow g1t manages for the project. One of `on`, `off`. \|
968
969	Calls [`get_deployment_settings`](/reference/api/deployments/get-deployment-settings/), [`update_deployment_settings`](/reference/api/deployments/update-deployment-settings/).
970
971	### g1t deploy enable
972
973	Turn on a project's g1t.page deployments: production builds from the default branch at once.
974
975	```text
976	g1t deploy enable [OPTIONS]
977	```
978
979	\| Argument or flag \| \|
980	\| --- \| --- \|
981	\| `-p, --project <PROJECT>` \| The project, as SLUG or WORKSPACE/SLUG; the current repository's when left out. \|
982
983	Calls [`update_deployment_settings`](/reference/api/deployments/update-deployment-settings/).
984
985	### g1t deploy disable
986
987	Turn off a project's g1t.page deployments: production and every preview come down.
988
989	```text
990	g1t deploy disable [OPTIONS]
991	```
992
993	\| Argument or flag \| \|
994	\| --- \| --- \|
995	\| `-p, --project <PROJECT>` \| The project, as SLUG or WORKSPACE/SLUG; the current repository's when left out. \|
996
997	Calls [`update_deployment_settings`](/reference/api/deployments/update-deployment-settings/).
998
999	## g1t logs
1000
1001	A project's logs and errors.
1002
1003	```text
1004	g1t logs [OPTIONS]
1005	```
1006
1007	\| Argument or flag \| \|
1008	\| --- \| --- \|
1009	\| `-p, --project <PROJECT>` \| The project; the current repository's when left out. \|
1010	\| `--errors` \| Grouped errors instead of log lines. \|
1011	\| `-q, --query <QUERY>` \| Lines holding all of these words, or a "quoted phrase". \|
1012	\| `-l, --level <LEVEL>` \| Levels: trace, debug, info, warn, error, fatal (comma-separated). \|
1013	\| `-e, --env <ENV>` \| \|
1014	\| `--service <SERVICE>` \| \|
1015	\| `-s, --since <SINCE>` \| How far back: 15m, 2h, 1d, or a time like 2026-10-12T09:00:00Z. \|
1016	\| `--state <STATE>` \| With --errors: open, resolved or ignored. \|
1017	\| `-f, --follow` \| Keep printing new lines as they come. \|
1018	\| `-L, --limit <LIMIT>` \| Default: `50`. \|
1019
1020	Calls [`list_logs`](/reference/api/observability/list-logs/), [`list_errors`](/reference/api/observability/list-errors/), [`list_projects`](/reference/api/projects/list-projects/), [`get_repo`](/reference/api/repositories/get-repo/).
1021
1022	## g1t status
1023
1024	What needs you: your pull requests, reviews asked of you, your issues, failing checks, and your sessions and claims here.
1025
1026	```text
1027	g1t status [OPTIONS]
1028	```
1029
1030	Calls [`search`](/reference/api/search/search/), [`list_notifications`](/reference/api/notifications/list-notifications/), [`get_pull_request`](/reference/api/pull-requests/get-pull-request/), [`list_sessions`](/reference/api/sessions/list-sessions/), [`list_claims`](/reference/api/claims-and-work/list-claims/).
1031
1032	## g1t session
1033
1034	Sessions: one run of an agent's harness, recorded as it works.
1035
1036	### g1t session start
1037
1038	Start a session and remember it for this working copy. Prints its id.
1039
1040	```text
1041	g1t session start [OPTIONS]
1042	```
1043
1044	\| Argument or flag \| \|
1045	\| --- \| --- \|
1046	\| `-i, --issue <ISSUE>` \| The issue it works on. \|
1047	\| `-p, --pull <PULL>` \| The pull request it works on. \|
1048	\| `--harness <HARNESS>` \| The harness running it. One of `claude_code`, `codex`, `cursor`, `copilot`, `other`. Default: `other`. \|
1049	\| `--harness-session-id <ID>` \| The harness's own id for the run, which makes starting again return the same session. \|
1050	\| `-t, --title <TITLE>` \| \|
1051	\| `-b, --branch <BRANCH>` \| The branch it works on; the current one when left out. \|
1052	\| `--parent <SESSION>` \| For a subagent: the session that started it (ses_…). \|
1053	\| `--agent-type <AGENT_TYPE>` \| For a subagent: its kind (Explore, security-reviewer). \|
1054	\| `--task <TASK>` \| For a subagent: the task it was given, in a few words. \|
1055	\| `--prompt <PROMPT>` \| For a subagent: the prompt its parent gave it. \|
1056	\| `--model <MODEL>` \| The model it runs on. \|
1057	\| `--no-remember` \| Do not remember it as this working copy's session (a subagent's, kept by its harness). \|
1058
1059	```text
1060	The id is kept in .git/g1t/session (each worktree has its own); G1T_SESSION overrides it.
1061	Starting again with the same --harness-session-id returns the same session.
1062	```
1063
1064	Calls [`start_session`](/reference/api/sessions/start-session/).
1065
1066	### g1t session heartbeat
1067
1068	Say the current session is still working; renews its claims.
1069
1070	```text
1071	g1t session heartbeat [OPTIONS]
1072	```
1073
1074	Calls [`update_session`](/reference/api/sessions/update-session/).
1075
1076	### g1t session log
1077
1078	Record a note, prompt or message in the current session.
1079
1080	```text
1081	g1t session log [OPTIONS] <TEXT>
1082	```
1083
1084	\| Argument or flag \| \|
1085	\| --- \| --- \|
1086	\| `<TEXT>` \| What to record; - reads it from stdin. \|
1087	\| `-k, --kind <KIND>` \| One of `note`, `prompt`, `message`, `tool_call`, `skill`. Default: `note`. \|
1088	\| `--tool <TOOL>` \| The tool, for a tool_call. \|
1089	\| `--key <KEY>` \| A key that makes recording it again do nothing. \|
1090
1091	Calls [`record_session_entries`](/reference/api/sessions/record-session-entries/).
1092
1093	### g1t session attach
1094
1095	Attach the current session to an issue, a pull request or a branch, or give it a title.
1096
1097	```text
1098	g1t session attach [OPTIONS] <--issue <ISSUE>\|--pull <PULL>\|--branch <BRANCH>\|--head-commit <SHA>\|--title <TITLE>>
1099	```
1100
1101	\| Argument or flag \| \|
1102	\| --- \| --- \|
1103	\| `-i, --issue <ISSUE>` \| \|
1104	\| `-p, --pull <PULL>` \| \|
1105	\| `-b, --branch <BRANCH>` \| \|
1106	\| `--head-commit <SHA>` \| The commit it pushed last. \|
1107	\| `-t, --title <TITLE>` \| What it is for, in a few words; replaces its title. \|
1108
1109	Calls [`update_session`](/reference/api/sessions/update-session/).
1110
1111	### g1t session end
1112
1113	End the current session.
1114
1115	```text
1116	g1t session end [OPTIONS]
1117	```
1118
1119	\| Argument or flag \| \|
1120	\| --- \| --- \|
1121	\| `-r, --reason <REASON>` \| Why it ended: done, abandoned, handed_off... \|
1122	\| `--result <RESULT>` \| What it reported when it finished (a subagent's final message); - reads it from stdin. \|
1123
1124	Calls [`end_session`](/reference/api/sessions/end-session/).
1125
1126	### g1t session list
1127
1128	List the repository's sessions.
1129
1130	```text
1131	g1t session list [OPTIONS]
1132	```
1133
1134	\| Argument or flag \| \|
1135	\| --- \| --- \|
1136	\| `-s, --state <STATE>` \| Only sessions in this state. One of `active`, `idle`, `ended`. \|
1137	\| `-i, --issue <ISSUE>` \| \|
1138	\| `-p, --pull <PULL>` \| \|
1139	\| `-L, --limit <LIMIT>` \| Default: `20`. \|
1140	\| `--path <PATH>` \| Only sessions that touched this file, or any under it when it ends in /. \|
1141	\| `--subagents` \| List subagents too, under the sessions that started them. \|
1142
1143	Calls [`list_sessions`](/reference/api/sessions/list-sessions/).
1144
1145	### g1t session view
1146
1147	Show a session and what it recorded; the current one when left out.
1148
1149	```text
1150	g1t session view [OPTIONS] [ID]
1151	```
1152
1153	\| Argument or flag \| \|
1154	\| --- \| --- \|
1155	\| `[ID]` \| The session's id (ses_…); the current one when left out. \|
1156
1157	Calls [`get_session`](/reference/api/sessions/get-session/).
1158
1159	### g1t session updates
1160
1161	Read pending coordination updates without acknowledging them.
1162
1163	```text
1164	g1t session updates [OPTIONS] [ID]
1165	```
1166
1167	\| Argument or flag \| \|
1168	\| --- \| --- \|
1169	\| `[ID]` \| The session's id (ses_…); the current one when left out. \|
1170
1171	```text
1172	First says which files this working copy changed (git status, from its root), as `session touch`
1173	would, so another session changing the same files is an overlap.detected for both: heartbeat and
1174	acknowledge do too. G1T_TOUCH=0 turns that off.
1175	```
1176
1177	Calls [`get_session`](/reference/api/sessions/get-session/).
1178
1179	### g1t session acknowledge
1180
1181	Record your decision, then acknowledge exact coordination update IDs.
1182
1183	```text
1184	g1t session acknowledge [OPTIONS] --note <NOTE> <UPDATES>...
1185	```
1186
1187	\| Argument or flag \| \|
1188	\| --- \| --- \|
1189	\| `<UPDATES>` \| IDs you have considered. Never pass unseen updates. At most 100. \|
1190	\| `--note <NOTE>` \| What changed in your plan, or why no change is needed. \|
1191	\| `--session <SESSION>` \| Use this session instead of G1T_SESSION or the working copy's session. \|
1192
1193	Calls [`record_session_entries`](/reference/api/sessions/record-session-entries/).
1194
1195	### g1t session touch
1196
1197	Say what the current session touched: files, commits, branches, pull requests, issues.
1198
1199	```text
1200	g1t session touch [OPTIONS] <--file <FILE>\|--commit <COMMIT>\|--branch <BRANCH>\|--pull <PULL>\|--issue <ISSUE>>
1201	```
1202
1203	\| Argument or flag \| \|
1204	\| --- \| --- \|
1205	\| `--file <FILE>` \| A file it wrote, from the repository's root. Repeat for more. \|
1206	\| `--commit <COMMIT>` \| A commit it made. \|
1207	\| `--branch <BRANCH>` \| A branch it pushed. \|
1208	\| `--pull <PULL>` \| A pull request it opened. \|
1209	\| `--issue <ISSUE>` \| An issue it named. \|
1210
1211	```text
1212	Each is kept once. A file another active session touched too (a sibling subagent's included)
1213	is an overlap.detected event for both. Pull requests and issues tie the session to them.
1214	```
1215
1216	Calls [`record_session_entries`](/reference/api/sessions/record-session-entries/).
1217
1218	## g1t work
1219
1220	Coordinate work on issues: context, claims, hand-offs, dependencies, events.
1221
1222	### g1t work context
1223
1224	Everything about an issue's work: claims, sessions, pull requests, dependencies, decisions.
1225
1226	```text
1227	g1t work context [OPTIONS] <NUMBER>
1228	```
1229
1230	\| Argument or flag \| \|
1231	\| --- \| --- \|
1232	\| `<NUMBER>` \| The issue's number. \|
1233
1234	Calls [`get_work`](/reference/api/claims-and-work/get-work/).
1235
1236	### g1t work claim
1237
1238	Claim an issue: say you are working on it. Others are told, never stopped.
1239
1240	```text
1241	g1t work claim [OPTIONS] <NUMBER\|--title <TITLE>>
1242	```
1243
1244	\| Argument or flag \| \|
1245	\| --- \| --- \|
1246	\| `[NUMBER]` \| The issue's number. \|
1247	\| `--title <TITLE>` \| Open a new issue with this title and claim it; the current session is attached to it. \|
1248	\| `--body <BODY>` \| The new issue's description. \|
1249	\| `-n, --note <NOTE>` \| What you are doing about it. \|
1250	\| `--ttl <DURATION>` \| How long the claim lasts unless renewed: 30m, 2h (at most 4h). \|
1251
1252	```text
1253	With --title instead of a number, a new issue is opened and claimed in one step, and the
1254	current session is attached to it: for work that became a change others should know about.
1255	Examples:
1256	g1t work claim 12 --note "Rewriting the retry loop"
1257	g1t work claim --title "Preview builds time out on large repositories"
1258	```
1259
1260	Calls [`claim_issue`](/reference/api/claims-and-work/claim-issue/), [`claim_new_issue`](/reference/api/claims-and-work/claim-new-issue/).
1261
1262	### g1t work release
1263
1264	Release your claim on an issue.
1265
1266	```text
1267	g1t work release [OPTIONS] <NUMBER>
1268	```
1269
1270	\| Argument or flag \| \|
1271	\| --- \| --- \|
1272	\| `<NUMBER>` \| \|
1273	\| `-r, --reason <REASON>` \| Why: done, blocked, abandoned... \|
1274
1275	Calls [`release_claim`](/reference/api/claims-and-work/release-claim/).
1276
1277	### g1t work handoff
1278
1279	Hand an issue over to someone else, or to anyone.
1280
1281	```text
1282	g1t work handoff [OPTIONS] --note <NOTE> <NUMBER>
1283	```
1284
1285	\| Argument or flag \| \|
1286	\| --- \| --- \|
1287	\| `<NUMBER>` \| \|
1288	\| `--to <LOGIN>` \| Who takes it over; anyone when left out. \|
1289	\| `-n, --note <NOTE>` \| Where it stands and what is left, for whoever takes it. \|
1290
1291	Calls [`hand_off_issue`](/reference/api/claims-and-work/hand-off-issue/).
1292
1293	### g1t work list
1294
1295	Active claims and sessions in the repository.
1296
1297	```text
1298	g1t work list [OPTIONS]
1299	```
1300
1301	Calls [`list_claims`](/reference/api/claims-and-work/list-claims/), [`list_sessions`](/reference/api/sessions/list-sessions/).
1302
1303	### g1t work block
1304
1305	Say an issue waits on others: it is blocked by them.
1306
1307	```text
1308	g1t work block [OPTIONS] --by <NUMBER> <NUMBER>
1309	```
1310
1311	\| Argument or flag \| \|
1312	\| --- \| --- \|
1313	\| `<NUMBER>` \| The issue that waits. \|
1314	\| `--by <NUMBER>` \| The issue it waits on; repeat for more. \|
1315
1316	Calls [`get_issue`](/reference/api/issues/get-issue/), [`update_issue`](/reference/api/issues/update-issue/).
1317
1318	### g1t work unblock
1319
1320	Say an issue no longer waits on others.
1321
1322	```text
1323	g1t work unblock [OPTIONS] --by <NUMBER> <NUMBER>
1324	```
1325
1326	\| Argument or flag \| \|
1327	\| --- \| --- \|
1328	\| `<NUMBER>` \| The issue that waits. \|
1329	\| `--by <NUMBER>` \| The issue it waits on; repeat for more. \|
1330
1331	Calls [`get_issue`](/reference/api/issues/get-issue/), [`update_issue`](/reference/api/issues/update-issue/).
1332
1333	### g1t work events
1334
1335	The repository's events; --follow keeps printing them as they happen.
1336
1337	```text
1338	g1t work events [OPTIONS]
1339	```
1340
1341	\| Argument or flag \| \|
1342	\| --- \| --- \|
1343	\| `-f, --follow` \| Keep printing events as they happen, until stopped. \|
1344	\| `-t, --type <TYPE>` \| Only events of this type; repeat for more. \|
1345	\| `-i, --issue <NUMBER>` \| Only events about this issue or pull request; repeat for more. \|
1346	\| `-s, --since <SINCE>` \| Only events since then: 15m, 2h, 1d, or a time like 2026-10-12T09:00:00Z. \|
1347	\| `--after <EVENT_ID>` \| Start after this event id, as a follow that stopped would resume. \|
1348	\| `-L, --limit <LIMIT>` \| How many past events to show first. Default: `20`. \|
1349
1350	```text
1351	Examples:
1352	g1t work events --follow --issue 12
1353	g1t work events --follow --type integration.failed --type overlap.detected --json
1354	With --json, each event is one JSON object on a line of its own.
1355	```
1356
1357	Calls [`list_events`](/reference/api/repositories/list-events/).
1358
1359	### g1t work dispatch
1360
1361	Start work on an issue in a session on your own Claude, or print the Claude Code command for it.
1362
1363	```text
1364	g1t work dispatch [OPTIONS] <NUMBER\|--title <TITLE>>
1365	```
1366
1367	\| Argument or flag \| \|
1368	\| --- \| --- \|
1369	\| `[NUMBER]` \| The issue's number. \|
1370	\| `--title <TITLE>` \| Open a new issue with this title and work on it. \|
1371	\| `--body <BODY>` \| The new issue's description. \|
1372	\| `-i, --instruction <INSTRUCTION>` \| What to do beyond what the issue says. \|
1373	\| `-m, --mode <MODE>` \| What kind of work. One of `plan`, `implement`, `review`. \|
1374	\| `--handoff` \| Print the Claude Code command to run yourself; start nothing. \|
1375	\| `--managed` \| Start it on the workspace's Anthropic account, or fail. \|
1376
1377	```text
1378	With the workspace's Anthropic AI provider, a Claude Managed Agents session starts on that
1379	account and is recorded on g1t; otherwise (or with --handoff) this prints a `claude` command
1380	to run with g1t's plugin, whose session attaches to the issue as it starts.
1381	Examples:
1382	g1t work dispatch 12
1383	g1t work dispatch 12 --mode plan --instruction "Keep the old flag"
1384	g1t work dispatch --title "Add a healthcheck" --handoff
1385	```
1386
1387	Calls [`start_agent_session`](/reference/api/sessions/start-agent-session/).
1388
1389	## g1t why
1390
1391	Why a file or line is as it is: its commit, pull request, issue, decisions and sessions.
1392
1393	```text
1394	g1t why [OPTIONS] <TARGET>
1395	```
1396
1397	\| Argument or flag \| \|
1398	\| --- \| --- \|
1399	\| `<TARGET>` \| A file, or a line of it as PATH:LINE. \|
1400	\| `--ref <REF>` \| The branch, tag or commit to read it at; the default branch when left out. \|
1401
1402	Calls [`why`](/reference/api/decisions-and-why/why/).
1403
1404	## g1t attach
1405
1406	Upload images, such as a screenshot, to show in an issue, a pull request or a comment; prints their Markdown.
1407
1408	```text
1409	g1t attach [OPTIONS] <FILE>...
1410	```
1411
1412	\| Argument or flag \| \|
1413	\| --- \| --- \|
1414	\| `<FILE>` \| The files: PNG, JPEG, GIF or WebP, at most 10 MB each. \|
1415
1416	```text
1417	Prints each image's Markdown, ![name](url), to paste into a description or a comment; --json prints
1418	{ id, name, url, markdown, content_type, size } (a list for several files). The image is served from
1419	g1t's usercontent address, and anyone given that address can see it, even from a private repository.
1420	--attach FILE on g1t issue create, g1t issue comment, g1t pr create, g1t pr comment and g1t pr ready
1421	uploads and adds the Markdown for you:
1422	g1t attach preview.png
1423	g1t pr comment --body 'The preview, after the fix:' --attach preview.png
1424	```
1425
1426	Calls [`upload_attachment`](/reference/api/issues/upload-attachment/).
1427
1428	## g1t api
1429
1430	Call any API operation or path, with your token.
1431
1432	```text
1433	g1t api [OPTIONS] [ENDPOINT]
1434	```
1435
1436	\| Argument or flag \| \|
1437	\| --- \| --- \|
1438	\| `[ENDPOINT]` \| An operation's name, or a path. \|
1439	\| `--list [QUERY]` \| List the operations, or those matching this word. \|
1440	\| `-X, --method <METHOD>` \| The HTTP method: GET unless fields are given, then POST. \|
1441	\| `-f, --raw-field <KEY=VALUE>` \| A string field, key=value. key[]=value adds to a list. \|
1442	\| `-F, --field <KEY=VALUE>` \| A typed field: true, false, null and numbers become JSON; @file reads a file. \|
1443	\| `-H, --header <KEY:VALUE>` \| A request header, key:value. \|
1444	\| `--input <FILE>` \| The request body, from a file or - for stdin. \|
1445	\| `--paginate` \| Follow next pages until there are none. \|
1446	\| `--slurp` \| With --paginate, put every page's items into one array. \|
1447	\| `-i, --include` \| Print the status line and headers too. \|
1448	\| `--silent` \| Print nothing on success. \|
1449
1450	```text
1451	ENDPOINT is an operation's name (list_issues) or a path (/repos/{owner}/{name}/issues).
1452	{owner}, {name}, {repo} and {workspace} are filled in from the current repository,
1453	and an operation's other path parameters from -f/-F fields of the same name.
1454
1455	Examples:
1456	g1t api list_issues -f state=closed
1457	g1t api /user --jq .username
1458	g1t api create_issue -f title='Broken link' -f labels[]=docs
1459	g1t api list_workflow_runs --paginate --jq '.[].conclusion'
1460	g1t api --list issue
1461	```
1462
1463	## g1t browse
1464
1465	Open the repository, an issue or a pull request in the browser.
1466
1467	```text
1468	g1t browse [OPTIONS] [TARGET]
1469	```
1470
1471	\| Argument or flag \| \|
1472	\| --- \| --- \|
1473	\| `[TARGET]` \| An issue or pull request number, a file path (path:line), or a commit. \|
1474	\| `-b, --branch <BRANCH>` \| The branch to show files on. \|
1475	\| `-s, --settings` \| \|
1476	\| `--issues` \| \|
1477	\| `--pulls` \| \|
1478	\| `--actions` \| \|
1479	\| `-n, --no-browser` \| Print the address instead of opening it. \|
1480
1481	## g1t alias
1482
1483	Shortcuts for commands you type often.
1484
1485	### g1t alias set
1486
1487	Make an alias: g1t alias set co 'pr checkout'. Start it with ! to run it through the shell.
1488
1489	```text
1490	g1t alias set [OPTIONS] <NAME> <EXPANSION>
1491	```
1492
1493	\| Argument or flag \| \|
1494	\| --- \| --- \|
1495	\| `<NAME>` \| \|
1496	\| `<EXPANSION>` \| What it expands to. $1, $2... take the arguments after it. \|
1497
1498	### g1t alias list
1499
1500	List aliases.
1501
1502	```text
1503	g1t alias list [OPTIONS]
1504	```
1505
1506	### g1t alias delete
1507
1508	Delete an alias.
1509
1510	```text
1511	g1t alias delete [OPTIONS] <NAME>
1512	```
1513
1514	\| Argument or flag \| \|
1515	\| --- \| --- \|
1516	\| `<NAME>` \| \|
1517
1518	## g1t completion
1519
1520	Print a shell completion script.
1521
1522	```text
1523	g1t completion [OPTIONS] <SHELL>
1524	```
1525
1526	\| Argument or flag \| \|
1527	\| --- \| --- \|
1528	\| `<SHELL>` \| One of `bash`, `elvish`, `fish`, `powershell`, `zsh`. \|
1529
1530	## g1t push
1531
1532	Push a local container image to g1t's registry, in chunks.
1533
1534	```text
1535	g1t push [OPTIONS] [IMAGE]
1536	```
1537
1538	\| Argument or flag \| \|
1539	\| --- \| --- \|
1540	\| `[IMAGE]` \| The local image, [REGISTRY/]NAME[:TAG]. \|
1541	\| `--as <ADDRESS>` \| Where to push, when the image's own name is not an address on g1t.sh. The tag defaults to latest. \|
1542	\| `--chunk-size <SIZE>` \| How much of a layer each request carries: 5MB to 95MB. Default: `90MB`. \|
1543	\| `--token-stdin` \| Read the g1t token from stdin. \|
1544	\| `--archive <FILE>` \| Push a tarball `docker save` wrote, instead of asking docker for the image. \|
1545
1546	```text
1547	The token is the first of: --token-stdin, G1T_TOKEN, the account `g1t auth login`
1548	signed in for the registry's host, or what `docker login g1t.sh` stored.
1549	```
1550
1551	## g1t upgrade
1552
1553	Update g1t to the newest release, checked against g1t's release key.
1554
1555	```text
1556	g1t upgrade [OPTIONS]
1557	```
1558
1559	\| Argument or flag \| \|
1560	\| --- \| --- \|
1561	\| `--check` \| Only say whether a newer release is out. \|
1562
1563	```text
1564	Downloads the newest release for this machine from g1t.sh, checks its signature and SHA-256, and puts it
1565	where this g1t is. In a terminal, g1t also says once a day when a newer release is out;
1566	G1T_NO_UPDATE_NOTIFIER=1 turns that off.
1567	```