1hut(1)                      General Commands Manual                     hut(1)
2
3
4

NAME

6       hut - A CLI tool for sr.ht
7

SYNOPSIS

9       hut [commands...] [options...]
10

DESCRIPTION

12       hut is a CLI companion utility to interact with sr.ht.
13

OPTIONS

15       -h, --help
16           Show help message and quit. Can be used after a command to get more
17           information it.
18
19       --config
20           Explicitly select a configuration file that should be used over the
21           default configuration.
22
23       --instance
24           Select which sr.ht instance from the config file should be used. By
25           default the first one will be selected.
26

COMMANDS

28       help <command>
29           Help about any command.
30
31       graphql <service>
32           Write a GraphQL query and execute it. The JSON response is written
33           to stdout. service is the sr.ht service to execute the query on
34           (for instance "meta" or "builds"). When this command is run from a
35           terminal, the query will be read from $EDITOR, otherwise it de‐
36           faults to stdin.
37
38           A tool like jq(1) can be used to prettify the output and process
39           the data. Example:
40
41               hut graphql meta <<EOF | jq '.me'
42               query {
43                    me { canonicalName }
44               }
45               EOF
46
47           Options are:
48
49           --stdin
50               Read query from stdin.
51
52           -v, --var <key>=<value>
53               Set a raw variable. Example:
54
55                   hut graphql meta -v username=emersion <<'EOF'
56                   query($username: String!) {
57                        userByName(username: $username) {
58                             bio
59                        }
60                   }
61                   EOF
62
63       init
64           Initialize hut's configuration file.
65
66       export <directory>
67           Export account data.
68
69           Note, todo.sr.ht is not yet supported and pagination not imple‐
70           mented at the moment.
71
72   builds
73       artifacts <ID>
74           List artifacts.
75
76       cancel <IDs...>
77           Cancel jobs.
78
79       list [owner]
80           List jobs.
81
82       resubmit <ID>
83           Resubmit a build.
84
85           Options are:
86
87           -e, --edit
88               Edit manifest with $EDITOR.
89
90           -f, --follow
91               Follow build logs.
92
93           -n, --note <string>
94               Provide a short job description.
95
96           -t, --tags <string>
97               Slash separated tags (e.g. "hut/test").
98
99       secrets
100           List secrets.
101
102       show [ID] [options...]
103           Show job status.
104
105           If no ID is specified, the latest build will be printed.
106
107           Options are:
108
109           -f, --follow
110               Follow job status.
111
112       ssh <ID>
113           Connect with SSH to a job.
114
115       submit [manifest...] [options...]
116           Submit a build manifest.
117
118           If no build manifest is specified, build manifests are discovered
119           at .build.yml and .builds/*.yml.
120
121           Options are:
122
123           -e, --edit
124               Edit manifest with $EDITOR.
125
126           -f, --follow
127               Follow build logs.
128
129           -n, --note <string>
130               Provide a short job description.
131
132       user-webhook create [options...]
133           Create a user webhook. When this command is run from a terminal,
134           the query will be read from $EDITOR, otherwise it defaults to
135           stdin.
136
137           Options are:
138
139           -e, --events <strings...>
140               List of events that should trigger the webhook (JOB_CREATED).
141               Required.
142
143           --stdin
144               Read query from stdin.
145
146           -u, --url <URL>
147               The payload URL which receives the POST request. Required.
148
149       user-webhook delete <ID>
150           Delete a user webhook.
151
152       user-webhook list
153           List user webhooks.
154
155   git
156       Options are:
157
158           -r, --repo <string>
159               Name of repository.
160
161       acl delete <ID>
162           Delete an ACL entry.
163
164       acl list [repo]
165           List ACL entries of a repo. Defaults to current repo.
166
167       acl update <user> [options...]
168           Update or add an ACL entry for user.
169
170           Options are:
171
172           -m, --mode <string>
173               Access mode to set (RW, RO).
174
175       artifact delete <ID>
176           Delete an artifact.
177
178       artifact list [options...]
179           List artifacts.
180
181       artifact upload <filename...> [options...]
182           Upload artifacts.
183
184           Options are:
185
186           --rev <string>
187               Revision tag. Defaults to the last Git tag.
188
189       create <name> [options...]
190           Create a repository.
191
192           Options are:
193
194           -c, --clone
195               Clone repository to CWD.
196
197           -d, --description <string>
198               Description of the repository.
199
200           --import-url <url>
201               Import the repository from the given URL.
202
203           -v, --visibility <string>
204               Visibility to use (public, unlisted, private). Defaults to pub‐
205               lic.
206
207       delete [repo] [options...]
208           Delete a repository. By default the current repo will be deleted.
209
210           Options are:
211
212           -y, --yes
213               Confirm deletion without prompt.
214
215       list [owner]
216           List repositories.
217
218       show [repo]
219           Display information about a repository.
220
221       update [repo] [options...]
222           Update a repository.
223
224           Options are:
225
226           -b, --default-branch <branch>
227               Set the default branch.
228
229           -d, --description <description>
230               Set one-line repository description.
231
232           --readme <file>
233               Update the custom README HTML from file. Pass "-" as the file‐
234               name to read from stdin.
235
236           -v, --visibility <string>
237               Visibility to use (public, unlisted, private).
238
239       user-webhook create [options...]
240           Create a user webhook. When this command is run from a terminal,
241           the query will be read from $EDITOR, otherwise it defaults to
242           stdin.
243
244           Options are:
245
246           -e, --events <strings...>
247               List of events that should trigger the webhook (REPO_CREATED,
248               REPO_UPDATE, REPO_DELETED). Required.
249
250           --stdin
251               Read query from stdin.
252
253           -u, --url <URL>
254               The payload URL which receives the POST request. Required.
255
256       user-webhook delete <ID>
257           Delete a user webhook.
258
259       user-webhook list
260           List user webhooks.
261
262   hg
263       create <name> [options...]
264           Create a repository.
265
266           Options are:
267
268           -d, --description <string>
269               Description of the repository.
270
271           -v, --visibility <string>
272               Visibility to use (public, unlisted, private). Defaults to pub‐
273               lic.
274
275       delete <repo> [options...]
276           Delete a repository.
277
278           Options are:
279
280           -y, --yes
281               Confirm deletion without prompt.
282
283       list [owner]
284           List repositories.
285
286       user-webhook create [options...]
287           Create a user webhook. When this command is run from a terminal,
288           the query will be read from $EDITOR, otherwise it defaults to
289           stdin.
290
291           Options are:
292
293           -e, --events <strings...>
294               List of events that should trigger the webhook (REPO_CREATED,
295               REPO_UPDATE, REPO_DELETED). Required.
296
297           --stdin
298               Read query from stdin.
299
300           -u, --url <URL>
301               The payload URL which receives the POST request. Required.
302
303       user-webhook delete <ID>
304           Delete a user webhook.
305
306       user-webhook list
307           List user webhooks.
308
309   lists
310       Options are:
311
312           -l, --mailing-list <name>
313               Select a mailing list.
314
315               By default, the mailing list configured for the current Git
316               repository will be selected.
317
318       acl delete <ID>
319           Delete an ACL entry.
320
321       acl list [list]
322           List ACL entries of a mailing list.
323
324       archive [list] [options...]
325           Download a mailing list archive as an mbox file to stdout.
326
327           Options are:
328
329           -d, --days <int>
330               Number of last days for which the archive should be downloaded.
331               By default the entire archive will be selected.
332
333       create <name> [options...]
334           Create a mailing list.
335
336           Options are:
337
338           --stdin
339               Read description from stdin.
340
341           -v, --visibility <string>
342               Visibility to use (public, unlisted, private). Defaults to pub‐
343               lic.
344
345       delete [list] [options...]
346           Delete a mailing list.
347
348           Options are:
349
350           -y, --yes
351               Confirm deletion without prompt.
352
353       list [owner]
354           List mailing lists.
355
356       patchset apply <ID>
357           Apply a patchset.
358
359       patchset list [list] [options...]
360           List patchsets in list.
361
362           Options are:
363
364           -u, --user
365               List patchsets by user instead of by list.
366
367       patchset show <ID>
368           Show a patchset.
369
370       patchset update <ID>
371           Update a patchset.
372
373           Options are:
374
375           -s, --status <string>
376               Patchset status to set (required).
377
378       subscribe [list]
379           Subscribe to a mailing list.
380
381       unsubscribe [list]
382           Unsubscribe from a mailing list.
383
384       user-webhook create [options...]
385           Create a user webhook. When this command is run from a terminal,
386           the query will be read from $EDITOR, otherwise it defaults to
387           stdin.
388
389           Options are:
390
391           -e, --events <strings...>
392               List of events that should trigger the webhook (LIST_CREATED,
393               LIST_UPDATED, LIST_DELETED, EMAIL_RECEIVED, PATCHSET_RECEIVED).
394               Required.
395
396           --stdin
397               Read query from stdin.
398
399           -u, --url <URL>
400               The payload URL which receives the POST request. Required.
401
402       user-webhook delete <ID>
403           Delete a user webhook.
404
405       user-webhook list
406           List user webhooks.
407
408       webhook create [list] [options...]
409           Create a mailing list webhook.
410
411           Options are:
412
413           -e, --events <strings...>
414               List of events that should trigger the webhook (LIST_UPDATED,
415               LIST_DELETED, EMAIL_RECEIVED, PATCHSET_RECEIVED). Required.
416
417           --stdin
418               Read query from stdin.
419
420           -u, --url <URL>
421               The payload URL which receives the POST request. Required.
422
423       webhook delete <ID>
424           Delete a tracker webhook.
425
426       webhook list [list]
427           List mailing list webhooks.
428
429   meta
430       audit-log
431           Display your audit log.
432
433       pgp-key create [path]
434           Upload a PGP public key and associate it with your account.
435
436           The public key must be in the armored format.
437
438           If path is not specified, the default public key from the local GPG
439           keyring is used.
440
441       pgp-key delete <ID>
442           Delete a PGP key from your account.
443
444       pgp-key list [username] [options...]
445           List PGP public keys.
446
447           Options are:
448
449           -r, --raw
450               Only print raw public key
451
452       show [username]
453           Show a user's profile.
454
455           If username is not specified, your profile is displayed.
456
457       ssh-key create [path]
458           Upload an SSH public key and associate it with your account.
459
460           If path is not specified, the default SSH public key is used.
461
462       ssh-key delete <ID>
463           Delete an SSH public key from your account.
464
465       ssh-key list [username] [options...]
466           List SSH public keys.
467
468           Options are:
469
470           -r, --raw
471               Only print raw public key
472
473       user-webhook create [options...]
474           Create a user webhook. When this command is run from a terminal,
475           the query will be read from $EDITOR, otherwise it defaults to
476           stdin.
477
478           Options are:
479
480           -e, --events <strings...>
481               List of events that should trigger the webhook (PROFILE_UPDATE,
482               PGP_KEY_ADDED, PGP_KEY_REMOVED, SSH_KEY_ADDED, SSH_KEY_RE‐
483               MOVED). Required.
484
485           --stdin
486               Read query from stdin.
487
488           -u, --url <URL>
489               The payload URL which receives the POST request. Required.
490
491       user-webhook delete <ID>
492           Delete a user webhook.
493
494       user-webhook list
495           List user webhooks.
496
497   pages
498       list
499           List registered sites.
500
501       publish [file] [options...]
502           Publish a website.
503
504           The input file can be either a gzip tarball or a directory. If file
505           is not specified, standard input is used.
506
507           Options are:
508
509           -d, --domain <string>
510               Fully qualified domain name.
511
512           --not-found <string>
513               Path to serve for page not found responses. This flag is depre‐
514               cated, use --site-config instead to set the path.
515
516           -p, --protocol <string>
517               Protocol to use (either HTTPS or GEMINI; defaults to HTTPS)
518
519           --site-config <string>
520               Path to site configuration file (for e.g. cache-control).
521
522           -s, --subdirectory <string>
523               If specified, only this subdirectory is updated, the rest of
524               the site is left untouched.
525
526       unpublish [options...]
527           Unpublish a website.
528
529           Options are:
530
531           -d, --domain <string>
532               Fully qualified domain name.
533
534           -p, --protocol <string>
535               Protocol to use (either HTTPS or GEMINI; defaults to HTTPS)
536
537       user-webhook create [options...]
538           Create a user webhook. When this command is run from a terminal,
539           the query will be read from $EDITOR, otherwise it defaults to
540           stdin.
541
542           Options are:
543
544           -e, --events <strings...>
545               List of events that should trigger the webhook (SITE_PUBLISHED,
546               SITE_UNPUBLISHED). Required.
547
548           --stdin
549               Read query from stdin.
550
551           -u, --url <URL>
552               The payload URL which receives the POST request. Required.
553
554       user-webhook delete <ID>
555           Delete a user webhook.
556
557       user-webhook list
558           List user webhooks.
559
560   paste
561       create <filenames...>
562           Create a new paste.
563
564           Options are:
565
566           -v, --visibility <string>
567               Visibility to use (public, unlisted, private). Defaults to un‐
568               listed.
569
570           -n, --name <string>
571               Name of the created paste. Only valid when reading from stdin.
572
573       delete <IDs...>
574           Delete pastes.
575
576       list
577           List pastes.
578
579       show <ID>
580           Display a paste.
581
582       update <ID> [options...]
583           Update a paste's visibility.
584
585           Options are:
586
587           -v, --visibility <string>
588               Visibility to use (public, unlisted, private)
589
590       user-webhook create [options...]
591           Create a user webhook. When this command is run from a terminal,
592           the query will be read from $EDITOR, otherwise it defaults to
593           stdin.
594
595           Options are:
596
597           -e, --events <strings...>
598               List of events that should trigger the webhook (PASTE_CREATED,
599               PASTE_UPDATED, PASTE_DELETED). Required.
600
601           --stdin
602               Read query from stdin.
603
604           -u, --url <URL>
605               The payload URL which receives the POST request. Required.
606
607       user-webhook delete <ID>
608           Delete a user webhook.
609
610       user-webhook list
611           List user webhooks.
612
613   todo
614       Options are:
615
616           -t, --tracker <string>
617               Name of tracker.
618
619       acl delete <ID>
620           Delete an ACL entry.
621
622       acl list [tracker]
623           List ACL entries of a tracker.
624
625       create <name> [options...]
626           Create a tracker.
627
628           Options are:
629
630           --stdin
631               Read description from stdin.
632
633           -v, --visibility <string>
634               Visibility to use (public, unlisted, private). Defaults to pub‐
635               lic.
636
637       delete <tracker> [options...]
638           Delete a tracker.
639
640           Options are:
641
642           -y, --yes
643               Confirm deletion without prompt.
644
645       label create <name> [options...]
646           Create a label.
647
648           Options are:
649
650           -b, --background
651               Background color in hex format (required).
652
653           -f, --foreground
654               Foreground color in hex format. If omitted either black or
655               white will be selected for an optimized contrast.
656
657       label delete <name>
658           Delete a label.
659
660       label list
661           List labels.
662
663       list [owner]
664           List trackers.
665
666       subscribe [tracker]
667           Subscribe to a tracker.
668
669       ticket assign <ID> [options...]
670           Assign a user to a ticket.
671
672           Options are:
673
674           -u, --user
675               Username of the new assignee (required).
676
677       ticket comment <ID> [options...]
678           Comment on a ticket with $EDITOR.
679
680           Options are:
681
682           -r, --resolution
683               Resolution for resolved tickets. If status is omitted, it will
684               be set to RESOLVED.
685
686           -s, --status
687               New ticket status. If set to RESOLVED, resolution will default
688               to CLOSED.
689
690           --stdin
691               Read comment from stdin.
692
693       ticket create [options...]
694           Create a new ticket with $EDITOR.
695
696           Options are:
697
698           --stdin
699               Read ticket from stdin.
700
701       ticket delete <ID> [options...]
702           Delete a ticket.
703
704           Options are:
705
706           -y, --yes
707               Confirm deletion without prompt.
708
709       ticket label <ID> [options...]
710           Add a label to a ticket.
711
712           Options are:
713
714           -l, --label <name>
715               Name of the label (required).
716
717       ticket list
718           List tickets.
719
720       ticket show <ID>
721           Display a ticket.
722
723       ticket subscribe <ID>
724           Subscribe to a ticket.
725
726       ticket unassign <ID> [options...]
727           Unassign a user from a ticket.
728
729           Options are:
730
731           -u, --user
732               Username of the assignee (required).
733
734       ticket unlabel <ID> [options...]
735           Remove a label from a ticket.
736
737           Options are:
738
739           -l, --label <name>
740               Name of the label (required).
741
742       ticket unsubscribe <ID>
743           Unsubscribe from a ticket.
744
745       ticket update-status <ID> [options...]
746           Update status of a ticket.
747
748           Options are:
749
750           -r, --resolution
751               Resolution for resolved tickets (required if status RESOLVED is
752               used). If status is omitted, it will be set to RESOLVED.
753
754           -s, --status
755               New ticket status.
756
757       ticket webhook create <ID> [options...]
758           Create a ticket webhook.
759
760           Options are:
761
762           -e, --events <strings...>
763               List of events that should trigger the webhook (EVENT_CREATED,
764               TICKET_UPDATE, TICKET_DELETED). Required.
765
766           --stdin
767               Read query from stdin.
768
769           -u, --url <URL>
770               The payload URL which receives the POST request. Required.
771
772       ticket webhook delete <ID>
773           Delete a ticket webhook.
774
775       ticket webhook list <ID>
776           List ticket webhooks.
777
778       unsubscribe [tracker]
779           Unsubscribe from a tracker.
780
781       user-webhook create [options...]
782           Create a user webhook. When this command is run from a terminal,
783           the query will be read from $EDITOR, otherwise it defaults to
784           stdin.
785
786           Options are:
787
788           -e, --events <strings...>
789               List of events that should trigger the webhook (TRACKER_CRE‐
790               ATED, TRACKER_UPDATE, TRACKER_DELETED, TICKET_CREATED). Re‐
791               quired.
792
793           --stdin
794               Read query from stdin.
795
796           -u, --url <URL>
797               The payload URL which receives the POST request. Required.
798
799       user-webhook delete <ID>
800           Delete a user webhook.
801
802       user-webhook list
803           List user webhooks.
804
805       webhook create [tracker] [options...]
806           Create a tracker webhook.
807
808           Options are:
809
810           -e, --events <strings...>
811               List of events that should trigger the webhook (TRACKER_UPDATE,
812               TRACKER_DELETED, LABEL_CREATED, LABEL_UPDATE, LABEL_DELETED,
813               TICKET_CREATED, TICKET_UPDATE, TICKET_DELETED, EVENT_CREATED).
814               Required.
815
816           --stdin
817               Read query from stdin.
818
819           -u, --url <URL>
820               The payload URL which receives the POST request. Required.
821
822       webhook delete <ID>
823           Delete a tracker webhook.
824
825       webhook list [tracker]
826           List tracker webhooks.
827

CONFIGURATION

829       Generate a new OAuth2 access token on meta.sr.ht.
830
831       On startup hut will look for a file at $XDG_CONFIG_HOME/hut/config. If
832       unset, $XDG_CONFIG_HOME defaults to ~/.config/.
833
834           instance "sr.ht" {
835                access-token "<token>"
836                # As an alternative you can specify a command whose first line of output
837                # will be parsed as the token
838                access-token-cmd pass token
839                meta {
840                     # You can set the origin for each service. As fallback hut will
841                     # construct the origin from the instance name and the service.
842                     origin "https://meta.sr.ht"
843                }
844           }
845

AUTHORS

847       Maintained by Simon Ser <contact@emersion.fr>, who is assisted by other
848       open-source contributors. For more information about hut development,
849       see <https://sr.ht/~emersion/hut>.
850
851
852
853                                  2023-07-20                            hut(1)
Impressum