Metadata-Version: 2.5
Name: hmailserver-cli
Version: 6.3.7
Summary: hmctl: administer an hMailServer over its REST API from a command line
Keywords: hmailserver,mail server,smtp,imap,rest,administration,cli
Author: Christopher Holloway / Progressive Robot Ltd
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-Expression: AGPL-3.0-or-later
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Communications :: Email :: Mail Transport Agents
Classifier: Topic :: System :: Systems Administration
License-File: LICENSE
Project-URL: Changelog, https://gitlab.com/hmailserver/hmailserver/-/blob/master/CHANGELOG.md
Project-URL: Documentation, https://gitlab.com/hmailserver/hmailserver/-/blob/master/hmailserver/docs/CommandLine.md
Project-URL: Homepage, https://gitlab.com/hmailserver/hmailserver
Project-URL: Issues, https://gitlab.com/hmailserver/hmailserver/-/issues
Project-URL: Source, https://gitlab.com/hmailserver/hmailserver
Import-Name: hmailserver_cli

hmailserver-cli
===============

`hmctl`, the command-line client of [hMailServer](https://gitlab.com/hmailserver/hmailserver):
administer an hMailServer - on Windows or on Linux, on this machine or another -
over its REST API, from any shell.

It is the same `hmctl` the server's Linux packages install as `/usr/bin/hmctl`,
built from the same file, at the server's version. It is one module with nothing
behind it but the Python standard library: installing it fetches nothing else, and
it runs no code when it is installed.

Install
-------

```sh
pipx install hmailserver-cli
```

or `python -m pip install hmailserver-cli` into an environment of your own. Python
3.8 or later.

Use
---

The server's REST listener must be on. It is off until an administrator turns it
on, which `hmctl` cannot do, since it needs the listener itself: on a Linux server,
`sudo hmailserver --set-setting RestApiPort=8045` and a restart
([CommandLine.md](https://gitlab.com/hmailserver/hmailserver/-/blob/master/hmailserver/docs/CommandLine.md)
says more).

```sh
export HMAIL_URL=https://mail.example.com:8045
export HMAIL_API_KEY="$(cat ~/.config/hmailserver/api.key)"
hmctl domain list
hmctl account list --domain example.com
hmctl queue list
hmctl api GET /api/v1/status
```

Credentials, in the order they are looked for: `--api-key` or `HMAIL_API_KEY` (an
API key, sent as a bearer token); `--password` or `HMAIL_PASSWORD`, and
`--password-file` or `HMAIL_PASSWORD_FILE` (the administrator password, sent as
HTTP Basic); otherwise a prompt, when there is a console to answer it. An API key is
the better answer for anything unattended: it can be read-only, limited to one
domain, and revoked without changing the administrator password.

`--insecure` accepts a certificate nobody verified, and is refused for any host but
the loopback address.

Run `hmctl` with no arguments for the resources, `hmctl <resource> --help` for one
resource's verbs, and `hmctl api` for any method on any path.

More
----

- [Administering the server from a command line](https://gitlab.com/hmailserver/hmailserver/-/blob/master/hmailserver/docs/CommandLine.md):
  every resource and verb, and the PowerShell module that speaks the same vocabulary.
- [The command-line packages](https://gitlab.com/hmailserver/hmailserver/-/blob/master/hmailserver/docs/CommandLinePackages.md):
  how this package is built and published.
- Licence: AGPL-3.0-or-later.

