1hut(1) General Commands Manual hut(1)
2
6 hut - A CLI tool for sr.ht
7
9 hut [commands...] [options...]
10
12 hut is a CLI companion utility to interact with sr.ht.
13
15 -h, --help
16 Show help message and quit. Can be used after a command to get more
17 information it.
18 --config
20 Explicitly select a configuration file that should be used over the
21 default configuration.
22 --instance
24 Select which sr.ht instance from the config file should be used. By
25 default the first one will be selected.
26
28 help <command>
29 Help about any command.
30 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 A tool like jq(1) can be used to prettify the output and process
39 the data. Example:
40 hut graphql meta <<EOF | jq '.me'
42 query {
43 me { canonicalName }
44 }
45 EOF
46 Options are:
48 --stdin
50 Read query from stdin.
51 -v, --var <key>=<value>
53 Set a raw variable. Example:
54 hut graphql meta -v username=emersion <<'EOF'
56 query($username: String!) {
57 userByName(username: $username) {
58 bio
59 }
60 }
61 EOF
62 init
64 Initialize hut's configuration file.
65 export <directory>
67 Export account data.
68 Note, todo.sr.ht is not yet supported and pagination not imple‐
70 mented at the moment.
71 builds
73 artifacts <ID>
74 List artifacts.
75 cancel <IDs...>
77 Cancel jobs.
78 list [owner]
80 List jobs.
81 resubmit <ID>
83 Resubmit a build.
84 Options are:
86 -e, --edit
88 Edit manifest with $EDITOR.
89 -f, --follow
91 Follow build logs.
92 -n, --note <string>
94 Provide a short job description.
95 -t, --tags <string>
97 Slash separated tags (e.g. "hut/test").
98 secrets
100 List secrets.
101 show [ID] [options...]
103 Show job status.
104 If no ID is specified, the latest build will be printed.
106 Options are:
108 -f, --follow
110 Follow job status.
111 ssh <ID>
113 Connect with SSH to a job.
114 submit [manifest...] [options...]
116 Submit a build manifest.
117 If no build manifest is specified, build manifests are discovered
119 at .build.yml and .builds/*.yml.
120 Options are:
122 -e, --edit
124 Edit manifest with $EDITOR.
125 -f, --follow
127 Follow build logs.
128 -n, --note <string>
130 Provide a short job description.
131 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 Options are:
138 -e, --events <strings...>
140 List of events that should trigger the webhook (JOB_CREATED).
141 Required.
142 --stdin
144 Read query from stdin.
145 -u, --url <URL>
147 The payload URL which receives the POST request. Required.
148 user-webhook delete <ID>
150 Delete a user webhook.
151 user-webhook list
153 List user webhooks.
154 git
156 Options are:
157 -r, --repo <string>
159 Name of repository.
160 acl delete <ID>
162 Delete an ACL entry.
163 acl list [repo]
165 List ACL entries of a repo. Defaults to current repo.
166 acl update <user> [options...]
168 Update or add an ACL entry for user.
169 Options are:
171 -m, --mode <string>
173 Access mode to set (RW, RO).
174 artifact delete <ID>
176 Delete an artifact.
177 artifact list [options...]
179 List artifacts.
180 artifact upload <filename...> [options...]
182 Upload artifacts.
183 Options are:
185 --rev <string>
187 Revision tag. Defaults to the last Git tag.
188 create <name> [options...]
190 Create a repository.
191 Options are:
193 -c, --clone
195 Clone repository to CWD.
196 -d, --description <string>
198 Description of the repository.
199 --import-url <url>
201 Import the repository from the given URL.
202 -v, --visibility <string>
204 Visibility to use (public, unlisted, private). Defaults to pub‐
205 lic.
206 delete [repo] [options...]
208 Delete a repository. By default the current repo will be deleted.
209 Options are:
211 -y, --yes
213 Confirm deletion without prompt.
214 list [owner]
216 List repositories.
217 show [repo]
219 Display information about a repository.
220 update [repo] [options...]
222 Update a repository.
223 Options are:
225 -b, --default-branch <branch>
227 Set the default branch.
228 -d, --description <description>
230 Set one-line repository description.
231 --readme <file>
233 Update the custom README HTML from file. Pass "-" as the file‐
234 name to read from stdin.
235 -v, --visibility <string>
237 Visibility to use (public, unlisted, private).
238 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 Options are:
245 -e, --events <strings...>
247 List of events that should trigger the webhook (REPO_CREATED,
248 REPO_UPDATE, REPO_DELETED). Required.
249 --stdin
251 Read query from stdin.
252 -u, --url <URL>
254 The payload URL which receives the POST request. Required.
255 user-webhook delete <ID>
257 Delete a user webhook.
258 user-webhook list
260 List user webhooks.
261 hg
263 create <name> [options...]
264 Create a repository.
265 Options are:
267 -d, --description <string>
269 Description of the repository.
270 -v, --visibility <string>
272 Visibility to use (public, unlisted, private). Defaults to pub‐
273 lic.
274 delete <repo> [options...]
276 Delete a repository.
277 Options are:
279 -y, --yes
281 Confirm deletion without prompt.
282 list [owner]
284 List repositories.
285 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 Options are:
292 -e, --events <strings...>
294 List of events that should trigger the webhook (REPO_CREATED,
295 REPO_UPDATE, REPO_DELETED). Required.
296 --stdin
298 Read query from stdin.
299 -u, --url <URL>
301 The payload URL which receives the POST request. Required.
302 user-webhook delete <ID>
304 Delete a user webhook.
305 user-webhook list
307 List user webhooks.
308 lists
310 Options are:
311 -l, --mailing-list <name>
313 Select a mailing list.
314 By default, the mailing list configured for the current Git
316 repository will be selected.
317 acl delete <ID>
319 Delete an ACL entry.
320 acl list [list]
322 List ACL entries of a mailing list.
323 archive [list] [options...]
325 Download a mailing list archive as an mbox file to stdout.
326 Options are:
328 -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 create <name> [options...]
334 Create a mailing list.
335 Options are:
337 --stdin
339 Read description from stdin.
340 -v, --visibility <string>
342 Visibility to use (public, unlisted, private). Defaults to pub‐
343 lic.
344 delete [list] [options...]
346 Delete a mailing list.
347 Options are:
349 -y, --yes
351 Confirm deletion without prompt.
352 list [owner]
354 List mailing lists.
355 patchset apply <ID>
357 Apply a patchset.
358 patchset list [list] [options...]
360 List patchsets in list.
361 Options are:
363 -u, --user
365 List patchsets by user instead of by list.
366 patchset show <ID>
368 Show a patchset.
369 patchset update <ID>
371 Update a patchset.
372 Options are:
374 -s, --status <string>
376 Patchset status to set (required).
377 subscribe [list]
379 Subscribe to a mailing list.
380 unsubscribe [list]
382 Unsubscribe from a mailing list.
383 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 Options are:
390 -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 --stdin
397 Read query from stdin.
398 -u, --url <URL>
400 The payload URL which receives the POST request. Required.
401 user-webhook delete <ID>
403 Delete a user webhook.
404 user-webhook list
406 List user webhooks.
407 webhook create [list] [options...]
409 Create a mailing list webhook.
410 Options are:
412 -e, --events <strings...>
414 List of events that should trigger the webhook (LIST_UPDATED,
415 LIST_DELETED, EMAIL_RECEIVED, PATCHSET_RECEIVED). Required.
416 --stdin
418 Read query from stdin.
419 -u, --url <URL>
421 The payload URL which receives the POST request. Required.
422 webhook delete <ID>
424 Delete a tracker webhook.
425 webhook list [list]
427 List mailing list webhooks.
428 meta
430 audit-log
431 Display your audit log.
432 pgp-key create [path]
434 Upload a PGP public key and associate it with your account.
435 The public key must be in the armored format.
437 If path is not specified, the default public key from the local GPG
439 keyring is used.
440 pgp-key delete <ID>
442 Delete a PGP key from your account.
443 pgp-key list [username] [options...]
445 List PGP public keys.
446 Options are:
448 -r, --raw
450 Only print raw public key
451 show [username]
453 Show a user's profile.
454 If username is not specified, your profile is displayed.
456 ssh-key create [path]
458 Upload an SSH public key and associate it with your account.
459 If path is not specified, the default SSH public key is used.
461 ssh-key delete <ID>
463 Delete an SSH public key from your account.
464 ssh-key list [username] [options...]
466 List SSH public keys.
467 Options are:
469 -r, --raw
471 Only print raw public key
472 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 Options are:
479 -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 --stdin
486 Read query from stdin.
487 -u, --url <URL>
489 The payload URL which receives the POST request. Required.
490 user-webhook delete <ID>
492 Delete a user webhook.
493 user-webhook list
495 List user webhooks.
496 pages
498 list
499 List registered sites.
500 publish [file] [options...]
502 Publish a website.
503 The input file can be either a gzip tarball or a directory. If file
505 is not specified, standard input is used.
506 Options are:
508 -d, --domain <string>
510 Fully qualified domain name.
511 --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 -p, --protocol <string>
517 Protocol to use (either HTTPS or GEMINI; defaults to HTTPS)
518 --site-config <string>
520 Path to site configuration file (for e.g. cache-control).
521 -s, --subdirectory <string>
523 If specified, only this subdirectory is updated, the rest of
524 the site is left untouched.
525 unpublish [options...]
527 Unpublish a website.
528 Options are:
530 -d, --domain <string>
532 Fully qualified domain name.
533 -p, --protocol <string>
535 Protocol to use (either HTTPS or GEMINI; defaults to HTTPS)
536 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 Options are:
543 -e, --events <strings...>
545 List of events that should trigger the webhook (SITE_PUBLISHED,
546 SITE_UNPUBLISHED). Required.
547 --stdin
549 Read query from stdin.
550 -u, --url <URL>
552 The payload URL which receives the POST request. Required.
553 user-webhook delete <ID>
555 Delete a user webhook.
556 user-webhook list
558 List user webhooks.
559 paste
561 create <filenames...>
562 Create a new paste.
563 Options are:
565 -v, --visibility <string>
567 Visibility to use (public, unlisted, private). Defaults to un‐
568 listed.
569 -n, --name <string>
571 Name of the created paste. Only valid when reading from stdin.
572 delete <IDs...>
574 Delete pastes.
575 list
577 List pastes.
578 show <ID>
580 Display a paste.
581 update <ID> [options...]
583 Update a paste's visibility.
584 Options are:
586 -v, --visibility <string>
588 Visibility to use (public, unlisted, private)
589 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 Options are:
596 -e, --events <strings...>
598 List of events that should trigger the webhook (PASTE_CREATED,
599 PASTE_UPDATED, PASTE_DELETED). Required.
600 --stdin
602 Read query from stdin.
603 -u, --url <URL>
605 The payload URL which receives the POST request. Required.
606 user-webhook delete <ID>
608 Delete a user webhook.
609 user-webhook list
611 List user webhooks.
612 todo
614 Options are:
615 -t, --tracker <string>
617 Name of tracker.
618 acl delete <ID>
620 Delete an ACL entry.
621 acl list [tracker]
623 List ACL entries of a tracker.
624 create <name> [options...]
626 Create a tracker.
627 Options are:
629 --stdin
631 Read description from stdin.
632 -v, --visibility <string>
634 Visibility to use (public, unlisted, private). Defaults to pub‐
635 lic.
636 delete <tracker> [options...]
638 Delete a tracker.
639 Options are:
641 -y, --yes
643 Confirm deletion without prompt.
644 label create <name> [options...]
646 Create a label.
647 Options are:
649 -b, --background
651 Background color in hex format (required).
652 -f, --foreground
654 Foreground color in hex format. If omitted either black or
655 white will be selected for an optimized contrast.
656 label delete <name>
658 Delete a label.
659 label list
661 List labels.
662 list [owner]
664 List trackers.
665 subscribe [tracker]
667 Subscribe to a tracker.
668 ticket assign <ID> [options...]
670 Assign a user to a ticket.
671 Options are:
673 -u, --user
675 Username of the new assignee (required).
676 ticket comment <ID> [options...]
678 Comment on a ticket with $EDITOR.
679 Options are:
681 -r, --resolution
683 Resolution for resolved tickets. If status is omitted, it will
684 be set to RESOLVED.
685 -s, --status
687 New ticket status. If set to RESOLVED, resolution will default
688 to CLOSED.
689 --stdin
691 Read comment from stdin.
692 ticket create [options...]
694 Create a new ticket with $EDITOR.
695 Options are:
697 --stdin
699 Read ticket from stdin.
700 ticket delete <ID> [options...]
702 Delete a ticket.
703 Options are:
705 -y, --yes
707 Confirm deletion without prompt.
708 ticket label <ID> [options...]
710 Add a label to a ticket.
711 Options are:
713 -l, --label <name>
715 Name of the label (required).
716 ticket list
718 List tickets.
719 ticket show <ID>
721 Display a ticket.
722 ticket subscribe <ID>
724 Subscribe to a ticket.
725 ticket unassign <ID> [options...]
727 Unassign a user from a ticket.
728 Options are:
730 -u, --user
732 Username of the assignee (required).
733 ticket unlabel <ID> [options...]
735 Remove a label from a ticket.
736 Options are:
738 -l, --label <name>
740 Name of the label (required).
741 ticket unsubscribe <ID>
743 Unsubscribe from a ticket.
744 ticket update-status <ID> [options...]
746 Update status of a ticket.
747 Options are:
749 -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 -s, --status
755 New ticket status.
756 ticket webhook create <ID> [options...]
758 Create a ticket webhook.
759 Options are:
761 -e, --events <strings...>
763 List of events that should trigger the webhook (EVENT_CREATED,
764 TICKET_UPDATE, TICKET_DELETED). Required.
765 --stdin
767 Read query from stdin.
768 -u, --url <URL>
770 The payload URL which receives the POST request. Required.
771 ticket webhook delete <ID>
773 Delete a ticket webhook.
774 ticket webhook list <ID>
776 List ticket webhooks.
777 unsubscribe [tracker]
779 Unsubscribe from a tracker.
780 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 Options are:
787 -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 --stdin
794 Read query from stdin.
795 -u, --url <URL>
797 The payload URL which receives the POST request. Required.
798 user-webhook delete <ID>
800 Delete a user webhook.
801 user-webhook list
803 List user webhooks.
804 webhook create [tracker] [options...]
806 Create a tracker webhook.
807 Options are:
809 -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 --stdin
817 Read query from stdin.
818 -u, --url <URL>
820 The payload URL which receives the POST request. Required.
821 webhook delete <ID>
823 Delete a tracker webhook.
824 webhook list [tracker]
826 List tracker webhooks.
827
829 Generate a new OAuth2 access token on meta.sr.ht.
830 On startup hut will look for a file at $XDG_CONFIG_HOME/hut/config. If
832 unset, $XDG_CONFIG_HOME defaults to ~/.config/.
833 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
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 2023-07-20 hut(1)