hut(1) General Commands Manual hut(1) NAME hut - A CLI tool for sr.ht SYNOPSIS hut [commands...] [options...] DESCRIPTION hut is a CLI companion utility to interact with sr.ht. Resources (such as build jobs, todo tickets, lists patchsets, git repositories, and so on) can be specified in multiple forms: name, owner and name, or full URL. For instance, the repository hut owned by ~emersion on git.sr.ht can be referred to via: o "hut" o "~emersion/hut" o "https://git.sr.ht/~emersion/hut" Additionally, mailing lists can be referred to by their email address. hut commands that read input, like hut graphql or hut builds user- webhook create read input depending on whether their stdin is on a terminal or not: o If stdin is not on a terminal, for example, because stdin is redirected from a file or from a pipe, hut reads input from stdin. o Otherwise, if option --stdin is specified to the command, hut reads input from stdin. o Otherwise, hut assumes to run in a terminal and starts the command provided by environment variable $EDITOR to read input. OPTIONS -h, --help Show help message and quit. Can be used after a command to get more information it. --config Explicitly select a configuration file that should be used over the default configuration. --debug Prints the command's underlying GraphQL request to stderr. --instance Select which sr.ht instance from the config file should be used. By default the first one will be selected. COMMANDS help Help about any command. graphql Write a GraphQL query and execute it. The JSON response is written to stdout. service is the sr.ht service to execute the query on (for instance "meta" or "builds"). A tool like jq(1) can be used to prettify the output and process the data. Example: hut graphql meta <= Set a file variable. --stdin Read query from stdin. -v, --var = Set a raw variable. Example: hut graphql meta -v username=emersion <<'EOF' query($username: String!) { userByName(username: $username) { bio } } EOF init Initialize hut's configuration file. export [resource|service...] Export account data. By default, all data of the current user will be exported. Alternatively, an explicit list of instance services (e.g. "todo.sr.ht") or resources (e.g. "todo.sr.ht/~user/tracker") can be specified. import Import account data. builds artifacts List artifacts. cancel Cancel jobs. list [owner] List jobs. resubmit Resubmit a build. Options are: -e, --edit Edit manifest with $EDITOR. -f, --follow Follow build logs. -n, --note Provide a short job description. -v, --visibility Visibility to use (public, unlisted, private). Defaults to the same visibility used by the original build job. secret list List secrets. secret share Share a secret. Options are: -u, --user User with whom to share the secret (required). show [ID] [options...] Show job status. If no ID is specified, the latest build will be printed. Options are: -f, --follow Follow job status. ssh Connect with SSH to a job. submit [manifest...] [options...] Submit a build manifest. If no build manifest is specified, build manifests are discovered at .build.yml and .builds/*.yml. Options are: -e, --edit Edit manifest with $EDITOR. -f, --follow Follow build logs. -n, --note Provide a short job description. -t, --tags Slash separated tags (e.g. "hut/test"). -v, --visibility Visibility to use (public, unlisted, private). Defaults to unlisted. user-webhook create [options...] Create a user webhook. Options are: -e, --events List of events that should trigger the webhook (JOB_CREATED). Required. --stdin Read query from stdin. -u, --url The payload URL which receives the POST request. Required. user-webhook delete Delete a user webhook. user-webhook list List user webhooks. git Options are: -r, --repo Name of repository. acl delete Delete an ACL entry. acl list [repo] List ACL entries of a repo. Defaults to current repo. acl update [options...] Update or add an ACL entry for user. Options are: -m, --mode Access mode to set (RW, RO). artifact delete Delete an artifact. artifact list [options...] List artifacts. artifact upload [options...] Upload artifacts. Options are: --rev Revision tag. Defaults to the last Git tag. clone This will clone the repository to CWD and try to configure it for git send-email if possible. create [options...] Create a repository. If --clone is not used, the remote URL will be printed to stdout. Options are: -c, --clone Clone repository to CWD. -d, --description Description of the repository. --import-url Import the repository from the given URL. -v, --visibility Visibility to use (public, unlisted, private). Defaults to public. delete [repo] [options...] Delete a repository. By default the current repo will be deleted. Options are: -y, --yes Confirm deletion without prompt. list [owner] List repositories. show [repo] Display information about a repository. update [repo] [options...] Update a repository. By default the current repo will be updated. Options are: -b, --default-branch Set the default branch. -d, --description Set one-line repository description. --readme Update the custom README settings. You can read the HTML from a file or pass "-" as the filename to read from stdin. To clear the custom README use an empty string "". -v, --visibility Visibility to use (public, unlisted, private). user-webhook create [options...] Create a user webhook. Options are: -e, --events List of events that should trigger the webhook (REPO_CREATED, REPO_UPDATE, REPO_DELETED). Required. --stdin Read query from stdin. -u, --url The payload URL which receives the POST request. Required. user-webhook delete Delete a user webhook. user-webhook list List user webhooks. hg Options are: -r, --repo Name of repository. acl delete Delete an ACL entry. acl list [repo] List ACL entries of a repo. Defaults to current repo. acl update [options...] Update or add an ACL entry for user. Options are: -m, --mode Access mode to set (RW, RO). create [options...] Create a repository. If --clone is not used, the remote URL will be printed to stdout. Options are: -c, --clone Clone repository to CWD. -d, --description Description of the repository. -v, --visibility Visibility to use (public, unlisted, private). Defaults to public. delete [repo] [options...] Delete a repository. By default the current repo will be deleted. Options are: -y, --yes Confirm deletion without prompt. list [owner] List repositories. update [repo] [options...] Update a repository. By default the current repo will be updated. Options are: -d, --description Set one-line repository description. --non-publishing Controls whether this repository is a non-publishing repository. --readme Update the custom README settings. You can read the HTML from a file or pass "-" as the filename to read from stdin. To clear the custom README use an empty string "". -v, --visibility Visibility to use (public, unlisted, private). user-webhook create [options...] Create a user webhook. Options are: -e, --events List of events that should trigger the webhook (REPO_CREATED, REPO_UPDATE, REPO_DELETED). Required. --stdin Read query from stdin. -u, --url The payload URL which receives the POST request. Required. user-webhook delete Delete a user webhook. user-webhook list List user webhooks. lists Options are: -l, --mailing-list Select a mailing list. By default, the mailing list configured for the current Git repository will be selected. acl delete Delete an ACL entry. acl list [list] List ACL entries of a mailing list. archive [list] [options...] Download a mailing list archive as an mbox file to stdout. Options are: -d, --days Number of last days for which the archive should be downloaded. By default the entire archive will be selected. create [options...] Create a mailing list. Options are: --stdin Read description from stdin. -v, --visibility Visibility to use (public, unlisted, private). Defaults to public. delete [list] [options...] Delete a mailing list. Options are: -y, --yes Confirm deletion without prompt. list [owner] List mailing lists. patchset apply Apply a patchset. patchset list [list] [options...] List patchsets in list. Options are: -u, --user List patchsets by user instead of by list. patchset show Show a patchset. patchset update Update a patchset. Options are: -s, --status Patchset status to set (required). subscribe [list] Subscribe to a mailing list. subscriptions List mailing list subscriptions. unsubscribe [list] Unsubscribe from a mailing list. update [list] [options...] Update a mailing list. Options are: --description Edit description. -v, --visibility Visibility to use (public, unlisted, private). user-webhook create [options...] Create a user webhook. Options are: -e, --events List of events that should trigger the webhook (LIST_CREATED, LIST_UPDATED, LIST_DELETED, EMAIL_RECEIVED, PATCHSET_RECEIVED). Required. --stdin Read query from stdin. -u, --url The payload URL which receives the POST request. Required. user-webhook delete Delete a user webhook. user-webhook list List user webhooks. webhook create [list] [options...] Create a mailing list webhook. Options are: -e, --events List of events that should trigger the webhook (LIST_UPDATED, LIST_DELETED, EMAIL_RECEIVED, PATCHSET_RECEIVED). Required. --stdin Read query from stdin. -u, --url The payload URL which receives the POST request. Required. webhook delete Delete a tracker webhook. webhook list [list] List mailing list webhooks. meta audit-log Display your audit log. oauth tokens List personal access tokens. pgp-key create [path] Upload a PGP public key and associate it with your account. The public key must be in the armored format. If path is not specified, the default public key from the local GPG keyring is used. pgp-key delete Delete a PGP key from your account. pgp-key list [username] [options...] List PGP public keys. Options are: -r, --raw Only print raw public key show [username] Show a user's profile. If username is not specified, your profile is displayed. ssh-key create [path] Upload an SSH public key and associate it with your account. If path is not specified, the default SSH public key is used. ssh-key delete Delete an SSH public key from your account. ssh-key list [username] [options...] List SSH public keys. Options are: -r, --raw Only print raw public key update [options...] Update account. Options are: --bio Edit biography. --email Set Email address. --location Set location. --url Set URL. user-webhook create [options...] Create a user webhook. Options are: -e, --events List of events that should trigger the webhook (PROFILE_UPDATE, PGP_KEY_ADDED, PGP_KEY_REMOVED, SSH_KEY_ADDED, SSH_KEY_REMOVED). Required. --stdin Read query from stdin. -u, --url The payload URL which receives the POST request. Required. user-webhook delete Delete a user webhook. user-webhook list List user webhooks. pages list List registered sites. publish [file] [options...] Publish a website. The input file can be either a gzip tarball or a directory. If file is not specified, standard input is used. Options are: -d, --domain Fully qualified domain name. -p, --protocol Protocol to use (either HTTPS or GEMINI; defaults to HTTPS) --site-config Path to site configuration file (for e.g. cache-control). -s, --subdirectory If specified, only this subdirectory is updated, the rest of the site is left untouched. unpublish [options...] Unpublish a website. Options are: -d, --domain Fully qualified domain name. -p, --protocol Protocol to use (either HTTPS or GEMINI; defaults to HTTPS) user-webhook create [options...] Create a user webhook. Options are: -e, --events List of events that should trigger the webhook (SITE_PUBLISHED, SITE_UNPUBLISHED). Required. --stdin Read query from stdin. -u, --url The payload URL which receives the POST request. Required. user-webhook delete Delete a user webhook. user-webhook list List user webhooks. paste create Create a new paste. Options are: -v, --visibility Visibility to use (public, unlisted, private). Defaults to unlisted. -n, --name Name of the created paste. Only valid when reading from stdin. delete Delete pastes. list List pastes. show Display a paste. update [options...] Update a paste's visibility. Options are: -v, --visibility Visibility to use (public, unlisted, private) user-webhook create [options...] Create a user webhook. Options are: -e, --events List of events that should trigger the webhook (PASTE_CREATED, PASTE_UPDATED, PASTE_DELETED). Required. --stdin Read query from stdin. -u, --url The payload URL which receives the POST request. Required. user-webhook delete Delete a user webhook. user-webhook list List user webhooks. todo Options are: -t, --tracker Name of tracker. acl delete Delete an ACL entry. acl list [tracker] List ACL entries of a tracker. create [options...] Create a tracker. Options are: --stdin Read description from stdin. -v, --visibility Visibility to use (public, unlisted, private). Defaults to public. delete [tracker] [options...] Delete a tracker. Options are: -y, --yes Confirm deletion without prompt. label create [options...] Create a label. Options are: -b, --background Background color in hex format (required). -f, --foreground Foreground color in hex format. If omitted either black or white will be selected for an optimized contrast. label delete Delete a label. label list List labels. label update [options...] Update a label. Options are: -b, --background Background color in hex format. -f, --foreground Foreground color in hex format. -n, --name New label name. list [owner] List trackers. subscribe [tracker] Subscribe to a tracker. ticket assign [options...] Assign a user to a ticket. Options are: -u, --user Username of the new assignee (required). ticket comment [options...] Comment on a ticket. Options are: -r, --resolution Resolution for resolved tickets. If status is omitted, it will be set to RESOLVED. -s, --status New ticket status. If set to RESOLVED, resolution will default to CLOSED. --stdin Read comment from stdin. ticket create [options...] Create a new ticket. Options are: --stdin Read ticket from stdin. ticket delete [options...] Delete a ticket. Options are: -y, --yes Confirm deletion without prompt. ticket edit Edit a ticket. ticket label [options...] Add a label to a ticket. Options are: -l, --label Name of the label (required). ticket list [options...] List tickets. Options are: -s, --status Filter by ticket status. ticket show Display a ticket. ticket subscribe Subscribe to a ticket. ticket unassign [options...] Unassign a user from a ticket. Options are: -u, --user Username of the assignee (required). ticket unlabel [options...] Remove a label from a ticket. Options are: -l, --label Name of the label (required). ticket unsubscribe Unsubscribe from a ticket. ticket update-status [options...] Update status of a ticket. Options are: -r, --resolution Resolution for resolved tickets (required if status RESOLVED is used). If status is omitted, it will be set to RESOLVED. -s, --status New ticket status. ticket webhook create [options...] Create a ticket webhook. Options are: -e, --events List of events that should trigger the webhook (EVENT_CREATED, TICKET_UPDATE, TICKET_DELETED). Required. --stdin Read query from stdin. -u, --url The payload URL which receives the POST request. Required. ticket webhook delete Delete a ticket webhook. ticket webhook list List ticket webhooks. unsubscribe [tracker] Unsubscribe from a tracker. update [tracker] [options...] Update a tracker. Options are: --description Edit description. -v, --visibility Visibility to use (public, unlisted, private). user-webhook create [options...] Create a user webhook. Options are: -e, --events List of events that should trigger the webhook (TRACKER_CREATED, TRACKER_UPDATE, TRACKER_DELETED, TICKET_CREATED). Required. --stdin Read query from stdin. -u, --url The payload URL which receives the POST request. Required. user-webhook delete Delete a user webhook. user-webhook list List user webhooks. webhook create [tracker] [options...] Create a tracker webhook. Options are: -e, --events List of events that should trigger the webhook (TRACKER_UPDATE, TRACKER_DELETED, LABEL_CREATED, LABEL_UPDATE, LABEL_DELETED, TICKET_CREATED, TICKET_UPDATE, TICKET_DELETED, EVENT_CREATED). Required. --stdin Read query from stdin. -u, --url The payload URL which receives the POST request. Required. webhook delete Delete a tracker webhook. webhook list [tracker] List tracker webhooks. CONFIGURATION Generate a new OAuth2 access token on meta.sr.ht. On startup hut will look for a file at $XDG_CONFIG_HOME/hut/config. If unset, $XDG_CONFIG_HOME defaults to ~/.config/. instance "sr.ht" { access-token "" # As an alternative you can specify a command whose first line of output # will be parsed as the token access-token-cmd pass token meta { # You can set the origin for each service. As fallback hut will # construct the origin from the instance name and the service. origin "https://meta.sr.ht" } } Project configuration file The project configuration file is a top-level file called .hut.scfg in a repository, where the assosciated tracker and development mailing list can be specified. These resources will be used whenever a command is called which needs a tracker/mailing list and none is explicitly set. Furthermore it is possible to configure that patches should contain the repository name in their prefix. The hut git clone command will configure a freshly cloned repository to make contributing easier. tracker https://todo.sr.ht/~xenrox/hut development-mailing-list ~xenrox/hut-dev@lists.sr.ht patch-prefix false AUTHORS Originally written by Simon Ser . Currently maintained by Thorben Gunther , who is assisted by other open-source contributors. For more information about hut development, see . 2024-06-29 hut(1)