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,268 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 workflow
623
624Workflows in .g1t/workflows: list, view, run, enable, disable.
625
626### g1t workflow list
627
628List the workflows in .g1t/workflows, with whether each is on.
629
630```text
631g1t workflow list [OPTIONS]
632```
633
634| Argument or flag | |
635| --- | --- |
636| `-a, --all` | Include the workflows that are turned off. |
637| `-L, --limit <LIMIT>` | Default: `50`. |
638
639Calls [`list_workflows`](/reference/api/actions/list-workflows/).
640
641### g1t workflow view
642
643Show a workflow and its latest runs; --yaml prints its file.
644
645```text
646g1t workflow view [OPTIONS] [WORKFLOW]
647```
648
649| Argument or flag | |
650| --- | --- |
651| `[WORKFLOW]` | Its file name (ci.yml), id (wfl_…) or name; asked for at a terminal when left out. |
652| `-y, --yaml` | Print the workflow's file. |
653| `-g, --ref <REF>` | The branch or tag to read the file on, with --yaml; the default branch when left out. |
654| `-w, --web` | Open it in the browser. |
655
656Calls [`list_workflows`](/reference/api/actions/list-workflows/), [`get_workflow`](/reference/api/actions/get-workflow/), [`list_workflow_runs`](/reference/api/actions/list-workflow-runs/).
657
658### g1t workflow run
659
660Run a workflow that has `on: workflow_dispatch`, and print its run's address.
661
662```text
663g1t workflow run [OPTIONS] [WORKFLOW]
664```
665
666| Argument or flag | |
667| --- | --- |
668| `[WORKFLOW]` | Its file name (ci.yml), id (wfl_…) or name; asked for at a terminal when left out. |
669| `-g, --ref <REF>` | The branch or tag to run it on; the default branch when left out. |
670| `-f, --raw-field <KEY=VALUE>` | An input, key=value; repeat for more. |
671| `-F, --field <KEY=VALUE>` | An input, key=value, where @FILE reads the value from a file (@- from stdin). |
672
673```text
674Inputs are given with -f (or -F, where @FILE reads a file), or as a JSON object on
675stdin with --json. At a terminal, with none given, g1t asks for each input.
676
677Examples:
678 g1t workflow run release.yml
679 g1t workflow run release.yml --ref v1.4.0 -f channel=stable -f dry_run=true
680 echo '{"channel":"stable"}' | g1t workflow run Release --json
681```
682
683Calls [`list_workflows`](/reference/api/actions/list-workflows/), [`dispatch_workflow`](/reference/api/actions/dispatch-workflow/), [`list_workflow_runs`](/reference/api/actions/list-workflow-runs/).
684
685### g1t workflow enable
686
687Turn a workflow on again.
688
689```text
690g1t workflow enable [OPTIONS] [WORKFLOW]
691```
692
693| Argument or flag | |
694| --- | --- |
695| `[WORKFLOW]` | Its file name (ci.yml), id (wfl_…) or name; asked for at a terminal when left out. |
696
697Calls [`list_workflows`](/reference/api/actions/list-workflows/), [`enable_workflow`](/reference/api/actions/enable-workflow/).
698
699### g1t workflow disable
700
701Turn a workflow off: its file stays, and nothing starts it until it is turned on.
702
703```text
704g1t workflow disable [OPTIONS] [WORKFLOW]
705```
706
707| Argument or flag | |
708| --- | --- |
709| `[WORKFLOW]` | Its file name (ci.yml), id (wfl_…) or name; asked for at a terminal when left out. |
710
711Calls [`list_workflows`](/reference/api/actions/list-workflows/), [`disable_workflow`](/reference/api/actions/disable-workflow/).
712
713## g1t secret
714
715Secrets for workflows and deployments, a repository's or a workspace's.
716
717### g1t secret list
718
719List secrets' names (never their values).
720
721```text
722g1t secret list [OPTIONS]
723```
724
725| Argument or flag | |
726| --- | --- |
727| `-w, --workspace <WORKSPACE>` | A workspace's secrets instead of the repository's. |
728| `-e, --env <ENVIRONMENT>` | Only the value for this environment (production, preview...). |
729
730Calls [`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/).
731
732### g1t secret set
733
734Set a secret. The value is read from stdin when not given.
735
736```text
737g1t secret set [OPTIONS] <NAME>
738```
739
740| Argument or flag | |
741| --- | --- |
742| `<NAME>` | The secret's name; uppercased. |
743| `-b, --body <BODY>` | The value. Read from stdin when left out, so it stays out of your shell's history. |
744| `-w, --workspace <WORKSPACE>` | A workspace's secrets instead of the repository's. |
745| `-e, --env <ENVIRONMENT>` | Only the value for this environment (production, preview...). |
746| `--available-to <WHO>` | Who can read it: workflows, deployments, or both (repeat). |
747| `--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. |
748| `--note <NOTE>` | A note for whoever reads the list. |
749
750Calls [`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/).
751
752### g1t secret delete
753
754Delete a secret.
755
756```text
757g1t secret delete [OPTIONS] <NAME>
758```
759
760| Argument or flag | |
761| --- | --- |
762| `<NAME>` | |
763| `-w, --workspace <WORKSPACE>` | A workspace's secrets instead of the repository's. |
764| `-e, --env <ENVIRONMENT>` | Only the value for this environment (production, preview...). |
765
766Calls [`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/).
767
768## g1t cache
769
770The repository's actions/cache entries: list, usage, delete.
771
772### g1t cache list
773
774List the repository's cache entries, least recently used last.
775
776```text
777g1t cache list [OPTIONS]
778```
779
780| Argument or flag | |
781| --- | --- |
782| `-k, --key <KEY>` | Only entries whose key starts with this. |
783| `-g, --ref <REF>` | Only entries saved by this ref's runs, e.g. refs/heads/main. |
784| `-S, --sort <SORT>` | One of `last-accessed-at`, `created-at`, `size-in-bytes`. Default: `last-accessed-at`. |
785| `-O, --order <ORDER>` | One of `asc`, `desc`. Default: `desc`. |
786| `-L, --limit <LIMIT>` | Default: `30`. |
787
788Calls [`list_caches`](/reference/api/actions/list-caches/).
789
790### g1t cache usage
791
792What the repository's cache entries hold, against its quota.
793
794```text
795g1t cache usage [OPTIONS]
796```
797
798Calls [`get_cache_usage`](/reference/api/actions/get-cache-usage/).
799
800### g1t cache delete
801
802Delete cache entries: one by its id, or every entry with a key.
803
804```text
805g1t cache delete [OPTIONS] <ENTRY>
806```
807
808| Argument or flag | |
809| --- | --- |
810| `<ENTRY>` | An entry's id (a number, from `g1t cache list`), or a key: every entry with exactly that key. |
811| `-g, --ref <REF>` | With a key, only the entries this ref's runs saved. |
812
813Calls [`delete_cache`](/reference/api/actions/delete-cache/), [`delete_caches_by_key`](/reference/api/actions/delete-caches-by-key/).
814
815## g1t deploy
816
817Deployments: list and view.
818
819### g1t deploy list
820
821List deployments, newest first.
822
823```text
824g1t deploy list [OPTIONS]
825```
826
827| Argument or flag | |
828| --- | --- |
829| `-e, --env <ENV>` | |
830| `-s, --state <STATE>` | queued, in_progress, success, failure, error or inactive. |
831| `--source <SOURCE>` | api, actions or g1t_page. |
832| `-L, --limit <LIMIT>` | Default: `20`. |
833
834Calls [`list_deployments`](/reference/api/deployments/list-deployments/).
835
836### g1t deploy view
837
838Show a deployment and its statuses.
839
840```text
841g1t deploy view [OPTIONS] <ID>
842```
843
844| Argument or flag | |
845| --- | --- |
846| `<ID>` | |
847| `-w, --web` | |
848
849Calls [`get_deployment`](/reference/api/deployments/get-deployment/).
850
851## g1t logs
852
853A project's logs and errors.
854
855```text
856g1t logs [OPTIONS]
857```
858
859| Argument or flag | |
860| --- | --- |
861| `-p, --project <PROJECT>` | The project; the current repository's when left out. |
862| `--errors` | Grouped errors instead of log lines. |
863| `-q, --query <QUERY>` | Lines holding all of these words, or a "quoted phrase". |
864| `-l, --level <LEVEL>` | Levels: trace, debug, info, warn, error, fatal (comma-separated). |
865| `-e, --env <ENV>` | |
866| `--service <SERVICE>` | |
867| `-s, --since <SINCE>` | How far back: 15m, 2h, 1d, or a time like 2026-10-12T09:00:00Z. |
868| `--state <STATE>` | With --errors: open, resolved or ignored. |
869| `-f, --follow` | Keep printing new lines as they come. |
870| `-L, --limit <LIMIT>` | Default: `50`. |
871
872Calls [`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/).
873
874## g1t status
875
876What needs you: your pull requests, reviews asked of you, your issues, failing checks, and your sessions and claims here.
877
878```text
879g1t status [OPTIONS]
880```
881
882Calls [`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/).
883
884## g1t session
885
886Sessions: one run of an agent's harness, recorded as it works.
887
888### g1t session start
889
890Start a session and remember it for this working copy. Prints its id.
891
892```text
893g1t session start [OPTIONS]
894```
895
896| Argument or flag | |
897| --- | --- |
898| `-i, --issue <ISSUE>` | The issue it works on. |
899| `-p, --pull <PULL>` | The pull request it works on. |
900| `--harness <HARNESS>` | The harness running it. One of `claude_code`, `codex`, `cursor`, `copilot`, `other`. Default: `other`. |
901| `--harness-session-id <ID>` | The harness's own id for the run, which makes starting again return the same session. |
902| `-t, --title <TITLE>` | |
903| `-b, --branch <BRANCH>` | The branch it works on; the current one when left out. |
904
905```text
906The id is kept in .git/g1t/session (each worktree has its own); G1T_SESSION overrides it.
907Starting again with the same --harness-session-id returns the same session.
908```
909
910Calls [`start_session`](/reference/api/sessions/start-session/).
911
912### g1t session heartbeat
913
914Say the current session is still working; renews its claims.
915
916```text
917g1t session heartbeat [OPTIONS]
918```
919
920Calls [`update_session`](/reference/api/sessions/update-session/).
921
922### g1t session log
923
924Record a note, prompt or message in the current session.
925
926```text
927g1t session log [OPTIONS] <TEXT>
928```
929
930| Argument or flag | |
931| --- | --- |
932| `<TEXT>` | What to record; - reads it from stdin. |
933| `-k, --kind <KIND>` | One of `note`, `prompt`, `message`, `tool-call`. Default: `note`. |
934| `--tool <TOOL>` | The tool, for a tool_call. |
935| `--key <KEY>` | A key that makes recording it again do nothing. |
936
937Calls [`record_session_entries`](/reference/api/sessions/record-session-entries/).
938
939### g1t session attach
940
941Attach the current session to an issue, a pull request or a branch.
942
943```text
944g1t session attach [OPTIONS] <--issue <ISSUE>|--pull <PULL>|--branch <BRANCH>|--head-commit <SHA>>
945```
946
947| Argument or flag | |
948| --- | --- |
949| `-i, --issue <ISSUE>` | |
950| `-p, --pull <PULL>` | |
951| `-b, --branch <BRANCH>` | |
952| `--head-commit <SHA>` | The commit it pushed last. |
953
954Calls [`update_session`](/reference/api/sessions/update-session/).
955
956### g1t session end
957
958End the current session.
959
960```text
961g1t session end [OPTIONS]
962```
963
964| Argument or flag | |
965| --- | --- |
966| `-r, --reason <REASON>` | Why it ended: done, abandoned, handed_off... |
967
968Calls [`end_session`](/reference/api/sessions/end-session/).
969
970### g1t session list
971
972List the repository's sessions.
973
974```text
975g1t session list [OPTIONS]
976```
977
978| Argument or flag | |
979| --- | --- |
980| `-s, --state <STATE>` | Only sessions in this state. One of `active`, `idle`, `ended`. |
981| `-i, --issue <ISSUE>` | |
982| `-p, --pull <PULL>` | |
983| `-L, --limit <LIMIT>` | Default: `20`. |
984
985Calls [`list_sessions`](/reference/api/sessions/list-sessions/).
986
987### g1t session view
988
989Show a session and what it recorded; the current one when left out.
990
991```text
992g1t session view [OPTIONS] [ID]
993```
994
995| Argument or flag | |
996| --- | --- |
997| `[ID]` | The session's id (ses_…); the current one when left out. |
998
999Calls [`get_session`](/reference/api/sessions/get-session/).
1000
1001## g1t work
1002
1003Coordinate work on issues: context, claims, hand-offs, dependencies, events.
1004
1005### g1t work context
1006
1007Everything about an issue's work: claims, sessions, pull requests, dependencies, decisions.
1008
1009```text
1010g1t work context [OPTIONS] <NUMBER>
1011```
1012
1013| Argument or flag | |
1014| --- | --- |
1015| `<NUMBER>` | The issue's number. |
1016
1017Calls [`get_work`](/reference/api/claims-and-work/get-work/).
1018
1019### g1t work claim
1020
1021Claim an issue: say you are working on it. Others are told, never stopped.
1022
1023```text
1024g1t work claim [OPTIONS] <NUMBER>
1025```
1026
1027| Argument or flag | |
1028| --- | --- |
1029| `<NUMBER>` | The issue's number. |
1030| `-n, --note <NOTE>` | What you are doing about it. |
1031| `--ttl <DURATION>` | How long the claim lasts unless renewed: 30m, 2h (at most 4h). |
1032
1033Calls [`claim_issue`](/reference/api/claims-and-work/claim-issue/).
1034
1035### g1t work release
1036
1037Release your claim on an issue.
1038
1039```text
1040g1t work release [OPTIONS] <NUMBER>
1041```
1042
1043| Argument or flag | |
1044| --- | --- |
1045| `<NUMBER>` | |
1046| `-r, --reason <REASON>` | Why: done, blocked, abandoned... |
1047
1048Calls [`release_claim`](/reference/api/claims-and-work/release-claim/).
1049
1050### g1t work handoff
1051
1052Hand an issue over to someone else, or to anyone.
1053
1054```text
1055g1t work handoff [OPTIONS] --note <NOTE> <NUMBER>
1056```
1057
1058| Argument or flag | |
1059| --- | --- |
1060| `<NUMBER>` | |
1061| `--to <LOGIN>` | Who takes it over; anyone when left out. |
1062| `-n, --note <NOTE>` | Where it stands and what is left, for whoever takes it. |
1063
1064Calls [`hand_off_issue`](/reference/api/claims-and-work/hand-off-issue/).
1065
1066### g1t work list
1067
1068Active claims and sessions in the repository.
1069
1070```text
1071g1t work list [OPTIONS]
1072```
1073
1074Calls [`list_claims`](/reference/api/claims-and-work/list-claims/), [`list_sessions`](/reference/api/sessions/list-sessions/).
1075
1076### g1t work block
1077
1078Say an issue waits on others: it is blocked by them.
1079
1080```text
1081g1t work block [OPTIONS] --by <NUMBER> <NUMBER>
1082```
1083
1084| Argument or flag | |
1085| --- | --- |
1086| `<NUMBER>` | The issue that waits. |
1087| `--by <NUMBER>` | The issue it waits on; repeat for more. |
1088
1089Calls [`get_issue`](/reference/api/issues/get-issue/), [`update_issue`](/reference/api/issues/update-issue/).
1090
1091### g1t work unblock
1092
1093Say an issue no longer waits on others.
1094
1095```text
1096g1t work unblock [OPTIONS] --by <NUMBER> <NUMBER>
1097```
1098
1099| Argument or flag | |
1100| --- | --- |
1101| `<NUMBER>` | The issue that waits. |
1102| `--by <NUMBER>` | The issue it waits on; repeat for more. |
1103
1104Calls [`get_issue`](/reference/api/issues/get-issue/), [`update_issue`](/reference/api/issues/update-issue/).
1105
1106### g1t work events
1107
1108The repository's events; --follow keeps printing them as they happen.
1109
1110```text
1111g1t work events [OPTIONS]
1112```
1113
1114| Argument or flag | |
1115| --- | --- |
1116| `-f, --follow` | Keep printing events as they happen, until stopped. |
1117| `-t, --type <TYPE>` | Only events of this type; repeat for more. |
1118| `-i, --issue <NUMBER>` | Only events about this issue or pull request; repeat for more. |
1119| `-s, --since <SINCE>` | Only events since then: 15m, 2h, 1d, or a time like 2026-10-12T09:00:00Z. |
1120| `--after <EVENT_ID>` | Start after this event id, as a follow that stopped would resume. |
1121| `-L, --limit <LIMIT>` | How many past events to show first. Default: `20`. |
1122
1123```text
1124Examples:
1125 g1t work events --follow --issue 12
1126 g1t work events --follow --type integration.failed --type overlap.detected --json
1127With --json, each event is one JSON object on a line of its own.
1128```
1129
1130Calls [`list_events`](/reference/api/repositories/list-events/).
1131
1132## g1t why
1133
1134Why a file or line is as it is: its commit, pull request, issue, decisions and sessions.
1135
1136```text
1137g1t why [OPTIONS] <TARGET>
1138```
1139
1140| Argument or flag | |
1141| --- | --- |
1142| `<TARGET>` | A file, or a line of it as PATH:LINE. |
1143| `--ref <REF>` | The branch, tag or commit to read it at; the default branch when left out. |
1144
1145Calls [`why`](/reference/api/decisions-and-why/why/).
1146
1147## g1t api
1148
1149Call any API operation or path, with your token.
1150
1151```text
1152g1t api [OPTIONS] [ENDPOINT]
1153```
1154
1155| Argument or flag | |
1156| --- | --- |
1157| `[ENDPOINT]` | An operation's name, or a path. |
1158| `--list [QUERY]` | List the operations, or those matching this word. |
1159| `-X, --method <METHOD>` | The HTTP method: GET unless fields are given, then POST. |
1160| `-f, --raw-field <KEY=VALUE>` | A string field, key=value. key[]=value adds to a list. |
1161| `-F, --field <KEY=VALUE>` | A typed field: true, false, null and numbers become JSON; @file reads a file. |
1162| `-H, --header <KEY:VALUE>` | A request header, key:value. |
1163| `--input <FILE>` | The request body, from a file or - for stdin. |
1164| `--paginate` | Follow next pages until there are none. |
1165| `--slurp` | With --paginate, put every page's items into one array. |
1166| `-i, --include` | Print the status line and headers too. |
1167| `--silent` | Print nothing on success. |
1168
1169```text
1170ENDPOINT is an operation's name (list_issues) or a path (/repos/{owner}/{name}/issues).
1171{owner}, {name}, {repo} and {workspace} are filled in from the current repository,
1172and an operation's other path parameters from -f/-F fields of the same name.
1173
1174Examples:
1175 g1t api list_issues -f state=closed
1176 g1t api /user --jq .username
1177 g1t api create_issue -f title='Broken link' -f labels[]=docs
1178 g1t api list_workflow_runs --paginate --jq '.[].conclusion'
1179 g1t api --list issue
1180```
1181
1182## g1t browse
1183
1184Open the repository, an issue or a pull request in the browser.
1185
1186```text
1187g1t browse [OPTIONS] [TARGET]
1188```
1189
1190| Argument or flag | |
1191| --- | --- |
1192| `[TARGET]` | An issue or pull request number, a file path (path:line), or a commit. |
1193| `-b, --branch <BRANCH>` | The branch to show files on. |
1194| `-s, --settings` | |
1195| `--issues` | |
1196| `--pulls` | |
1197| `--actions` | |
1198| `-n, --no-browser` | Print the address instead of opening it. |
1199
1200## g1t alias
1201
1202Shortcuts for commands you type often.
1203
1204### g1t alias set
1205
1206Make an alias: g1t alias set co 'pr checkout'. Start it with ! to run it through the shell.
1207
1208```text
1209g1t alias set [OPTIONS] <NAME> <EXPANSION>
1210```
1211
1212| Argument or flag | |
1213| --- | --- |
1214| `<NAME>` | |
1215| `<EXPANSION>` | What it expands to. $1, $2... take the arguments after it. |
1216
1217### g1t alias list
1218
1219List aliases.
1220
1221```text
1222g1t alias list [OPTIONS]
1223```
1224
1225### g1t alias delete
1226
1227Delete an alias.
1228
1229```text
1230g1t alias delete [OPTIONS] <NAME>
1231```
1232
1233| Argument or flag | |
1234| --- | --- |
1235| `<NAME>` | |
1236
1237## g1t completion
1238
1239Print a shell completion script.
1240
1241```text
1242g1t completion [OPTIONS] <SHELL>
1243```
1244
1245| Argument or flag | |
1246| --- | --- |
1247| `<SHELL>` | One of `bash`, `elvish`, `fish`, `powershell`, `zsh`. |
1248
1249## g1t push
1250
1251Push a local container image to g1t's registry, in chunks.
1252
1253```text
1254g1t push [OPTIONS] [IMAGE]
1255```
1256
1257| Argument or flag | |
1258| --- | --- |
1259| `[IMAGE]` | The local image, [REGISTRY/]NAME[:TAG]. |
1260| `--as <ADDRESS>` | Where to push, when the image's own name is not an address on g1t.sh. The tag defaults to latest. |
1261| `--chunk-size <SIZE>` | How much of a layer each request carries: 5MB to 95MB. Default: `90MB`. |
1262| `--token-stdin` | Read the g1t token from stdin. |
1263| `--archive <FILE>` | Push a tarball `docker save` wrote, instead of asking docker for the image. |
1264
1265```text
1266The token is the first of: --token-stdin, G1T_TOKEN, the account `g1t auth login`
1267signed in for the registry's host, or what `docker login g1t.sh` stored.
1268```