Skip to content
Sign up

flagon-io/g1t

public
00

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

g1t.sh
gitagentscloudflarerustforgemcp
1,177 linesCodeBlameRaw
1---
2title: CLI commands
3description: 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
8Every 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
10to the API names the operations it calls, which link to the
11[API reference](/reference/api/); [`g1t api`](#g1t-api) calls any other.
12
13## Flags every command takes
14
15| Flag | |
16| --- | --- |
17| `-R, --repo <[HOST/]OWNER/NAME>` | The repository, as [HOST/]OWNER/NAME, instead of the current directory's. |
18| `--hostname <HOST>` | The g1t host, such as g1t.sh or git.example.com. |
19| `--json [FIELDS]` | Print JSON: every field, or only the comma-separated FIELDS. |
20| `--jq <EXPRESSION>` | Run a jq expression over the JSON and print what it gives. |
21
22## g1t auth
23
24Sign in, sign out, and set git up to use g1t's credentials.
25
26### g1t auth login
27
28Sign in to a g1t host.
29
30```text
31g1t 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
42Without --with-token, g1t shows a code and a link; approve it in the browser, signed in.
43With --with-token, the token is read from stdin:
44 g1t auth login --with-token < token.txt
45```
46
47Calls [`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
51Sign out of an account on a host.
52
53```text
54g1t 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
63Show which accounts are signed in, and whether their tokens work.
64
65```text
66g1t auth status [OPTIONS]
67```
68
69| Argument or flag | |
70| --- | --- |
71| `--show-token` | Print each token too. |
72
73Calls [`whoami`](/reference/api/accounts/whoami/).
74
75### g1t auth token
76
77Print the token in use, for another program.
78
79```text
80g1t 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
89Make another signed-in account on a host the active one.
90
91```text
92g1t 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
101Make git use g1t's credentials for pushing and fetching over HTTPS.
102
103```text
104g1t 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
113Repositories: view, clone, create, list.
114
115### g1t repo view
116
117Show a repository.
118
119```text
120g1t 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
128Calls [`get_repo`](/reference/api/repositories/get-repo/).
129
130### g1t repo clone
131
132Clone a repository.
133
134```text
135g1t 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
144Calls [`whoami`](/reference/api/accounts/whoami/).
145
146### g1t repo create
147
148Make a repository.
149
150```text
151g1t 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>` | |
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
164Calls [`create_repo`](/reference/api/repositories/create-repo/).
165
166### g1t repo list
167
168List repositories you can see.
169
170```text
171g1t repo list [OPTIONS] [WORKSPACE]
172```
173
174| Argument or flag | |
175| --- | --- |
176| `[WORKSPACE]` | Only this workspace's. |
177| `-q, --query <QUERY>` | Only those whose name or description holds this. |
178| `-L, --limit <LIMIT>` | Default: `20`. |
179
180Calls [`list_repos`](/reference/api/repositories/list-repos/).
181
182## g1t issue
183
184Issues: list, view, create, comment, close, reopen, edit.
185
186### g1t issue list
187
188List issues.
189
190```text
191g1t issue list [OPTIONS]
192```
193
194| Argument or flag | |
195| --- | --- |
196| `-s, --state <STATE>` | One of `open`, `closed`, `all`. Default: `open`. |
197| `-l, --label <LABEL>` | Only issues with this label. |
198| `-m, --milestone <MILESTONE>` | Only issues in the milestone of this number. |
199| `-a, --assignee <ASSIGNEE>` | Only issues assigned to this person (@me for you). |
200| `-A, --author <AUTHOR>` | Only issues opened by this person (@me for you). |
201| `-L, --limit <LIMIT>` | Default: `20`. |
202
203Calls [`list_issues`](/reference/api/issues/list-issues/).
204
205### g1t issue view
206
207Show an issue, with its comments.
208
209```text
210g1t issue view [OPTIONS] <NUMBER>
211```
212
213| Argument or flag | |
214| --- | --- |
215| `<NUMBER>` | The issue's number. |
216| `-c, --comments` | Show its comments too. |
217| `-w, --web` | Open it in the browser. |
218
219Calls [`get_issue`](/reference/api/issues/get-issue/).
220
221### g1t issue create
222
223Open an issue.
224
225```text
226g1t issue create [OPTIONS]
227```
228
229| Argument or flag | |
230| --- | --- |
231| `-t, --title <TITLE>` | |
232| `-b, --body <BODY>` | The text. Markdown. |
233| `-F, --body-file <FILE>` | Read the text from a file, or - for stdin. |
234| `-l, --label <LABEL>` | A label; repeat for more. |
235| `-a, --assignee <ASSIGNEE>` | Someone to assign; repeat for more (@me for you). |
236| `-m, --milestone <MILESTONE>` | A milestone's number. |
237| `-w, --web` | Open the new-issue page in the browser instead. |
238
239Calls [`create_issue`](/reference/api/issues/create-issue/), [`update_issue`](/reference/api/issues/update-issue/).
240
241### g1t issue comment
242
243Comment on an issue.
244
245```text
246g1t issue comment [OPTIONS] [NUMBER]
247```
248
249| Argument or flag | |
250| --- | --- |
251| `[NUMBER]` | The number; for a pull request, the current branch's when left out. |
252| `-b, --body <BODY>` | The text. Markdown. |
253| `-F, --body-file <FILE>` | Read the text from a file, or - for stdin. |
254
255Calls [`add_comment`](/reference/api/issues/add-comment/).
256
257### g1t issue close
258
259Close an issue.
260
261```text
262g1t issue close [OPTIONS] <NUMBER>
263```
264
265| Argument or flag | |
266| --- | --- |
267| `<NUMBER>` | |
268| `-r, --reason <REASON>` | One of `completed`, `not-planned`. |
269| `-c, --comment <COMMENT>` | Leave a comment as it closes. |
270
271Calls [`close_issue`](/reference/api/issues/close-issue/), [`add_comment`](/reference/api/issues/add-comment/).
272
273### g1t issue reopen
274
275Reopen an issue.
276
277```text
278g1t issue reopen [OPTIONS] <NUMBER>
279```
280
281| Argument or flag | |
282| --- | --- |
283| `<NUMBER>` | |
284| `-c, --comment <COMMENT>` | Leave a comment as it reopens. |
285
286Calls [`reopen_issue`](/reference/api/issues/reopen-issue/), [`add_comment`](/reference/api/issues/add-comment/).
287
288### g1t issue edit
289
290Change an issue's title, body, labels, assignees or milestone.
291
292```text
293g1t issue edit [OPTIONS] <NUMBER>
294```
295
296| Argument or flag | |
297| --- | --- |
298| `<NUMBER>` | |
299| `-t, --title <TITLE>` | |
300| `-b, --body <BODY>` | The text. Markdown. |
301| `-F, --body-file <FILE>` | Read the text from a file, or - for stdin. |
302| `--add-label <LABEL>` | |
303| `--remove-label <LABEL>` | |
304| `--add-assignee <LOGIN>` | |
305| `--remove-assignee <LOGIN>` | |
306| `-m, --milestone <MILESTONE>` | A milestone's number. |
307| `--remove-milestone` | Take it out of its milestone. |
308
309Calls [`update_issue`](/reference/api/issues/update-issue/), [`get_issue`](/reference/api/issues/get-issue/).
310
311## g1t pr
312
313Pull requests: list, view, create, check out, diff, checks, review, merge.
314
315### g1t pr list
316
317List pull requests.
318
319```text
320g1t pr list [OPTIONS]
321```
322
323| Argument or flag | |
324| --- | --- |
325| `-s, --state <STATE>` | One of `open`, `closed`, `merged`, `all`. Default: `open`. |
326| `-B, --base <BASE>` | Only those merging into this branch. |
327| `-l, --label <LABEL>` | |
328| `-A, --author <AUTHOR>` | Only those opened by this person (@me for you). |
329| `-d, --draft` | Only drafts. |
330| `-L, --limit <LIMIT>` | Default: `20`. |
331
332Calls [`list_pull_requests`](/reference/api/pull-requests/list-pull-requests/).
333
334### g1t pr view
335
336Show a pull request.
337
338```text
339g1t pr view [OPTIONS] [NUMBER]
340```
341
342| Argument or flag | |
343| --- | --- |
344| `[NUMBER]` | The number; the current branch's when left out. |
345| `-c, --comments` | |
346| `-w, --web` | |
347
348Calls [`get_pull_request`](/reference/api/pull-requests/get-pull-request/), [`list_pull_requests`](/reference/api/pull-requests/list-pull-requests/).
349
350### g1t pr create
351
352Open a pull request from a branch, or start one for an issue.
353
354```text
355g1t pr create [OPTIONS]
356```
357
358| Argument or flag | |
359| --- | --- |
360| `-t, --title <TITLE>` | |
361| `-b, --body <BODY>` | The text. Markdown. |
362| `-F, --body-file <FILE>` | Read the text from a file, or - for stdin. |
363| `-B, --base <BASE>` | The branch to merge into; the default branch when left out. |
364| `-H, --head <HEAD>` | The branch with the changes; the current one when left out. |
365| `-i, --issue <ISSUE>` | The issue it is for. Without a branch, starts a draft in a working copy of its own. |
366| `-f, --fill` | Take the title and body from the branch's commits. |
367| `-d, --draft` | Open it as a draft. |
368| `--no-push` | Do not push the branch first. |
369
370Calls [`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/).
371
372### g1t pr checkout
373
374Check a pull request's changes out locally.
375
376```text
377g1t pr checkout [OPTIONS] <NUMBER>
378```
379
380| Argument or flag | |
381| --- | --- |
382| `<NUMBER>` | |
383| `-b, --branch <BRANCH>` | The local branch's name; pr-NUMBER when left out. |
384| `-f, --force` | Reset the local branch to the pull request's head even if it has other commits. |
385
386Calls [`get_pull_request`](/reference/api/pull-requests/get-pull-request/).
387
388### g1t pr diff
389
390Show a pull request's changes as a diff.
391
392```text
393g1t pr diff [OPTIONS] [NUMBER]
394```
395
396| Argument or flag | |
397| --- | --- |
398| `[NUMBER]` | |
399| `--name-only` | Only the changed files' names. |
400| `--color <COLOR>` | Color: auto, always or never. Default: `auto`. |
401
402Calls [`get_pull_request_changes`](/reference/api/pull-requests/get-pull-request-changes/).
403
404### g1t pr checks
405
406Show a pull request's checks; --watch waits for them.
407
408```text
409g1t pr checks [OPTIONS] [NUMBER]
410```
411
412| Argument or flag | |
413| --- | --- |
414| `[NUMBER]` | |
415| `-w, --watch` | Wait until every check has finished. |
416| `--fail-fast` | With --watch, stop at the first failing check. |
417| `-i, --interval <INTERVAL>` | Seconds between looks, with --watch. Default: `10`. |
418
419Calls [`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/).
420
421### g1t pr review
422
423Approve a pull request, or ask for changes.
424
425```text
426g1t pr review [OPTIONS] <--approve|--request-changes|--comment> [NUMBER]
427```
428
429| Argument or flag | |
430| --- | --- |
431| `[NUMBER]` | |
432| `-a, --approve` | |
433| `-r, --request-changes` | |
434| `-c, --comment` | Comment without approving or asking for changes. |
435| `-b, --body <BODY>` | The text. Markdown. |
436| `-F, --body-file <FILE>` | Read the text from a file, or - for stdin. |
437
438Calls [`review_pull_request`](/reference/api/pull-requests/review-pull-request/), [`add_comment`](/reference/api/issues/add-comment/).
439
440### g1t pr merge
441
442Merge a pull request.
443
444```text
445g1t pr merge [OPTIONS] [NUMBER]
446```
447
448| Argument or flag | |
449| --- | --- |
450| `[NUMBER]` | |
451| `--keep-issue-open` | Leave the issue it is for open. |
452| `--admin` | Merge past failing required checks and rules (needs the Admin role). |
453| `-d, --delete-branch` | Delete the local and remote branch afterwards. |
454
455Calls [`merge_pull_request`](/reference/api/pull-requests/merge-pull-request/), [`delete_branch`](/reference/api/repositories/delete-branch/).
456
457### g1t pr ready
458
459Mark a draft ready for review, or turn it back into a draft.
460
461```text
462g1t pr ready [OPTIONS] [NUMBER]
463```
464
465| Argument or flag | |
466| --- | --- |
467| `[NUMBER]` | |
468| `-s, --summary <SUMMARY>` | What changed and why; it becomes the description. The current one when left out. |
469| `--undo` | Turn it back into a draft. |
470
471Calls [`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/).
472
473### g1t pr comment
474
475Comment on a pull request.
476
477```text
478g1t pr comment [OPTIONS] [NUMBER]
479```
480
481| Argument or flag | |
482| --- | --- |
483| `[NUMBER]` | The number; for a pull request, the current branch's when left out. |
484| `-b, --body <BODY>` | The text. Markdown. |
485| `-F, --body-file <FILE>` | Read the text from a file, or - for stdin. |
486
487Calls [`add_comment`](/reference/api/issues/add-comment/).
488
489### g1t pr close
490
491Close a pull request without merging it.
492
493```text
494g1t pr close [OPTIONS] [NUMBER]
495```
496
497| Argument or flag | |
498| --- | --- |
499| `[NUMBER]` | The number; the current branch's when left out. |
500
501Calls [`close_pull_request`](/reference/api/pull-requests/close-pull-request/).
502
503### g1t pr reopen
504
505Reopen a closed pull request.
506
507```text
508g1t pr reopen [OPTIONS] [NUMBER]
509```
510
511| Argument or flag | |
512| --- | --- |
513| `[NUMBER]` | The number; the current branch's when left out. |
514
515Calls [`reopen_pull_request`](/reference/api/pull-requests/reopen-pull-request/).
516
517## g1t run
518
519Workflow runs: list, view, watch, logs, rerun, cancel.
520
521### g1t run list
522
523List workflow runs, newest first.
524
525```text
526g1t run list [OPTIONS]
527```
528
529| Argument or flag | |
530| --- | --- |
531| `-w, --workflow <WORKFLOW>` | Only this workflow's: its file name or id. |
532| `-b, --branch <BRANCH>` | |
533| `-e, --event <EVENT>` | Only runs for this event: push, pull_request, schedule... |
534| `-c, --commit <COMMIT>` | Only runs of this commit. |
535| `--pr <PR>` | Only runs for this pull request. |
536| `-L, --limit <LIMIT>` | Default: `20`. |
537
538Calls [`list_workflow_runs`](/reference/api/actions/list-workflow-runs/).
539
540### g1t run view
541
542Show a run's jobs and steps.
543
544```text
545g1t run view [OPTIONS] [RUN]
546```
547
548| Argument or flag | |
549| --- | --- |
550| `[RUN]` | |
551| `-j, --job <JOB>` | Show this job's steps only. |
552| `--log` | Print the log too. |
553| `--log-failed` | Print the failing steps' logs too. |
554| `-w, --web` | |
555| `--exit-status` | Exit 1 when the run failed. |
556
557Calls [`get_workflow_run`](/reference/api/actions/get-workflow-run/), [`get_job_logs`](/reference/api/actions/get-job-logs/).
558
559### g1t run watch
560
561Follow a run until it finishes; exits 1 if it fails.
562
563```text
564g1t run watch [OPTIONS] [RUN]
565```
566
567| Argument or flag | |
568| --- | --- |
569| `[RUN]` | |
570| `-i, --interval <INTERVAL>` | Seconds between looks. Default: `3`. |
571
572Calls [`get_workflow_run`](/reference/api/actions/get-workflow-run/).
573
574### g1t run logs
575
576Print a run's logs; --failed prints only the failing steps' tails.
577
578```text
579g1t run logs [OPTIONS] [RUN]
580```
581
582| Argument or flag | |
583| --- | --- |
584| `[RUN]` | |
585| `-j, --job <JOB>` | Only this job's (its id, key or name). |
586| `-f, --failed` | Only the failing steps, and only their last lines. |
587| `-n, --tail <TAIL>` | How many lines of each failing step to print, with --failed. Default: `60`. |
588
589Calls [`get_workflow_run`](/reference/api/actions/get-workflow-run/), [`get_job_logs`](/reference/api/actions/get-job-logs/).
590
591### g1t run rerun
592
593Run a run again: all of it, its failed jobs, or one job.
594
595```text
596g1t run rerun [OPTIONS] [RUN]
597```
598
599| Argument or flag | |
600| --- | --- |
601| `[RUN]` | |
602| `--failed` | Only the jobs that failed. |
603| `-j, --job <JOB>` | Only this job (its id). |
604| `-d, --debug` | With debug logging. |
605
606Calls [`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/).
607
608### g1t run cancel
609
610Cancel a run.
611
612```text
613g1t run cancel [OPTIONS] [RUN]
614```
615
616| Argument or flag | |
617| --- | --- |
618| `[RUN]` | The run's id (run_…) or number; the current branch's latest when left out. |
619
620Calls [`cancel_workflow_run`](/reference/api/actions/cancel-workflow-run/).
621
622## g1t secret
623
624Secrets for workflows and deployments, a repository's or a workspace's.
625
626### g1t secret list
627
628List secrets' names (never their values).
629
630```text
631g1t secret list [OPTIONS]
632```
633
634| Argument or flag | |
635| --- | --- |
636| `-w, --workspace <WORKSPACE>` | A workspace's secrets instead of the repository's. |
637| `-e, --env <ENVIRONMENT>` | Only the value for this environment (production, preview...). |
638
639Calls [`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/).
640
641### g1t secret set
642
643Set a secret. The value is read from stdin when not given.
644
645```text
646g1t secret set [OPTIONS] <NAME>
647```
648
649| Argument or flag | |
650| --- | --- |
651| `<NAME>` | The secret's name; uppercased. |
652| `-b, --body <BODY>` | The value. Read from stdin when left out, so it stays out of your shell's history. |
653| `-w, --workspace <WORKSPACE>` | A workspace's secrets instead of the repository's. |
654| `-e, --env <ENVIRONMENT>` | Only the value for this environment (production, preview...). |
655| `--available-to <WHO>` | Who can read it: workflows, deployments, or both (repeat). |
656| `--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. |
657| `--note <NOTE>` | A note for whoever reads the list. |
658
659Calls [`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/).
660
661### g1t secret delete
662
663Delete a secret.
664
665```text
666g1t secret delete [OPTIONS] <NAME>
667```
668
669| Argument or flag | |
670| --- | --- |
671| `<NAME>` | |
672| `-w, --workspace <WORKSPACE>` | A workspace's secrets instead of the repository's. |
673| `-e, --env <ENVIRONMENT>` | Only the value for this environment (production, preview...). |
674
675Calls [`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/).
676
677## g1t cache
678
679The repository's actions/cache entries: list, usage, delete.
680
681### g1t cache list
682
683List the repository's cache entries, least recently used last.
684
685```text
686g1t cache list [OPTIONS]
687```
688
689| Argument or flag | |
690| --- | --- |
691| `-k, --key <KEY>` | Only entries whose key starts with this. |
692| `-g, --ref <REF>` | Only entries saved by this ref's runs, e.g. refs/heads/main. |
693| `-S, --sort <SORT>` | One of `last-accessed-at`, `created-at`, `size-in-bytes`. Default: `last-accessed-at`. |
694| `-O, --order <ORDER>` | One of `asc`, `desc`. Default: `desc`. |
695| `-L, --limit <LIMIT>` | Default: `30`. |
696
697Calls [`list_caches`](/reference/api/actions/list-caches/).
698
699### g1t cache usage
700
701What the repository's cache entries hold, against its quota.
702
703```text
704g1t cache usage [OPTIONS]
705```
706
707Calls [`get_cache_usage`](/reference/api/actions/get-cache-usage/).
708
709### g1t cache delete
710
711Delete cache entries: one by its id, or every entry with a key.
712
713```text
714g1t cache delete [OPTIONS] <ENTRY>
715```
716
717| Argument or flag | |
718| --- | --- |
719| `<ENTRY>` | An entry's id (a number, from `g1t cache list`), or a key: every entry with exactly that key. |
720| `-g, --ref <REF>` | With a key, only the entries this ref's runs saved. |
721
722Calls [`delete_cache`](/reference/api/actions/delete-cache/), [`delete_caches_by_key`](/reference/api/actions/delete-caches-by-key/).
723
724## g1t deploy
725
726Deployments: list and view.
727
728### g1t deploy list
729
730List deployments, newest first.
731
732```text
733g1t deploy list [OPTIONS]
734```
735
736| Argument or flag | |
737| --- | --- |
738| `-e, --env <ENV>` | |
739| `-s, --state <STATE>` | queued, in_progress, success, failure, error or inactive. |
740| `--source <SOURCE>` | api, actions or g1t_page. |
741| `-L, --limit <LIMIT>` | Default: `20`. |
742
743Calls [`list_deployments`](/reference/api/deployments/list-deployments/).
744
745### g1t deploy view
746
747Show a deployment and its statuses.
748
749```text
750g1t deploy view [OPTIONS] <ID>
751```
752
753| Argument or flag | |
754| --- | --- |
755| `<ID>` | |
756| `-w, --web` | |
757
758Calls [`get_deployment`](/reference/api/deployments/get-deployment/).
759
760## g1t logs
761
762A project's logs and errors.
763
764```text
765g1t logs [OPTIONS]
766```
767
768| Argument or flag | |
769| --- | --- |
770| `-p, --project <PROJECT>` | The project; the current repository's when left out. |
771| `--errors` | Grouped errors instead of log lines. |
772| `-q, --query <QUERY>` | Lines holding all of these words, or a "quoted phrase". |
773| `-l, --level <LEVEL>` | Levels: trace, debug, info, warn, error, fatal (comma-separated). |
774| `-e, --env <ENV>` | |
775| `--service <SERVICE>` | |
776| `-s, --since <SINCE>` | How far back: 15m, 2h, 1d, or a time like 2026-10-12T09:00:00Z. |
777| `--state <STATE>` | With --errors: open, resolved or ignored. |
778| `-f, --follow` | Keep printing new lines as they come. |
779| `-L, --limit <LIMIT>` | Default: `50`. |
780
781Calls [`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/).
782
783## g1t status
784
785What needs you: your pull requests, reviews asked of you, your issues, failing checks, and your sessions and claims here.
786
787```text
788g1t status [OPTIONS]
789```
790
791Calls [`search`](/reference/api/search/search/), [`list_notifications`](/reference/api/notifications/list-notifications/), [`get_pull_request`](/reference/api/pull-requests/get-pull-request/), [`list_sessions`](/reference/api/sessions/list-sessions/), [`list_claims`](/reference/api/claims-and-work/list-claims/).
792
793## g1t session
794
795Sessions: one run of an agent's harness, recorded as it works.
796
797### g1t session start
798
799Start a session and remember it for this working copy. Prints its id.
800
801```text
802g1t session start [OPTIONS]
803```
804
805| Argument or flag | |
806| --- | --- |
807| `-i, --issue <ISSUE>` | The issue it works on. |
808| `-p, --pull <PULL>` | The pull request it works on. |
809| `--harness <HARNESS>` | The harness running it. One of `claude_code`, `codex`, `cursor`, `copilot`, `other`. Default: `other`. |
810| `--harness-session-id <ID>` | The harness's own id for the run, which makes starting again return the same session. |
811| `-t, --title <TITLE>` | |
812| `-b, --branch <BRANCH>` | The branch it works on; the current one when left out. |
813
814```text
815The id is kept in .git/g1t/session (each worktree has its own); G1T_SESSION overrides it.
816Starting again with the same --harness-session-id returns the same session.
817```
818
819Calls [`start_session`](/reference/api/sessions/start-session/).
820
821### g1t session heartbeat
822
823Say the current session is still working; renews its claims.
824
825```text
826g1t session heartbeat [OPTIONS]
827```
828
829Calls [`update_session`](/reference/api/sessions/update-session/).
830
831### g1t session log
832
833Record a note, prompt or message in the current session.
834
835```text
836g1t session log [OPTIONS] <TEXT>
837```
838
839| Argument or flag | |
840| --- | --- |
841| `<TEXT>` | What to record; - reads it from stdin. |
842| `-k, --kind <KIND>` | One of `note`, `prompt`, `message`, `tool-call`. Default: `note`. |
843| `--tool <TOOL>` | The tool, for a tool_call. |
844| `--key <KEY>` | A key that makes recording it again do nothing. |
845
846Calls [`record_session_entries`](/reference/api/sessions/record-session-entries/).
847
848### g1t session attach
849
850Attach the current session to an issue, a pull request or a branch.
851
852```text
853g1t session attach [OPTIONS] <--issue <ISSUE>|--pull <PULL>|--branch <BRANCH>|--head-commit <SHA>>
854```
855
856| Argument or flag | |
857| --- | --- |
858| `-i, --issue <ISSUE>` | |
859| `-p, --pull <PULL>` | |
860| `-b, --branch <BRANCH>` | |
861| `--head-commit <SHA>` | The commit it pushed last. |
862
863Calls [`update_session`](/reference/api/sessions/update-session/).
864
865### g1t session end
866
867End the current session.
868
869```text
870g1t session end [OPTIONS]
871```
872
873| Argument or flag | |
874| --- | --- |
875| `-r, --reason <REASON>` | Why it ended: done, abandoned, handed_off... |
876
877Calls [`end_session`](/reference/api/sessions/end-session/).
878
879### g1t session list
880
881List the repository's sessions.
882
883```text
884g1t session list [OPTIONS]
885```
886
887| Argument or flag | |
888| --- | --- |
889| `-s, --state <STATE>` | Only sessions in this state. One of `active`, `idle`, `ended`. |
890| `-i, --issue <ISSUE>` | |
891| `-p, --pull <PULL>` | |
892| `-L, --limit <LIMIT>` | Default: `20`. |
893
894Calls [`list_sessions`](/reference/api/sessions/list-sessions/).
895
896### g1t session view
897
898Show a session and what it recorded; the current one when left out.
899
900```text
901g1t session view [OPTIONS] [ID]
902```
903
904| Argument or flag | |
905| --- | --- |
906| `[ID]` | The session's id (ses_…); the current one when left out. |
907
908Calls [`get_session`](/reference/api/sessions/get-session/).
909
910## g1t work
911
912Coordinate work on issues: context, claims, hand-offs, dependencies, events.
913
914### g1t work context
915
916Everything about an issue's work: claims, sessions, pull requests, dependencies, decisions.
917
918```text
919g1t work context [OPTIONS] <NUMBER>
920```
921
922| Argument or flag | |
923| --- | --- |
924| `<NUMBER>` | The issue's number. |
925
926Calls [`get_work`](/reference/api/claims-and-work/get-work/).
927
928### g1t work claim
929
930Claim an issue: say you are working on it. Others are told, never stopped.
931
932```text
933g1t work claim [OPTIONS] <NUMBER>
934```
935
936| Argument or flag | |
937| --- | --- |
938| `<NUMBER>` | The issue's number. |
939| `-n, --note <NOTE>` | What you are doing about it. |
940| `--ttl <DURATION>` | How long the claim lasts unless renewed: 30m, 2h (at most 4h). |
941
942Calls [`claim_issue`](/reference/api/claims-and-work/claim-issue/).
943
944### g1t work release
945
946Release your claim on an issue.
947
948```text
949g1t work release [OPTIONS] <NUMBER>
950```
951
952| Argument or flag | |
953| --- | --- |
954| `<NUMBER>` | |
955| `-r, --reason <REASON>` | Why: done, blocked, abandoned... |
956
957Calls [`release_claim`](/reference/api/claims-and-work/release-claim/).
958
959### g1t work handoff
960
961Hand an issue over to someone else, or to anyone.
962
963```text
964g1t work handoff [OPTIONS] --note <NOTE> <NUMBER>
965```
966
967| Argument or flag | |
968| --- | --- |
969| `<NUMBER>` | |
970| `--to <LOGIN>` | Who takes it over; anyone when left out. |
971| `-n, --note <NOTE>` | Where it stands and what is left, for whoever takes it. |
972
973Calls [`hand_off_issue`](/reference/api/claims-and-work/hand-off-issue/).
974
975### g1t work list
976
977Active claims and sessions in the repository.
978
979```text
980g1t work list [OPTIONS]
981```
982
983Calls [`list_claims`](/reference/api/claims-and-work/list-claims/), [`list_sessions`](/reference/api/sessions/list-sessions/).
984
985### g1t work block
986
987Say an issue waits on others: it is blocked by them.
988
989```text
990g1t work block [OPTIONS] --by <NUMBER> <NUMBER>
991```
992
993| Argument or flag | |
994| --- | --- |
995| `<NUMBER>` | The issue that waits. |
996| `--by <NUMBER>` | The issue it waits on; repeat for more. |
997
998Calls [`get_issue`](/reference/api/issues/get-issue/), [`update_issue`](/reference/api/issues/update-issue/).
999
1000### g1t work unblock
1001
1002Say an issue no longer waits on others.
1003
1004```text
1005g1t work unblock [OPTIONS] --by <NUMBER> <NUMBER>
1006```
1007
1008| Argument or flag | |
1009| --- | --- |
1010| `<NUMBER>` | The issue that waits. |
1011| `--by <NUMBER>` | The issue it waits on; repeat for more. |
1012
1013Calls [`get_issue`](/reference/api/issues/get-issue/), [`update_issue`](/reference/api/issues/update-issue/).
1014
1015### g1t work events
1016
1017The repository's events; --follow keeps printing them as they happen.
1018
1019```text
1020g1t work events [OPTIONS]
1021```
1022
1023| Argument or flag | |
1024| --- | --- |
1025| `-f, --follow` | Keep printing events as they happen, until stopped. |
1026| `-t, --type <TYPE>` | Only events of this type; repeat for more. |
1027| `-i, --issue <NUMBER>` | Only events about this issue or pull request; repeat for more. |
1028| `-s, --since <SINCE>` | Only events since then: 15m, 2h, 1d, or a time like 2026-10-12T09:00:00Z. |
1029| `--after <EVENT_ID>` | Start after this event id, as a follow that stopped would resume. |
1030| `-L, --limit <LIMIT>` | How many past events to show first. Default: `20`. |
1031
1032```text
1033Examples:
1034 g1t work events --follow --issue 12
1035 g1t work events --follow --type integration.failed --type overlap.detected --json
1036With --json, each event is one JSON object on a line of its own.
1037```
1038
1039Calls [`list_events`](/reference/api/repositories/list-events/).
1040
1041## g1t why
1042
1043Why a file or line is as it is: its commit, pull request, issue, decisions and sessions.
1044
1045```text
1046g1t why [OPTIONS] <TARGET>
1047```
1048
1049| Argument or flag | |
1050| --- | --- |
1051| `<TARGET>` | A file, or a line of it as PATH:LINE. |
1052| `--ref <REF>` | The branch, tag or commit to read it at; the default branch when left out. |
1053
1054Calls [`why`](/reference/api/decisions-and-why/why/).
1055
1056## g1t api
1057
1058Call any API operation or path, with your token.
1059
1060```text
1061g1t api [OPTIONS] [ENDPOINT]
1062```
1063
1064| Argument or flag | |
1065| --- | --- |
1066| `[ENDPOINT]` | An operation's name, or a path. |
1067| `--list [QUERY]` | List the operations, or those matching this word. |
1068| `-X, --method <METHOD>` | The HTTP method: GET unless fields are given, then POST. |
1069| `-f, --raw-field <KEY=VALUE>` | A string field, key=value. key[]=value adds to a list. |
1070| `-F, --field <KEY=VALUE>` | A typed field: true, false, null and numbers become JSON; @file reads a file. |
1071| `-H, --header <KEY:VALUE>` | A request header, key:value. |
1072| `--input <FILE>` | The request body, from a file or - for stdin. |
1073| `--paginate` | Follow next pages until there are none. |
1074| `--slurp` | With --paginate, put every page's items into one array. |
1075| `-i, --include` | Print the status line and headers too. |
1076| `--silent` | Print nothing on success. |
1077
1078```text
1079ENDPOINT is an operation's name (list_issues) or a path (/repos/{owner}/{name}/issues).
1080{owner}, {name}, {repo} and {workspace} are filled in from the current repository,
1081and an operation's other path parameters from -f/-F fields of the same name.
1082
1083Examples:
1084 g1t api list_issues -f state=closed
1085 g1t api /user --jq .username
1086 g1t api create_issue -f title='Broken link' -f labels[]=docs
1087 g1t api list_workflow_runs --paginate --jq '.[].conclusion'
1088 g1t api --list issue
1089```
1090
1091## g1t browse
1092
1093Open the repository, an issue or a pull request in the browser.
1094
1095```text
1096g1t browse [OPTIONS] [TARGET]
1097```
1098
1099| Argument or flag | |
1100| --- | --- |
1101| `[TARGET]` | An issue or pull request number, a file path (path:line), or a commit. |
1102| `-b, --branch <BRANCH>` | The branch to show files on. |
1103| `-s, --settings` | |
1104| `--issues` | |
1105| `--pulls` | |
1106| `--actions` | |
1107| `-n, --no-browser` | Print the address instead of opening it. |
1108
1109## g1t alias
1110
1111Shortcuts for commands you type often.
1112
1113### g1t alias set
1114
1115Make an alias: g1t alias set co 'pr checkout'. Start it with ! to run it through the shell.
1116
1117```text
1118g1t alias set [OPTIONS] <NAME> <EXPANSION>
1119```
1120
1121| Argument or flag | |
1122| --- | --- |
1123| `<NAME>` | |
1124| `<EXPANSION>` | What it expands to. $1, $2... take the arguments after it. |
1125
1126### g1t alias list
1127
1128List aliases.
1129
1130```text
1131g1t alias list [OPTIONS]
1132```
1133
1134### g1t alias delete
1135
1136Delete an alias.
1137
1138```text
1139g1t alias delete [OPTIONS] <NAME>
1140```
1141
1142| Argument or flag | |
1143| --- | --- |
1144| `<NAME>` | |
1145
1146## g1t completion
1147
1148Print a shell completion script.
1149
1150```text
1151g1t completion [OPTIONS] <SHELL>
1152```
1153
1154| Argument or flag | |
1155| --- | --- |
1156| `<SHELL>` | One of `bash`, `elvish`, `fish`, `powershell`, `zsh`. |
1157
1158## g1t push
1159
1160Push a local container image to g1t's registry, in chunks.
1161
1162```text
1163g1t push [OPTIONS] [IMAGE]
1164```
1165
1166| Argument or flag | |
1167| --- | --- |
1168| `[IMAGE]` | The local image, [REGISTRY/]NAME[:TAG]. |
1169| `--as <ADDRESS>` | Where to push, when the image's own name is not an address on g1t.sh. The tag defaults to latest. |
1170| `--chunk-size <SIZE>` | How much of a layer each request carries: 5MB to 95MB. Default: `90MB`. |
1171| `--token-stdin` | Read the g1t token from stdin. |
1172| `--archive <FILE>` | Push a tarball `docker save` wrote, instead of asking docker for the image. |
1173
1174```text
1175The token is the first of: --token-stdin, G1T_TOKEN, the account `g1t auth login`
1176signed in for the registry's host, or what `docker login g1t.sh` stored.
1177```