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,610 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	Calls [`update_session`](/reference/api/sessions/update-session/).
943
944	### g1t session log
945
946	Record a note, prompt or message in the current session.
947
948	```text
949	g1t session log [OPTIONS] <TEXT>
950	```
951
952	\| Argument or flag \| \|
953	\| --- \| --- \|
954	\| `<TEXT>` \| What to record; - reads it from stdin. \|
955	\| `-k, --kind <KIND>` \| One of `note`, `prompt`, `message`, `tool_call`, `skill`. Default: `note`. \|
956	\| `--tool <TOOL>` \| The tool, for a tool_call. \|
957	\| `--key <KEY>` \| A key that makes recording it again do nothing. \|
958
959	Calls [`record_session_entries`](/reference/api/sessions/record-session-entries/).
960
961	### g1t session attach
962
963	Attach the current session to a work item, a pull request or a branch, or give it a title.
964
965	```text
966	g1t session attach [OPTIONS] <--item <ITEM>\|--pull <PULL>\|--branch <BRANCH>\|--head-commit <SHA>\|--title <TITLE>>
967	```
968
969	\| Argument or flag \| \|
970	\| --- \| --- \|
971	\| `-i, --item <ITEM>` \| A work item, by its number in the workspace. \|
972	\| `-p, --pull <PULL>` \| \|
973	\| `-b, --branch <BRANCH>` \| \|
974	\| `--head-commit <SHA>` \| The commit it pushed last. \|
975	\| `-t, --title <TITLE>` \| What it is for, in a few words; replaces its title. \|
976
977	Calls [`update_session`](/reference/api/sessions/update-session/).
978
979	### g1t session end
980
981	End the current session.
982
983	```text
984	g1t session end [OPTIONS]
985	```
986
987	\| Argument or flag \| \|
988	\| --- \| --- \|
989	\| `-r, --reason <REASON>` \| Why it ended: done, abandoned, handed_off... \|
990	\| `--result <RESULT>` \| What it reported when it finished (a subagent's final message); - reads it from stdin. \|
991
992	Calls [`end_session`](/reference/api/sessions/end-session/).
993
994	### g1t session list
995
996	List the repository's sessions.
997
998	```text
999	g1t session list [OPTIONS]
1000	```
1001
1002	\| Argument or flag \| \|
1003	\| --- \| --- \|
1004	\| `-s, --state <STATE>` \| Only sessions in this state. One of `active`, `idle`, `ended`. \|
1005	\| `-i, --item <ITEM>` \| Only sessions on this work item. \|
1006	\| `-p, --pull <PULL>` \| \|
1007	\| `-L, --limit <LIMIT>` \| Default: `20`. \|
1008	\| `--path <PATH>` \| Only sessions that touched this file, or any under it when it ends in /. \|
1009	\| `--subagents` \| List subagents too, under the sessions that started them. \|
1010	\| `--workspace [SLUG]` \| Every repository of a workspace you may read, every kind of session: this repository's workspace, or the one named. \|
1011	\| `--harness <HARNESS>` \| With --workspace: only sessions in this harness (claude_code, codex, …). \|
1012	\| `--person <PERSON>` \| With --workspace: only sessions this person runs, by username. \|
1013	\| `--in <NAME>` \| With --workspace: only sessions in this repository of it, by name. \|
1014
1015	Calls [`list_sessions`](/reference/api/sessions/list-sessions/), [`list_workspace_sessions`](/reference/api/sessions/list-workspace-sessions/).
1016
1017	### g1t session view
1018
1019	Show a session and what it recorded; the current one when left out.
1020
1021	```text
1022	g1t session view [OPTIONS] [ID]
1023	```
1024
1025	\| Argument or flag \| \|
1026	\| --- \| --- \|
1027	\| `[ID]` \| The session's id (ses_…); the current one when left out. \|
1028
1029	Calls [`get_session`](/reference/api/sessions/get-session/).
1030
1031	### g1t session updates
1032
1033	Read pending coordination updates without acknowledging them.
1034
1035	```text
1036	g1t session updates [OPTIONS] [ID]
1037	```
1038
1039	\| Argument or flag \| \|
1040	\| --- \| --- \|
1041	\| `[ID]` \| The session's id (ses_…); the current one when left out. \|
1042
1043	```text
1044	First says which files this working copy changed (git status, from its root), as `session touch`
1045	would, so another session changing the same files is an overlap.detected for both: heartbeat and
1046	acknowledge do too. G1T_TOUCH=0 turns that off.
1047	```
1048
1049	Calls [`get_session`](/reference/api/sessions/get-session/).
1050
1051	### g1t session acknowledge
1052
1053	Record your decision, then acknowledge exact coordination update IDs.
1054
1055	```text
1056	g1t session acknowledge [OPTIONS] --note <NOTE> <UPDATES>...
1057	```
1058
1059	\| Argument or flag \| \|
1060	\| --- \| --- \|
1061	\| `<UPDATES>` \| IDs you have considered. Never pass unseen updates. At most 100. \|
1062	\| `--note <NOTE>` \| What changed in your plan, or why no change is needed. \|
1063	\| `--session <SESSION>` \| Use this session instead of G1T_SESSION or the working copy's session. \|
1064
1065	Calls [`record_session_entries`](/reference/api/sessions/record-session-entries/).
1066
1067	### g1t session touch
1068
1069	Say what the current session touched: files, commits, branches, pull requests, work items.
1070
1071	```text
1072	g1t session touch [OPTIONS] <--file <FILE>\|--commit <COMMIT>\|--branch <BRANCH>\|--pull <PULL>\|--item <ITEM>>
1073	```
1074
1075	\| Argument or flag \| \|
1076	\| --- \| --- \|
1077	\| `--file <FILE>` \| A file it wrote, from the repository's root. Repeat for more. \|
1078	\| `--commit <COMMIT>` \| A commit it made. \|
1079	\| `--branch <BRANCH>` \| A branch it pushed. \|
1080	\| `--pull <PULL>` \| A pull request it opened. \|
1081	\| `--item <ITEM>` \| A work item it named, by its number in the workspace. \|
1082
1083	```text
1084	Each is kept once. A file another active session touched too (a sibling subagent's included)
1085	is an overlap.detected event for both. Pull requests and work items tie the session to them.
1086	```
1087
1088	Calls [`record_session_entries`](/reference/api/sessions/record-session-entries/).
1089
1090	## g1t work
1091
1092	Work items: list, view, new, edit, link, close; claims, hand-offs, dependencies, events.
1093
1094	Flags every `g1t work` command takes:
1095
1096	\| Flag \| \|
1097	\| --- \| --- \|
1098	\| `--workspace <SLUG>` \| The workspace, by its slug; the current repository's when left out. Also `G1T_WORKSPACE`. \|
1099
1100	### g1t work list
1101
1102	List the workspace's work items; with --repo, those linked to that repository.
1103
1104	```text
1105	g1t work list [OPTIONS]
1106	```
1107
1108	\| Argument or flag \| \|
1109	\| --- \| --- \|
1110	\| `-s, --state <STATE>` \| One of `open`, `closed`, `all`. Default: `open`. \|
1111	\| `-l, --label <LABEL>` \| Only work items with this label. \|
1112	\| `-m, --milestone <MILESTONE>` \| Only work items in the workspace milestone of this number. \|
1113	\| `-a, --assignee <ASSIGNEE>` \| Only work items assigned to this person (@me for you). \|
1114	\| `-A, --author <AUTHOR>` \| Only work items opened by this person (@me for you). \|
1115	\| `--role <ROLE>` \| With --repo: only those linked to it this way. One of `origin`, `target`, `touched`. \|
1116	\| `-L, --limit <LIMIT>` \| Default: `20`. \|
1117
1118	Calls [`list_work_items`](/reference/api/work-items/list-work-items/).
1119
1120	### g1t work view
1121
1122	Show a work item with everything about its work: repositories and what landed, claims, sessions, pull requests, what it waits on, decisions.
1123
1124	```text
1125	g1t work view [OPTIONS] <NUMBER>
1126	```
1127
1128	\| Argument or flag \| \|
1129	\| --- \| --- \|
1130	\| `<NUMBER>` \| The work item's number. \|
1131	\| `-c, --comments` \| Show its comments too. \|
1132	\| `-w, --web` \| Open it in the browser. \|
1133
1134	Calls [`get_work`](/reference/api/work-items/get-work/), [`get_work_item`](/reference/api/work-items/get-work-item/).
1135
1136	### g1t work new
1137
1138	Open a work item, with the current repository as its origin.
1139
1140	```text
1141	g1t work new [OPTIONS]
1142	```
1143
1144	\| Argument or flag \| \|
1145	\| --- \| --- \|
1146	\| `-t, --title <TITLE>` \| \|
1147	\| `-b, --body <BODY>` \| The text. Markdown. \|
1148	\| `-F, --body-file <FILE>` \| Read the text from a file, or - for stdin. \|
1149	\| `--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. \|
1150	\| `--target <OWNER/NAME>` \| A repository of the workspace where the work is meant to land, OWNER/NAME; repeat for more. \|
1151	\| `-l, --label <LABEL>` \| A label; repeat for more. \|
1152	\| `-a, --assignee <ASSIGNEE>` \| Someone to assign; repeat for more (@me for you). \|
1153	\| `-m, --milestone <MILESTONE>` \| A workspace milestone's number. \|
1154	\| `-w, --web` \| Open the new work item page in the browser instead. \|
1155
1156	```text
1157	In a repository, the work item is filed from it (its origin). With --workspace and no
1158	repository of that workspace here, it is filed in the workspace alone. --target names a repository
1159	where the work is meant to land; repeat it for more.
1160	Examples:
1161	g1t work new --title "Sign-in times out on slow networks" --body "..."
1162	g1t work new --title "Rename the flag" --target acme/api --target acme/docs
1163	```
1164
1165	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/).
1166
1167	### g1t work comment
1168
1169	Comment on a work item.
1170
1171	```text
1172	g1t work comment [OPTIONS] <NUMBER>
1173	```
1174
1175	\| Argument or flag \| \|
1176	\| --- \| --- \|
1177	\| `<NUMBER>` \| The work item's number. \|
1178	\| `-b, --body <BODY>` \| The text. Markdown. \|
1179	\| `-F, --body-file <FILE>` \| Read the text from a file, or - for stdin. \|
1180	\| `--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. \|
1181
1182	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/).
1183
1184	### g1t work edit
1185
1186	Change a work item's title, body, labels, assignees or milestone.
1187
1188	```text
1189	g1t work edit [OPTIONS] <NUMBER>
1190	```
1191
1192	\| Argument or flag \| \|
1193	\| --- \| --- \|
1194	\| `<NUMBER>` \| \|
1195	\| `-t, --title <TITLE>` \| \|
1196	\| `-b, --body <BODY>` \| The text. Markdown. \|
1197	\| `-F, --body-file <FILE>` \| Read the text from a file, or - for stdin. \|
1198	\| `--add-label <LABEL>` \| \|
1199	\| `--remove-label <LABEL>` \| \|
1200	\| `--add-assignee <LOGIN>` \| \|
1201	\| `--remove-assignee <LOGIN>` \| \|
1202	\| `-m, --milestone <MILESTONE>` \| A workspace milestone's number. \|
1203	\| `--remove-milestone` \| Take it out of its milestone. \|
1204
1205	Calls [`update_work_item`](/reference/api/work-items/update-work-item/), [`get_work_item`](/reference/api/work-items/get-work-item/).
1206
1207	### g1t work close
1208
1209	Close a work item.
1210
1211	```text
1212	g1t work close [OPTIONS] <NUMBER>
1213	```
1214
1215	\| Argument or flag \| \|
1216	\| --- \| --- \|
1217	\| `<NUMBER>` \| \|
1218	\| `-r, --reason <REASON>` \| One of `completed`, `not_planned`. \|
1219	\| `-c, --comment <COMMENT>` \| Leave a comment as it closes. \|
1220	\| `--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. \|
1221
1222	Calls [`close_work_item`](/reference/api/work-items/close-work-item/), [`add_work_item_comment`](/reference/api/work-items/add-work-item-comment/).
1223
1224	### g1t work reopen
1225
1226	Reopen a work item.
1227
1228	```text
1229	g1t work reopen [OPTIONS] <NUMBER>
1230	```
1231
1232	\| Argument or flag \| \|
1233	\| --- \| --- \|
1234	\| `<NUMBER>` \| \|
1235	\| `-c, --comment <COMMENT>` \| Leave a comment as it reopens. \|
1236
1237	Calls [`reopen_work_item`](/reference/api/work-items/reopen-work-item/), [`add_work_item_comment`](/reference/api/work-items/add-work-item-comment/).
1238
1239	### g1t work link
1240
1241	Link a repository to a work item: where the work must land (target), or touched.
1242
1243	```text
1244	g1t work link [OPTIONS] <NUMBER>
1245	```
1246
1247	\| Argument or flag \| \|
1248	\| --- \| --- \|
1249	\| `<NUMBER>` \| The work item's number. \|
1250	\| `--role <ROLE>` \| How the repository is linked. One of `target`, `touched`. Default: `target`. \|
1251
1252	```text
1253	The repository is the current one, or --repo OWNER/NAME. A work item with targets closes once it
1254	has landed in every one.
1255	Examples:
1256	g1t work link 12 --repo acme/api
1257	g1t work link 12 --role touched
1258	```
1259
1260	Calls [`link_work_item`](/reference/api/work-items/link-work-item/).
1261
1262	### g1t work unlink
1263
1264	Unlink a repository from a work item (never its origin).
1265
1266	```text
1267	g1t work unlink [OPTIONS] <NUMBER>
1268	```
1269
1270	\| Argument or flag \| \|
1271	\| --- \| --- \|
1272	\| `<NUMBER>` \| The work item's number. \|
1273
1274	Calls [`unlink_work_item`](/reference/api/work-items/unlink-work-item/).
1275
1276	### g1t work claim
1277
1278	Claim a work item: say you are working on it. Others are told, never stopped.
1279
1280	```text
1281	g1t work claim [OPTIONS] <NUMBER\|--title <TITLE>>
1282	```
1283
1284	\| Argument or flag \| \|
1285	\| --- \| --- \|
1286	\| `[NUMBER]` \| The work item's number. \|
1287	\| `--title <TITLE>` \| Open a new work item with this title and claim it; the current session is attached to it. \|
1288	\| `--body <BODY>` \| The new work item's description. \|
1289	\| `-n, --note <NOTE>` \| What you are doing about it. \|
1290	\| `--ttl <DURATION>` \| How long the claim lasts unless renewed: 30m, 2h (at most 4h). \|
1291
1292	```text
1293	With --title instead of a number, a new work item is opened (filed from the current repository)
1294	and claimed in one step, and the current session is attached to it: for work that became a change
1295	others should know about.
1296	Examples:
1297	g1t work claim 12 --note "Rewriting the retry loop"
1298	g1t work claim --title "Preview builds time out on large repositories"
1299	```
1300
1301	Calls [`claim_work_item`](/reference/api/work-items/claim-work-item/), [`claim_new_work_item`](/reference/api/work-items/claim-new-work-item/).
1302
1303	### g1t work release
1304
1305	Release your claim on a work item.
1306
1307	```text
1308	g1t work release [OPTIONS] <NUMBER>
1309	```
1310
1311	\| Argument or flag \| \|
1312	\| --- \| --- \|
1313	\| `<NUMBER>` \| \|
1314	\| `-r, --reason <REASON>` \| Why: done, blocked, abandoned... \|
1315
1316	Calls [`release_claim`](/reference/api/work-items/release-claim/).
1317
1318	### g1t work handoff
1319
1320	Hand a work item over to someone else, or to anyone.
1321
1322	```text
1323	g1t work handoff [OPTIONS] --note <NOTE> <NUMBER>
1324	```
1325
1326	\| Argument or flag \| \|
1327	\| --- \| --- \|
1328	\| `<NUMBER>` \| \|
1329	\| `--to <LOGIN>` \| Who takes it over; anyone when left out. \|
1330	\| `-n, --note <NOTE>` \| Where it stands and what is left, for whoever takes it. \|
1331
1332	Calls [`hand_off_work_item`](/reference/api/work-items/hand-off-work-item/).
1333
1334	### g1t work status
1335
1336	Active claims and sessions in the repository.
1337
1338	```text
1339	g1t work status [OPTIONS]
1340	```
1341
1342	Calls [`list_claims`](/reference/api/work-items/list-claims/), [`list_sessions`](/reference/api/sessions/list-sessions/).
1343
1344	### g1t work block
1345
1346	Say a work item waits on others: it is blocked by them.
1347
1348	```text
1349	g1t work block [OPTIONS] --by <NUMBER> <NUMBER>
1350	```
1351
1352	\| Argument or flag \| \|
1353	\| --- \| --- \|
1354	\| `<NUMBER>` \| The work item that waits. \|
1355	\| `--by <NUMBER>` \| The work item it waits on; repeat for more. \|
1356
1357	Calls [`get_work_item`](/reference/api/work-items/get-work-item/), [`update_work_item`](/reference/api/work-items/update-work-item/).
1358
1359	### g1t work unblock
1360
1361	Say a work item no longer waits on others.
1362
1363	```text
1364	g1t work unblock [OPTIONS] --by <NUMBER> <NUMBER>
1365	```
1366
1367	\| Argument or flag \| \|
1368	\| --- \| --- \|
1369	\| `<NUMBER>` \| The work item that waits. \|
1370	\| `--by <NUMBER>` \| The work item it waits on; repeat for more. \|
1371
1372	Calls [`get_work_item`](/reference/api/work-items/get-work-item/), [`update_work_item`](/reference/api/work-items/update-work-item/).
1373
1374	### g1t work events
1375
1376	The repository's events; --follow keeps printing them as they happen.
1377
1378	```text
1379	g1t work events [OPTIONS]
1380	```
1381
1382	\| Argument or flag \| \|
1383	\| --- \| --- \|
1384	\| `-f, --follow` \| Keep printing events as they happen, until stopped. \|
1385	\| `-t, --type <TYPE>` \| Only events of this type; repeat for more. \|
1386	\| `-i, --item <NUMBER>` \| Only events about this work item or pull request; repeat for more. \|
1387	\| `-s, --since <SINCE>` \| Only events since then: 15m, 2h, 1d, or a time like 2026-10-12T09:00:00Z. \|
1388	\| `--after <EVENT_ID>` \| Start after this event id, as a follow that stopped would resume. \|
1389	\| `-L, --limit <LIMIT>` \| How many past events to show first. Default: `20`. \|
1390
1391	```text
1392	Examples:
1393	g1t work events --follow --item 12
1394	g1t work events --follow --type integration.failed --type overlap.detected --json
1395	With --json, each event is one JSON object on a line of its own.
1396	```
1397
1398	Calls [`list_events`](/reference/api/repositories/list-events/).
1399
1400	### g1t work dispatch
1401
1402	Start work on a work item in a session on your own Claude, or print the Claude Code command for it.
1403
1404	```text
1405	g1t work dispatch [OPTIONS] <NUMBER\|--title <TITLE>>
1406	```
1407
1408	\| Argument or flag \| \|
1409	\| --- \| --- \|
1410	\| `[NUMBER]` \| The work item's number. \|
1411	\| `--title <TITLE>` \| Open a new work item with this title and work on it. \|
1412	\| `--body <BODY>` \| The new work item's description. \|
1413	\| `-i, --instruction <INSTRUCTION>` \| What to do beyond what the work item says. \|
1414	\| `-m, --mode <MODE>` \| What kind of work. One of `plan`, `implement`, `review`. \|
1415	\| `--handoff` \| Print the Claude Code command to run yourself; start nothing. \|
1416	\| `--managed` \| Start it on the workspace's Anthropic account, or fail. \|
1417
1418	```text
1419	With the workspace's Anthropic AI provider, a Claude Managed Agents session starts on that
1420	account and is recorded on g1t; otherwise (or with --handoff) this prints a `claude` command
1421	to run with g1t's plugin, whose session attaches to the work item as it starts.
1422	Examples:
1423	g1t work dispatch 12
1424	g1t work dispatch 12 --mode plan --instruction "Keep the old flag"
1425	g1t work dispatch --title "Add a healthcheck" --handoff
1426	```
1427
1428	Calls [`start_agent_session`](/reference/api/sessions/start-agent-session/).
1429
1430	## g1t why
1431
1432	Why a file or line is as it is: its commit, pull request, work item, decisions and sessions.
1433
1434	```text
1435	g1t why [OPTIONS] <TARGET>
1436	```
1437
1438	\| Argument or flag \| \|
1439	\| --- \| --- \|
1440	\| `<TARGET>` \| A file, or a line of it as PATH:LINE. \|
1441	\| `--ref <REF>` \| The branch, tag or commit to read it at; the default branch when left out. \|
1442
1443	Calls [`why`](/reference/api/decisions-and-why/why/).
1444
1445	## g1t attach
1446
1447	Upload images, such as a screenshot, to show in a work item, a pull request or a comment; prints their Markdown.
1448
1449	```text
1450	g1t attach [OPTIONS] <FILE>...
1451	```
1452
1453	\| Argument or flag \| \|
1454	\| --- \| --- \|
1455	\| `<FILE>` \| The files: PNG, JPEG, GIF or WebP, at most 10 MB each. \|
1456
1457	```text
1458	Prints each image's Markdown, ![name](url), to paste into a description or a comment; --json prints
1459	{ id, name, url, markdown, content_type, size } (a list for several files). The image is served from
1460	g1t's usercontent address, and anyone given that address can see it, even from a private repository.
1461	--attach FILE on g1t work new, g1t work comment, g1t pr create, g1t pr comment and g1t pr ready
1462	uploads and adds the Markdown for you:
1463	g1t attach preview.png
1464	g1t pr comment --body 'The preview, after the fix:' --attach preview.png
1465	```
1466
1467	Calls [`upload_attachment`](/reference/api/work-items/upload-attachment/), [`upload_work_item_attachment`](/reference/api/work-items/upload-work-item-attachment/).
1468
1469	## g1t api
1470
1471	Call any API operation or path, with your token.
1472
1473	```text
1474	g1t api [OPTIONS] [ENDPOINT]
1475	```
1476
1477	\| Argument or flag \| \|
1478	\| --- \| --- \|
1479	\| `[ENDPOINT]` \| An operation's name, or a path. \|
1480	\| `--list [QUERY]` \| List the operations, or those matching this word. \|
1481	\| `-X, --method <METHOD>` \| The HTTP method: GET unless fields are given, then POST. \|
1482	\| `-f, --raw-field <KEY=VALUE>` \| A string field, key=value. key[]=value adds to a list. \|
1483	\| `-F, --field <KEY=VALUE>` \| A typed field: true, false, null and numbers become JSON; @file reads a file. \|
1484	\| `-H, --header <KEY:VALUE>` \| A request header, key:value. \|
1485	\| `--input <FILE>` \| The request body, from a file or - for stdin. \|
1486	\| `--paginate` \| Follow next pages until there are none. \|
1487	\| `--slurp` \| With --paginate, put every page's items into one array. \|
1488	\| `-i, --include` \| Print the status line and headers too. \|
1489	\| `--silent` \| Print nothing on success. \|
1490
1491	```text
1492	ENDPOINT is an operation's name (list_work_items) or a path (/workspaces/{workspace}/work).
1493	{owner}, {name}, {repo} and {workspace} are filled in from the current repository,
1494	and an operation's other path parameters from -f/-F fields of the same name.
1495
1496	Examples:
1497	g1t api list_work_items -f state=closed
1498	g1t api /user --jq .username
1499	g1t api open_work_item -f title='Broken link' -f labels[]=docs
1500	g1t api list_workflow_runs --paginate --jq '.[].conclusion'
1501	g1t api --list work
1502	```
1503
1504	## g1t browse
1505
1506	Open the repository, a work item or a pull request in the browser.
1507
1508	```text
1509	g1t browse [OPTIONS] [TARGET]
1510	```
1511
1512	\| Argument or flag \| \|
1513	\| --- \| --- \|
1514	\| `[TARGET]` \| A work item or pull request number, a file path (path:line), or a commit. \|
1515	\| `-b, --branch <BRANCH>` \| The branch to show files on. \|
1516	\| `-s, --settings` \| \|
1517	\| `--work` \| The repository's work items: the workspace's Work list, filtered to it. \|
1518	\| `--pulls` \| \|
1519	\| `--actions` \| \|
1520	\| `-n, --no-browser` \| Print the address instead of opening it. \|
1521
1522	Calls [`resolve_ref`](/reference/api/work-items/resolve-ref/).
1523
1524	## g1t alias
1525
1526	Shortcuts for commands you type often.
1527
1528	### g1t alias set
1529
1530	Make an alias: g1t alias set co 'pr checkout'. Start it with ! to run it through the shell.
1531
1532	```text
1533	g1t alias set [OPTIONS] <NAME> <EXPANSION>
1534	```
1535
1536	\| Argument or flag \| \|
1537	\| --- \| --- \|
1538	\| `<NAME>` \| \|
1539	\| `<EXPANSION>` \| What it expands to. $1, $2... take the arguments after it. \|
1540
1541	### g1t alias list
1542
1543	List aliases.
1544
1545	```text
1546	g1t alias list [OPTIONS]
1547	```
1548
1549	### g1t alias delete
1550
1551	Delete an alias.
1552
1553	```text
1554	g1t alias delete [OPTIONS] <NAME>
1555	```
1556
1557	\| Argument or flag \| \|
1558	\| --- \| --- \|
1559	\| `<NAME>` \| \|
1560
1561	## g1t completion
1562
1563	Print a shell completion script.
1564
1565	```text
1566	g1t completion [OPTIONS] <SHELL>
1567	```
1568
1569	\| Argument or flag \| \|
1570	\| --- \| --- \|
1571	\| `<SHELL>` \| One of `bash`, `elvish`, `fish`, `powershell`, `zsh`. \|
1572
1573	## g1t push
1574
1575	Push a local container image to g1t's registry, in chunks.
1576
1577	```text
1578	g1t push [OPTIONS] [IMAGE]
1579	```
1580
1581	\| Argument or flag \| \|
1582	\| --- \| --- \|
1583	\| `[IMAGE]` \| The local image, [REGISTRY/]NAME[:TAG]. \|
1584	\| `--as <ADDRESS>` \| Where to push, when the image's own name is not an address on g1t.sh. The tag defaults to latest. \|
1585	\| `--chunk-size <SIZE>` \| How much of a layer each request carries: 5MB to 95MB. Default: `90MB`. \|
1586	\| `--token-stdin` \| Read the g1t token from stdin. \|
1587	\| `--archive <FILE>` \| Push a tarball `docker save` wrote, instead of asking docker for the image. \|
1588
1589	```text
1590	The token is the first of: --token-stdin, G1T_TOKEN, the account `g1t auth login`
1591	signed in for the registry's host, or what `docker login g1t.sh` stored.
1592	```
1593
1594	## g1t upgrade
1595
1596	Update g1t to the newest release, checked against g1t's release key.
1597
1598	```text
1599	g1t upgrade [OPTIONS]
1600	```
1601
1602	\| Argument or flag \| \|
1603	\| --- \| --- \|
1604	\| `--check` \| Only say whether a newer release is out. \|
1605
1606	```text
1607	Downloads the newest release for this machine from g1t.sh, checks its signature and SHA-256, and puts it
1608	where this g1t is. In a terminal, g1t also says once a day when a newer release is out;
1609	G1T_NO_UPDATE_NOTIFIER=1 turns that off.
1610	```