| 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:
- "hut"
- "~emersion/hut"
- "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:
- •
- 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.
- •
- Otherwise, if option --stdin is specified to the command, hut reads input from stdin.
- •
- Otherwise, hut assumes to run in a terminal and starts the command provided by environment variable $EDITOR to read input.
It is recommended to install git alongside hut. git is used by multiple commands, for example to determine which mailing list is connected to a git repository.
hut can link a git repository to a project, tracker and mailing list. You can execute a hut command that operates on one of the resources mentioned above from inside a repository while not explicitly passing the required resource to hut. In this case hut tries to match the repository to a resource through the project hub. These are then cached inside the repository's git config (hut.project, hut.tracker, sendemail.to). You can interact with these settings through hut's settings command or directly with git.
OPTIONS
-h, --help
--config
--debug
--instance
COMMANDS
access-token
help <command>
graphql <service>
A tool like jq(1) can be used to prettify the output and process the data. Example:
hut graphql meta <<EOF | jq '.me'
query {
me { canonicalName }
}
EOF
Options are:
--file <key>=<value>
--stdin
-v, --var <key>=<value>
hut graphql meta -v username=emersion <<'EOF'
query($username: String!) {
userByName(username: $username) {
bio
}
}
EOF
init
export <directory> [resource|service...]
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 <directory...>
version
completion <shell>
settings
show
update
builds
artifacts <ID>
artifact list <ID>
artifact get <ID> <path> [options...]
Options are:
--output <file>
cancel <IDs...>
list [owner] [options...]
Options are:
--count <int>
-s, --status <string>
-t, --tags <string>
resubmit <ID>
Options are:
-e, --edit
-f, --follow
-n, --note <string>
-s, --no-secrets
-v, --visibility <string>
secret list [options...]
Options are:
--count <int>
secret share <secret>
Options are:
-u, --user
show [ID] [options...]
If no ID is specified, the latest build will be printed.
Options are:
-f, --follow
--web
ssh [ID]
If no ID is specified, the latest running job will be used.
submit [manifest...] [options...]
If no build manifest is specified, build manifests are discovered at .build.yml, .build.yaml, .builds/*.yml and .builds/*.yaml.
Options are:
-e, --edit
-f, --follow
-n, --note <string>
-s, --no-secrets
-t, --tags <string>
-v, --visibility <string>
update <ID> [options...]
Options are:
-v, --visibility <string>
-t, --tags <string>
user-webhook create [options...]
Options are:
-e, --events <strings...>
--stdin
-q, --query <string>
-u, --url <URL>
user-webhook show <ID>
user-webhook delete <ID>
user-webhook list [options...]
Options are:
--count <int>
git
Options are:
acl delete <ID>
acl list [repo] [options...]
Options are:
--count <int>
acl update <user> [options...]
Options are:
-m, --mode <string>
artifact delete <ID>
artifact list [options...]
artifact upload <filename...> [options...]
Options are:
--rev <string>
clone <repo>
create <name> [options...]
Options are:
-c, --clone
-d, --description <string>
--import-url <url>
-v, --visibility <string>
delete [repo] [options...]
Options are:
-y, --yes
list [owner] [options...]
Options are:
--count <int>
setup [options...]
Options are:
-f, --force
show [repo] [options...]
Options are:
--web
update [repo] [options...]
Options are:
-b, --default-branch <branch>
-d, --description <description>
-n, --name <string>
--readme <file>
-v, --visibility <string>
user-webhook create [options...]
Options are:
-e, --events <strings...>
--stdin
-q, --query <string>
-u, --url <URL>
user-webhook show <ID>
user-webhook delete <ID>
user-webhook list [options...]
Options are:
--count <int>
webhook create [list] [options...]
Options are:
-e, --events <strings...>
--stdin
-q, --query <string>
-u, --url <URL>
webhook show <ID>
webhook delete <ID>
webhook list [repo] [options...]
Options are:
--count <int>
hg
Options are:
acl delete <ID>
acl list [repo] [options...]
Options are:
--count <int>
acl update <user> [options...]
Options are:
-m, --mode <string>
create <name> [options...]
Options are:
-c, --clone
-d, --description <string>
-v, --visibility <string>
delete [repo] [options...]
Options are:
-y, --yes
list [owner] [options...]
Options are:
--count <int>
update [repo] [options...]
Options are:
-d, --description <description>
--non-publishing <boolean>
--readme <file>
-v, --visibility <string>
user-webhook create [options...]
Options are:
-e, --events <strings...>
--stdin
-q, --query <string>
-u, --url <URL>
user-webhook show <ID>
user-webhook delete <ID>
user-webhook list [options...]
Options are:
--count <int>
hub
create <name> [options...]
Options are:
-d, --description <string>
-t, --tags <string>
-v, --visibility <string>
update [project] [options...]
Options are:
-n, --name <string>
-d, --description <string>
-w, --website <string>
-r, --readme <string>
-t, --tags <string>
-v, --visibility <string>
delete <project> [options...]
Options are:
-y, --yes
link <project> [options...]
Options are:
-g, --gitrepo <string>
-m, --hgrepo <string>
-l, --list <string>
-t, --tracker <string>
unlink <project> [options...]
Options are:
-g, --gitrepo <string>
-m, --hgrepo <string>
-l, --list <string>
-t, --tracker <string>
list [owner] [options...]
Options are:
--count <int>
show [project]
lists
Options are:
By default, the mailing list configured for the current Git repository will be selected.
acl delete <ID>
acl list [list] [options...]
Options are:
--count <int>
acl update <user> [options...]
Options are:
-b, --browse
-r, --reply
-p, --post
-m, --moderate
-y, --yes
archive [list] [options...]
Options are:
-d, --days <int>
create <name> [options...]
Options are:
--stdin
-v, --visibility <string>
delete [list] [options...]
Options are:
-y, --yes
list [owner] [options...]
Options are:
--count <int>
patchset apply <ID>
patchset list [list] [options...]
Options are:
--count <int>
-s, --status <string>
-u, --user
patchset show <ID>
patchset update <ID>
Options are:
-s, --status <string>
preferences show
preferences update [options...]
Options are:
-c, --copy-self <boolean>
subscribe [list]
subscriptions [options...]
Options are:
--count <int>
unsubscribe [list]
update [list] [options...]
Options are:
--description
-v, --visibility <string>
user-webhook create [options...]
Options are:
-e, --events <strings...>
--stdin
-q, --query <string>
-u, --url <URL>
user-webhook show <ID>
user-webhook delete <ID>
user-webhook list [options...]
Options are:
--count <int>
webhook create [list] [options...]
Options are:
-e, --events <strings...>
--stdin
-q, --query <string>
-u, --url <URL>
webhook show <ID>
webhook delete <ID>
webhook list [list] [options...]
Options are:
--count <int>
meta
audit-log [options...]
Options are:
--count <int>
oauth tokens
pgp-key create [path]
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 <ID>
pgp-key list [username] [options...]
Options are:
--count <int>
-r, --raw
show [username]
If username is not specified, your profile is displayed.
ssh-key create [path]
If path is not specified, the default SSH public key is used.
ssh-key delete <ID>
ssh-key list [username] [options...]
Options are:
--count <int>
-r, --raw
update [options...]
Options are:
--avatar
--bio
--email <string>
--location <string>
--pronouns <string>
--url <string>
user-webhook create [options...]
Options are:
-e, --events <strings...>
--stdin
-q, --query <string>
-u, --url <URL>
user-webhook show <ID>
user-webhook delete <ID>
user-webhook list [options...]
Options are:
--count <int>
pages
acl delete <ID>
acl list [options...]
Options are:
--count <int>
-d, --domain <string>
-p, --protocol <string>
acl update <user> [options...]
Options are:
--id <ID>
--publish
list [options...]
Options are:
--count <int>
publish [file] [options...]
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 <string>
-p, --protocol <string>
--site-config <string>
-s, --subdirectory <string>
unpublish [options...]
Options are:
-d, --domain <string>
-p, --protocol <string>
user-webhook create [options...]
Options are:
-e, --events <strings...>
--stdin
-q, --query <string>
-u, --url <URL>
user-webhook show <ID>
user-webhook delete <ID>
user-webhook list [options...]
Options are:
--count <int>
paste
create <filenames...>
Options are:
-v, --visibility <string>
-n, --name <string>
delete <IDs...>
list [options...]
Options are:
--count <int>
show <ID>
update <ID> [options...]
Options are:
-v, --visibility <string>
user-webhook create [options...]
Options are:
-e, --events <strings...>
--stdin
-q, --query <string>
-u, --url <URL>
user-webhook show <ID>
user-webhook delete <ID>
user-webhook list [options...]
Options are:
--count <int>
todo
Options are:
acl delete <ID>
acl list [tracker] [options...]
Options are:
--count <int>
acl update <user> [options...]
Options are:
-b, --browse
-s, --submit
-c, --comment
-e, --edit
-g, --triage
-y, --yes
create <name> [options...]
Options are:
--stdin
-v, --visibility <string>
delete [tracker] [options...]
Options are:
-y, --yes
label create <name> [options...]
Options are:
-b, --background
-f, --foreground
label delete <name>
label list [options...]
Options are:
--count <int>
label update <name> [options...]
Options are:
-b, --background
-f, --foreground
-n, --name
list [owner] [options...]
Options are:
--count <int>
preferences show
preferences update [options...]
Options are:
-n, --notify-self <boolean>
subscribe [tracker]
ticket assign <ID> [options...]
Options are:
-u, --user
ticket comment <ID> [options...]
Options are:
-r, --resolution
-s, --status
--stdin
ticket create [options...]
Options are:
--stdin
ticket delete <ID> [options...]
Options are:
-y, --yes
ticket edit <ID> [options...]
Options are:
--stdin
ticket label <ID> [options...]
Options are:
-l, --label <name>
ticket list [options...]
Options are:
--count <int>
-s, --status <string>
ticket show <ID> [options...]
Options are:
--web
ticket subscribe <ID>
ticket unassign <ID> [options...]
Options are:
-u, --user
ticket unlabel <ID> [options...]
Options are:
-l, --label <name>
ticket unsubscribe <ID>
ticket update-status <ID> [options...]
Options are:
-r, --resolution
-s, --status
ticket webhook create <ID> [options...]
Options are:
-e, --events <strings...>
--stdin
-q, --query <string>
-u, --url <URL>
ticket webhook delete <ID>
ticket webhook list <ID> [options...]
Options are:
--count <int>
unsubscribe [tracker]
update [tracker] [options...]
Options are:
--description
-n, --name <string>
-v, --visibility <string>
user-webhook create [options...]
Options are:
-e, --events <strings...>
--stdin
-q, --query <string>
-u, --url <URL>
user-webhook show <ID>
user-webhook delete <ID>
user-webhook list [options...]
Options are:
--count <int>
webhook create [tracker] [options...]
Options are:
-e, --events <strings...>
--stdin
-q, --query <string>
-u, --url <URL>
webhook show <ID>
webhook delete <ID>
webhook list [tracker] [options...]
Options are:
--count <int>
CONFIGURATION
Generate a new OAuth2 access token on meta.sr.ht. Note that many commands use helper functions that require the PROFILE:RO grant of their respective service.
On startup hut will look for a file at $XDG_CONFIG_HOME/hut/config on Unix. If unset, $XDG_CONFIG_HOME defaults to ~/.config/. On Darwin/macOS the file is at $HOME/Library/Application Support/hut/config.
instance "sourcehut" {
# Set the origin/common domain for the instance.
origin "sr.ht"
access-token "<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 <contact@emersion.fr>. Currently maintained by Thorben Günther <admin@xenrox.net>, who is assisted by other open-source contributors. For more information about hut development, see https://sr.ht/~xenrox/hut.
| 2026-10-20 |