Metadata-Version: 2.4
Name: il-postino
Version: 0.1.0
Summary: Typed Python CLI for administering Postfix + Dovecot mail servers (PostfixAdmin schema). Pluggable identity backend.
Project-URL: Homepage, https://github.com/vjt/postino
Project-URL: Issues, https://github.com/vjt/postino/issues
Author-email: Marcello Barnaba <marcello.barnaba@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Email
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: bcrypt<5,>=4.0
Requires-Dist: email-validator>=2.2
Requires-Dist: passlib>=1.7
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic>=2.7
Requires-Dist: pymysql>=1.1
Requires-Dist: rich>=13.7
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pyright>=1.1.370; extra == 'dev'
Requires-Dist: pytest-freezer>=0.4; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# postino

CLI tool to administer a Postfix + Dovecot mail server with the
PostfixAdmin SQL schema as user/alias/domain backend.

Pluggable identity backend (local password column or external IdP via
Zitadel/SCIM). Built for FreeBSD mail hosts but portable.

## Status

MVP shipping. Design spec: [`docs/superpowers/specs/2026-05-09-postino-design.md`](docs/superpowers/specs/2026-05-09-postino-design.md).

Requires Python 3.13+.

## Install

```sh
pipx install il-postino
```

Import name remains `postino`. The PyPI distribution is published as
`il-postino` because the bare `postino` name is squatted by an unrelated
2017 package.

### From git (mail host / production)

```sh
git clone https://github.com/vjt/postino.git /usr/local/src/postino
cd /usr/local/src/postino
python3.13 -m venv .venv
. .venv/bin/activate
pip install .
ln -s /usr/local/src/postino/.venv/bin/postino /usr/local/bin/postino

# update later: cd /usr/local/src/postino && git pull && .venv/bin/pip install .
```

## Usage

```sh
# All commands inherit POSTINO_* env vars or read /usr/local/etc/postino/postino.toml

postino domain add example.com --max-mailboxes 100 --default-quota 5G
postino user add foo@example.com --password 'hunter2' --name "Foo Bar" --quota 5G
postino user list --domain example.com --json
postino alias add foo@example.com forwarded@elsewhere.test
postino quota show foo@example.com
postino check
postino status
```

## Configuration

postino reads `/usr/local/etc/postino/postino.toml`. Example:

```toml
identity_backend = "local"
postfix_sql_dir = "/usr/local/etc/postfix"
virtual_mailbox_base = "/srv/mail"
postcreation_hook = "/usr/local/sbin/postfixadmin-mailbox-postcreation.sh"
vmail_uid = 1006
vmail_gid = 1006
default_password_scheme = "BLF-CRYPT"
default_quota_bytes = 1073741824
```

DB credentials are NOT duplicated here — postino parses
`/usr/local/etc/postfix/sql-virtual_mailbox_maps.cf` to extract them.

## Development

Set up a test MySQL/MariaDB schema (see
`docs/superpowers/plans/2026-05-09-postino-mvp.md` § Test Database
Prerequisites for the DDL), then:

```sh
python3.13 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
export POSTINO_TEST_DB_URL='mysql+pymysql://postino_test:postino_test_dev@localhost/postino_test'
./scripts/check.sh
```

## License

MIT — see [LICENSE](LICENSE).
