---
name: "hut"
section: "1"
platform: "linux"
package: "hut"
version: "0.9.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/hut"
---

# hut(1)

A CLI tool for sr.ht

## 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**

  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

**access-token**

Display the access token.

**help** \<command\>

Help about any command.

**graphql** \<service\>

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)](/jq/1.md) 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\>

  Set a file variable.

- **--stdin**

  Read query from *stdin*.

- **-v**, **--var** \<key\>=\<value\>

  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** \<directory\> \[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** \<directory...\>

Import account data.

**version**

Display hut version.

**completion** \<shell\>

Generate autocompletion script for either bash, fish, powershell or zsh.

### settings

Manage repo-specific hut settings, e.g. which resource (project, tracker, mailing list) is linked to a repo.

**show**

Show settings.

**update**

Update settings, e.g. in case a project swapped from a general purpose mailing list to a project specific one.

### builds

**artifacts** \<ID\>

List artifacts.

**artifact list** \<ID\>

List artifacts.

**artifact get** \<ID\> \<path\> \[options...\]

Get build artifact by its path.

Options are:

- **--output** \<file\>

  Path to write the artifact to. If unspecified, it is written to stdout.

**cancel** \<IDs...\>

Cancel jobs.

**list** \[owner\] \[options...\]

List jobs.

Options are:

- **--count** \<int\>

  Number of jobs to fetch.

- **-s**, **--status** \<string\>

  Filter by job status.

- **-t**, **--tags** \<string\>

  Only show jobs whose tags string starts with the provided value.

**resubmit** \<ID\>

Resubmit a build.

Options are:

- **-e**, **--edit**

  Edit manifest with *$EDITOR*.

- **-f**, **--follow**

  Follow build logs.

- **-n**, **--note** \<string\>

  Provide a short job description.

- **-s**, **--no-secrets**

  Disable secrets for this build.

- **-v**, **--visibility** \<string\>

  Visibility to use (public, unlisted, private). Defaults to the same visibility used by the original build job.

**secret list** \[options...\]

List secrets.

Options are:

- **--count** \<int\>

  Number of secrets to fetch.

**secret share** \<secret\>

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.

- **--web**

  Open in browser.

**ssh** \[ID\]

Connect with SSH to a job.

If no ID is specified, the latest running job will be used.

**submit** \[manifest...\] \[options...\]

Submit a build manifest.

If no build manifest is specified, build manifests are discovered at *.build.yml*, *.build.yaml*, *.builds/\*.yml* and *.builds/\*.yaml*.

Options are:

- **-e**, **--edit**

  Edit manifest with *$EDITOR*.

- **-f**, **--follow**

  Follow build logs.

- **-n**, **--note** \<string\>

  Provide a short job description.

- **-s**, **--no-secrets**

  Disable secrets for this build.

- **-t**, **--tags** \<string\>

  Slash separated tags (e.g. "hut/test").

- **-v**, **--visibility** \<string\>

  Visibility to use (public, unlisted, private). Defaults to unlisted.

**update** \<ID\> \[options...\]

Update a job.

Options are:

- **-v**, **--visibility** \<string\>

  Visibility to use (public, unlisted, private)

- **-t**, **--tags** \<string\>

  Tags to attach to the job

**user-webhook create** \[options...\]

Create a user webhook.

Options are:

- **-e**, **--events** \<strings...\>

  List of events that should trigger the webhook (JOB\_CREATED). Required.

- **--stdin**

  Read query from *stdin*.

- **-q**, **--query** \<string\>

  The webhook query. Exclusive with **--stdin**.

- **-u**, **--url** \<URL\>

  The payload URL which receives the *POST* request. Required.

**user-webhook show** \<ID\>

Show a user webhook.

**user-webhook delete** \<ID\>

Delete a user webhook.

**user-webhook list** \[options...\]

List user webhooks.

Options are:

- **--count** \<int\>

  Number of webhooks to fetch.

### git

Options are:

- **-r**, **--repo** \<string\>

  Name of repository.

**acl delete** \<ID\>

Delete an ACL entry.

**acl list** \[repo\] \[options...\]

List ACL entries of a repo. Defaults to current repo.

Options are:

- **--count** \<int\>

  Number of ACL entries to fetch.

**acl update** \<user\> \[options...\]

Update or add an ACL entry for user.

Options are:

- **-m**, **--mode** \<string\>

  Access mode to set (RW, RO).

**artifact delete** \<ID\>

Delete an artifact.

**artifact list** \[options...\]

List artifacts.

**artifact upload** \<filename...\> \[options...\]

Upload artifacts.

Options are:

- **--rev** \<string\>

  Revision tag. Defaults to the last Git tag.

**clone** \<repo\>

This will clone the repository to *CWD* and try to configure it for  *git send-email* if possible. "repo" can be either an (scp-like git) URL or a sourcehut resource ("hut", "~xenrox/hut").

**create** \<name\> \[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** \<string\>

  Description of the repository.

- **--import-url** \<url\>

  Import the repository from the given URL.

- **-v**, **--visibility** \<string\>

  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\] \[options...\]

List repositories.

Options are:

- **--count** \<int\>

  Number of repositories to fetch.

**setup** \[options...\]

Setup a repository for *git send-email*. hut will read the required settings from the project configuration file. If the repository already has some configuration, the setup will be skipped.

Options are:

- **-f**, **--force**

  Force the setup even if the repository is already configured for *git send-email*.

**show** \[repo\] \[options...\]

Display information about a repository.

Options are:

- **--web**

  Open in browser.

**update** \[repo\] \[options...\]

Update a repository. By default the current repo will be updated.

Options are:

- **-b**, **--default-branch** \<branch\>

  Set the default branch.

- **-d**, **--description** \<description\>

  Set one-line repository description.

- **-n**, **--name** \<string\>

  New repository name.

- **--readme** \<file\>

  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** \<string\>

  Visibility to use (public, unlisted, private).

**user-webhook create** \[options...\]

Create a user webhook.

Options are:

- **-e**, **--events** \<strings...\>

  List of events that should trigger the webhook (REPO\_CREATED, REPO\_UPDATE, REPO\_DELETED). Required.

- **--stdin**

  Read query from *stdin*.

- **-q**, **--query** \<string\>

  The webhook query. Exclusive with **--stdin**.

- **-u**, **--url** \<URL\>

  The payload URL which receives the *POST* request. Required.

**user-webhook show** \<ID\>

Show a user webhook.

**user-webhook delete** \<ID\>

Delete a user webhook.

**user-webhook list** \[options...\]

List user webhooks.

Options are:

- **--count** \<int\>

  Number of webhooks to fetch.

**webhook create** \[list\] \[options...\]

Create a git webhook.

Options are:

- **-e**, **--events** \<strings...\>

  List of events that should trigger the webhook (GIT\_PRE\_RECEIVE, GIT\_POST\_RECEIVE). Required.

- **--stdin**

  Read query from *stdin*.

- **-q**, **--query** \<string\>

  The webhook query. Exclusive with **--stdin**.

- **-u**, **--url** \<URL\>

  The payload URL which receives the *POST* request. Required.

**webhook show** \<ID\>

Show a git webhook.

**webhook delete** \<ID\>

Delete a git webhook.

**webhook list** \[repo\] \[options...\]

List git webhooks.

Options are:

- **--count** \<int\>

  Number of webhooks to fetch.

### hg

Options are:

- **-r**, **--repo** \<string\>

  Name of repository.

**acl delete** \<ID\>

Delete an ACL entry.

**acl list** \[repo\] \[options...\]

List ACL entries of a repo. Defaults to current repo.

Options are:

- **--count** \<int\>

  Number of ACL entries to fetch.

**acl update** \<user\> \[options...\]

Update or add an ACL entry for user.

Options are:

- **-m**, **--mode** \<string\>

  Access mode to set (RW, RO).

**create** \<name\> \[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** \<string\>

  Description of the repository.

- **-v**, **--visibility** \<string\>

  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\] \[options...\]

List repositories.

Options are:

- **--count** \<int\>

  Number of repositories to fetch.

**update** \[repo\] \[options...\]

Update a repository. By default the current repo will be updated.

Options are:

- **-d**, **--description** \<description\>

  Set one-line repository description.

- **--non-publishing** \<boolean\>

  Controls whether this repository is a non-publishing repository.

- **--readme** \<file\>

  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** \<string\>

  Visibility to use (public, unlisted, private).

**user-webhook create** \[options...\]

Create a user webhook.

Options are:

- **-e**, **--events** \<strings...\>

  List of events that should trigger the webhook (REPO\_CREATED, REPO\_UPDATE, REPO\_DELETED). Required.

- **--stdin**

  Read query from *stdin*.

- **-q**, **--query** \<string\>

  The webhook query. Exclusive with **--stdin**.

- **-u**, **--url** \<URL\>

  The payload URL which receives the *POST* request. Required.

**user-webhook show** \<ID\>

Show a user webhook.

**user-webhook delete** \<ID\>

Delete a user webhook.

**user-webhook list** \[options...\]

List user webhooks.

Options are:

- **--count** \<int\>

  Number of webhooks to fetch.

### hub

**create** \<name\> \[options...\]

Create a project.

Options are:

- **-d**, **--description** \<string\>

  Description of the project.

- **-t**, **--tags** \<string\>

  Comma separated tags (e.g. "foo,bar").

- **-v**, **--visibility** \<string\>

  Visibility to use (public, unlisted, private). Defaults to public.

**update** \[project\] \[options...\]

Update a project.

Options are:

- **-n**, **--name** \<string\>

  New project name.

- **-d**, **--description** \<string\>

  Description of the project.

- **-w**, **--website** \<string\>

  Website of the project.

- **-r**, **--readme** \<string\>

  Project README repository name.

- **-t**, **--tags** \<string\>

  Comma separated tags (e.g. "foo,bar").

- **-v**, **--visibility** \<string\>

  Visibility to use (public, unlisted, private). Defaults to public.

**delete** \<project\> \[options...\]

Delete a project.

Options are:

- **-y**, **--yes**

  Confirm deletion without prompt.

**link** \<project\> \[options...\]

Link an existing list/repository/tracker to a project. Only one resource can be linked at a time.

Options are:

- **-g**, **--gitrepo** \<string\>

  Name of the git repository to link.

- **-m**, **--hgrepo** \<string\>

  Name of the hg repository to link.

- **-l**, **--list** \<string\>

  Name of the mailing list to link.

- **-t**, **--tracker** \<string\>

  Name of the tracker to link.

**unlink** \<project\> \[options...\]

Unlink an existing list/repository/tracker from a project. Only one resource can be unlinked at a time.

Options are:

- **-g**, **--gitrepo** \<string\>

  Name of the git repository to unlink.

- **-m**, **--hgrepo** \<string\>

  Name of the hg repository to unlink.

- **-l**, **--list** \<string\>

  Name of the mailing list to unlink.

- **-t**, **--tracker** \<string\>

  Name of the tracker to unlink.

**list** \[owner\] \[options...\]

List projects.

Options are:

- **--count** \<int\>

  Number of projects to fetch.

**show** \[project\]

Display information about a project.

### lists

Options are:

- **-l**, **--mailing-list** \<name\>

  Select a mailing list.

  By default, the mailing list configured for the current Git repository will be selected.

**acl delete** \<ID\>

Delete an ACL entry.

**acl list** \[list\] \[options...\]

List ACL entries of a mailing list.

Options are:

- **--count** \<int\>

  Number of ACL entries to fetch.

**acl update** \<user\> \[options...\]

Update or add an ACL entry for user.

Options are:

- **-b**, **--browse**

  Permission to browse the mailing list.

- **-r**, **--reply**

  Permission to reply to messages in the mailing list.

- **-p**, **--post**

  Permission to post messages to the mailing list.

- **-m**, **--moderate**

  Permission to moderate the mailing list.

- **-y**, **--yes**

  Confirm update without summary.

**archive** \[list\] \[options...\]

Download a mailing list archive as an mbox file to *stdout*.

Options are:

- **-d**, **--days** \<int\>

  Number of last days for which the archive should be downloaded. By default the entire archive will be selected.

**create** \<name\> \[options...\]

Create a mailing list.

Options are:

- **--stdin**

  Read description from *stdin*.

- **-v**, **--visibility** \<string\>

  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\] \[options...\]

List mailing lists.

Options are:

- **--count** \<int\>

  Number of mailing lists to fetch.

**patchset apply** \<ID\>

Apply a patchset.

**patchset list** \[list\] \[options...\]

List patchsets in list.

Options are:

- **--count** \<int\>

  Number of patchsets to fetch.

- **-s**, **--status** \<string\>

  Filter by patchset status. By default only "PROPOSED" patchsets will be displayed. Use "" to show all patchsets.

- **-u**, **--user**

  List patchsets by user instead of by list.

**patchset show** \<ID\>

Show a patchset.

**patchset update** \<ID\>

Update a patchset.

Options are:

- **-s**, **--status** \<string\>

  Patchset status to set (required).

**preferences show**

Show user preferences for lists.

**preferences update** \[options...\]

Update user preferences for lists.

Options are:

- **-c**, **--copy-self** \<boolean\>

  Whether the user wishes to receive a copy of their own emails to mailings lists.

**subscribe** \[list\]

Subscribe to a mailing list.

**subscriptions** \[options...\]

List mailing list subscriptions.

Options are:

- **--count** \<int\>

  Number of subscriptions to fetch.

**unsubscribe** \[list\]

Unsubscribe from a mailing list.

**update** \[list\] \[options...\]

Update a mailing list.

Options are:

- **--description**

  Edit description.

- **-v**, **--visibility** \<string\>

  Visibility to use (public, unlisted, private).

**user-webhook create** \[options...\]

Create a user webhook.

Options are:

- **-e**, **--events** \<strings...\>

  List of events that should trigger the webhook (LIST\_CREATED, LIST\_UPDATED, LIST\_DELETED, EMAIL\_RECEIVED, PATCHSET\_RECEIVED). Required.

- **--stdin**

  Read query from *stdin*.

- **-q**, **--query** \<string\>

  The webhook query. Exclusive with **--stdin**.

- **-u**, **--url** \<URL\>

  The payload URL which receives the *POST* request. Required.

**user-webhook show** \<ID\>

Show a user webhook.

**user-webhook delete** \<ID\>

Delete a user webhook.

**user-webhook list** \[options...\]

List user webhooks.

Options are:

- **--count** \<int\>

  Number of webhooks to fetch.

**webhook create** \[list\] \[options...\]

Create a mailing list webhook.

Options are:

- **-e**, **--events** \<strings...\>

  List of events that should trigger the webhook (LIST\_UPDATED, LIST\_DELETED, EMAIL\_RECEIVED, PATCHSET\_RECEIVED). Required.

- **--stdin**

  Read query from *stdin*.

- **-q**, **--query** \<string\>

  The webhook query. Exclusive with **--stdin**.

- **-u**, **--url** \<URL\>

  The payload URL which receives the *POST* request. Required.

**webhook show** \<ID\>

Show a mailing list webhook.

**webhook delete** \<ID\>

Delete a mailing list webhook.

**webhook list** \[list\] \[options...\]

List mailing list webhooks.

Options are:

- **--count** \<int\>

  Number of webhooks to fetch.

### meta

**audit-log** \[options...\]

Display your audit log.

Options are:

- **--count** \<int\>

  Number of log entries to fetch.

**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** \<ID\>

Delete a PGP key from your account.

**pgp-key list** \[username\] \[options...\]

List PGP public keys.

Options are:

- **--count** \<int\>

  Number of keys to fetch.

- **-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** \<ID\>

Delete an SSH public key from your account.

**ssh-key list** \[username\] \[options...\]

List SSH public keys.

Options are:

- **--count** \<int\>

  Number of keys to fetch.

- **-r**, **--raw**

  Only print raw public key

**update** \[options...\]

Update account.

Options are:

- **--avatar**

  Set avatar.

- **--bio**

  Edit biography.

- **--email** \<string\>

  Set Email address.

- **--location** \<string\>

  Set location.

- **--pronouns** \<string\>

  Set pronouns.

- **--url** \<string\>

  Set URL.

**user-webhook create** \[options...\]

Create a user webhook.

Options are:

- **-e**, **--events** \<strings...\>

  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*.

- **-q**, **--query** \<string\>

  The webhook query. Exclusive with **--stdin**.

- **-u**, **--url** \<URL\>

  The payload URL which receives the *POST* request. Required.

**user-webhook show** \<ID\>

Show a user webhook.

**user-webhook delete** \<ID\>

Delete a user webhook.

**user-webhook list** \[options...\]

List user webhooks.

Options are:

- **--count** \<int\>

  Number of webhooks to fetch.

### pages

**acl delete** \<ID\>

Delete an ACL entry.

**acl list** \[options...\]

List ACL entries of a site.

Options are:

- **--count** \<int\>

  Number of ACL entries to fetch.

- **-d**, **--domain** \<string\>

  Fully qualified domain name. Required.

- **-p**, **--protocol** \<string\>

  Protocol to use (either HTTPS or GEMINI; defaults to HTTPS).

**acl update** \<user\> \[options...\]

Update an ACL entry for user.

Options are:

- **--id** \<ID\>

  ID of the site.

- **--publish**

  Permission to publish the site. Leave this flag out to remove the permission.

**list** \[options...\]

List registered sites.

Options are:

- **--count** \<int\>

  Number of sites to fetch.

**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** \<string\>

  Fully qualified domain name.

- **-p**, **--protocol** \<string\>

  Protocol to use (either HTTPS or GEMINI; defaults to HTTPS)

- **--site-config** \<string\>

  Path to site configuration file (for e.g. cache-control).

- **-s**, **--subdirectory** \<string\>

  If specified, only this subdirectory is updated, the rest of the site is left untouched.

**unpublish** \[options...\]

Unpublish a website.

Options are:

- **-d**, **--domain** \<string\>

  Fully qualified domain name.

- **-p**, **--protocol** \<string\>

  Protocol to use (either HTTPS or GEMINI; defaults to HTTPS)

**user-webhook create** \[options...\]

Create a user webhook.

Options are:

- **-e**, **--events** \<strings...\>

  List of events that should trigger the webhook (SITE\_PUBLISHED, SITE\_UNPUBLISHED). Required.

- **--stdin**

  Read query from *stdin*.

- **-q**, **--query** \<string\>

  The webhook query. Exclusive with **--stdin**.

- **-u**, **--url** \<URL\>

  The payload URL which receives the *POST* request. Required.

**user-webhook show** \<ID\>

Show a user webhook.

**user-webhook delete** \<ID\>

Delete a user webhook.

**user-webhook list** \[options...\]

List user webhooks.

Options are:

- **--count** \<int\>

  Number of webhooks to fetch.

### paste

**create** \<filenames...\>

Create a new paste.

Options are:

- **-v**, **--visibility** \<string\>

  Visibility to use (public, unlisted, private). Defaults to unlisted.

- **-n**, **--name** \<string\>

  Name of the created paste. Only valid when reading from stdin.

**delete** \<IDs...\>

Delete pastes.

**list** \[options...\]

List pastes.

Options are:

- **--count** \<int\>

  Number of pastes to fetch.

**show** \<ID\>

Display a paste.

**update** \<ID\> \[options...\]

Update a paste's visibility.

Options are:

- **-v**, **--visibility** \<string\>

  Visibility to use (public, unlisted, private)

**user-webhook create** \[options...\]

Create a user webhook.

Options are:

- **-e**, **--events** \<strings...\>

  List of events that should trigger the webhook (PASTE\_CREATED, PASTE\_UPDATED, PASTE\_DELETED). Required.

- **--stdin**

  Read query from *stdin*.

- **-q**, **--query** \<string\>

  The webhook query. Exclusive with **--stdin**.

- **-u**, **--url** \<URL\>

  The payload URL which receives the *POST* request. Required.

**user-webhook show** \<ID\>

Show a user webhook.

**user-webhook delete** \<ID\>

Delete a user webhook.

**user-webhook list** \[options...\]

List user webhooks.

Options are:

- **--count** \<int\>

  Number of webhooks to fetch.

### todo

Options are:

- **-t**, **--tracker** \<string\>

  Name of tracker.

**acl delete** \<ID\>

Delete an ACL entry.

**acl list** \[tracker\] \[options...\]

List ACL entries of a tracker.

Options are:

- **--count** \<int\>

  Number of ACL entries to fetch.

**acl update** \<user\> \[options...\]

Update or add an ACL entry for user.

Options are:

- **-b**, **--browse**

  Permission to browse tickets.

- **-s**, **--submit**

  Permission to submit new tickets.

- **-c**, **--comment**

  Permission to comment on tickets.

- **-e**, **--edit**

  Permission to edit tickets.

- **-g**, **--triage**

  Permission to triage tickets.

- **-y**, **--yes**

  Confirm update without summary.

**create** \<name\> \[options...\]

Create a tracker.

Options are:

- **--stdin**

  Read description from *stdin*.

- **-v**, **--visibility** \<string\>

  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** \<name\> \[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** \<name\>

Delete a label.

**label list** \[options...\]

List labels.

Options are:

- **--count** \<int\>

  Number of labels to fetch.

**label update** \<name\> \[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\] \[options...\]

List trackers.

Options are:

- **--count** \<int\>

  Number of trackers to fetch.

**preferences show**

Show user preferences for trackers.

**preferences update** \[options...\]

Update user preferences for trackers.

Options are:

- **-n**, **--notify-self** \<boolean\>

  Whether the user wishes to be notified of their own actions.

**subscribe** \[tracker\]

Subscribe to a tracker.

**ticket assign** \<ID\> \[options...\]

Assign a user to a ticket.

Options are:

- **-u**, **--user**

  Username of the new assignee (required).

**ticket comment** \<ID\> \[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** \<ID\> \[options...\]

Delete a ticket.

Options are:

- **-y**, **--yes**

  Confirm deletion without prompt.

**ticket edit** \<ID\> \[options...\]

Edit a ticket.

Options are:

- **--stdin**

  Read ticket from *stdin*.

**ticket label** \<ID\> \[options...\]

Add a label to a ticket.

Options are:

- **-l**, **--label** \<name\>

  Name of the label (required).

**ticket list** \[options...\]

List tickets.

Options are:

- **--count** \<int\>

  Number of tickets to fetch.

- **-s**, **--status** \<string\>

  Filter by ticket status. By default only open tickets will be displayed. Use "" to show all tickets.

**ticket show** \<ID\> \[options...\]

Display a ticket.

Options are:

- **--web**

  Open in browser.

**ticket subscribe** \<ID\>

Subscribe to a ticket.

**ticket unassign** \<ID\> \[options...\]

Unassign a user from a ticket.

Options are:

- **-u**, **--user**

  Username of the assignee (required).

**ticket unlabel** \<ID\> \[options...\]

Remove a label from a ticket.

Options are:

- **-l**, **--label** \<name\>

  Name of the label (required).

**ticket unsubscribe** \<ID\>

Unsubscribe from a ticket.

**ticket update-status** \<ID\> \[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** \<ID\> \[options...\]

Create a ticket webhook.

Options are:

- **-e**, **--events** \<strings...\>

  List of events that should trigger the webhook (EVENT\_CREATED, TICKET\_UPDATE, TICKET\_DELETED). Required.

- **--stdin**

  Read query from *stdin*.

- **-q**, **--query** \<string\>

  The webhook query. Exclusive with **--stdin**.

- **-u**, **--url** \<URL\>

  The payload URL which receives the *POST* request. Required.

**ticket webhook delete** \<ID\>

Delete a ticket webhook.

**ticket webhook list** \<ID\> \[options...\]

List ticket webhooks.

Options are:

- **--count** \<int\>

  Number of webhooks to fetch.

**unsubscribe** \[tracker\]

Unsubscribe from a tracker.

**update** \[tracker\] \[options...\]

Update a tracker.

Options are:

- **--description**

  Edit description.

- **-n**, **--name** \<string\>

  New tracker name.

- **-v**, **--visibility** \<string\>

  Visibility to use (public, unlisted, private).

**user-webhook create** \[options...\]

Create a user webhook.

Options are:

- **-e**, **--events** \<strings...\>

  List of events that should trigger the webhook (TRACKER\_CREATED, TRACKER\_UPDATE, TRACKER\_DELETED, TICKET\_CREATED). Required.

- **--stdin**

  Read query from *stdin*.

- **-q**, **--query** \<string\>

  The webhook query. Exclusive with **--stdin**.

- **-u**, **--url** \<URL\>

  The payload URL which receives the *POST* request. Required.

**user-webhook show** \<ID\>

Show a user webhook.

**user-webhook delete** \<ID\>

Delete a user webhook.

**user-webhook list** \[options...\]

List user webhooks.

Options are:

- **--count** \<int\>

  Number of webhooks to fetch.

**webhook create** \[tracker\] \[options...\]

Create a tracker webhook.

Options are:

- **-e**, **--events** \<strings...\>

  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*.

- **-q**, **--query** \<string\>

  The webhook query. Exclusive with **--stdin**.

- **-u**, **--url** \<URL\>

  The payload URL which receives the *POST* request. Required.

**webhook show** \<ID\>

Show a tracker webhook.

**webhook delete** \<ID\>

Delete a tracker webhook.

**webhook list** \[tracker\] \[options...\]

List tracker webhooks.

Options are:

- **--count** \<int\>

  Number of webhooks to fetch.

## 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\>.