..
  This file is part of PEPSI.
  Copyright (C) 2026 Pepsi contributors

  PEPSI is free software; you can redistribute it and/or modify it under the
  terms of the GNU Affero General Public License as published by the Free
  Software Foundation; either version 3, or (at your option) any later version.

==============
pepsi-settings
==============

*Manage per-address stage option overrides.*

Role
====

``pepsi-settings`` is the operator's tool for the ``pepsi.settings`` table,
which overrides a stage's ``[stage-<name>]`` options for messages to or from a
particular envelope address (the INI value remains the default). It connects
through the shared ``[pepsi-postgres]`` section and has no configuration of its
own. The table is consulted transparently by the stage scaffolding (see
:doc:`pepsi-dispatch`); this tool lets an administrator edit rows directly. It is
**not** a stage. Started as ``root`` it continues as the ``pepsi`` service
account before connecting (after reading the configuration and any ``import``
input file), so no ``sudo -u pepsi`` is needed.
Reference: :manpage:`pepsi-settings(1)`.

Each row maps one lower-cased envelope address to a JSON object
``{ "stage-<name>": { OPTION: value, … } }``. The relevant address is the
envelope **sender** for locally-originated mail (``state.local_origin``),
otherwise an envelope **recipient**, matched exactly. When one inbound message's
recipients resolve to different overrides for the stage about to run, the
pipeline splits it into one row per distinct override group.

Features
========

* **set** *ADDRESS STAGE OPTION VALUE* — set one option override (the stage label
  is stored as the section key ``stage-<name>``; the value is parsed by the stage
  like its INI value).
* **unset** *ADDRESS STAGE* [*OPTION*] — remove one option, or the whole stage
  section; empty sections and rows are dropped automatically.
* **import** *ADDRESS SOURCE* — replace an address's whole object from a JSON file
  (``-`` for standard input).
* **get** / **list** — print one address's settings, or all rows (``--json``).
* **remove** — delete an address's row entirely.

:doc:`pepsi-setup` validates the table after installing the schema: top-level
keys must be real ``[stage-<name>]`` sections and option values must be JSON
scalars.

See also
========

:doc:`pepsi-dispatch`, :doc:`pepsi-stage-check-whitelist`,
:doc:`pepsi-stage-edit-settings`,
:doc:`pepsi-setup`, :doc:`../architecture`, :manpage:`pepsi-settings(1)`,
:manpage:`pepsi.conf(5)`.