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