Configuration

Configuration#

Configuration file#

Profiles live in a TOML file. The first of these locations that is set wins.

$PLONE_CLIENT_CONFIG
$XDG_CONFIG_HOME/plone-client/config.toml
~/.config/plone-client/config.toml

current = "local"

[defaults]
timeout = 60
retries = 5

[profiles.local]
url = "http://localhost:8080/Plone"
username = "admin"
auth = "jwt"
retries = 0

[profiles.prod]
url = "https://example.org"
username = "editor"
read_only = true
secret = "command"
secret_command = "op read op://Private/example/password"
verify = "/etc/ssl/certs/example-ca.pem"

[groups]
customer = ["prod", "local"]

Key	Meaning
`current`	Name of the profile used when no other one is selected.
`defaults`	Connection settings shared by every profile; see below.
`profiles.<name>`	One table per profile; see below.
`groups`	Named lists of profiles; see below.

The file never holds a secret.

Profile settings#

Key	Type	Default	Meaning
`url`	string	required	URL of the site root.
`username`	string	`""`	Login name; empty for anonymous access.
`auth`	`basic`, `jwt`, or `token`	`basic`	How the client authenticates; `token` sends the secret as a JWT.
`secret`	`keyring`, `env`, `command`, or `none`	`keyring`	Where the secret is kept.
`secret_env`	string	`PLONE_CLIENT_PASSWORD`	Variable holding the secret, with `secret = "env"`.
`secret_command`	string	`""`	Command printing the secret, with `secret = "command"`; run without a shell.
`read_only`	boolean	`false`	Refuse every request that could change the site.
`timeout`	number	`30.0`	Seconds to wait for the site; must be greater than zero.
`verify`	boolean or string	`true`	Verify TLS certificates. A string is the path of a CA bundle, a file or a directory, used instead of the default certificates; `~` is expanded.
`retries`	integer	`3`	Times a request is repeated after a network error, or after a `429`, `502`, `503`, or `504` answer to a request that is safe to repeat. `0` turns retries off.
`backoff`	number	`0.5`	Base delay in seconds between retries; it doubles after each one.
`api_prefix`	string	`++api++`	Traversal prefix of the REST API.
`frontend_url`	string	`""`	URL of the Volto frontend, for the services Volto serves itself, such as `@blocks-schema`. Empty means `url`, which is right when `url` is the frontend.
`description`	string	`""`	Free text, shown by `plone-client profile list` and by the MCP server’s `list_sites` tool.

Profile names start with a letter or a digit and contain only letters, digits, _, ., and -.

Defaults#

The defaults table sets connection settings for every profile. A profile’s own value wins over it.

Key	Allowed
`timeout`, `verify`, `retries`, `backoff`, `api_prefix`, `read_only`	Yes
Any other key	No; the file is refused.

When the configuration file is saved, a profile does not repeat a value equal to the defaults, so it follows later changes to them.

Groups#

The groups table names lists of profiles, which plone-client mcp --group serves together; see Several sites. Each key is a group name, and each value is a list of profile names.

Group names follow the rules of profile names.
A group must list at least one profile, and every profile it lists must exist; otherwise the file is refused.
A profile listed twice counts once.
Removing a profile removes it from its groups, and removes a group left empty.

plone-client profile groups, profile group-set, and profile group-remove change the table.

Secrets in the keyring#

Field	Value
Service	`plone-client:<profile>`
Account	The profile’s `username`, or `token` for a token profile without one

The keyring is the operating system’s own: macOS Keychain, Windows Credential Locker, or Secret Service on Linux.

Project file#

A .plone-client.toml file in the working directory, or in one of its parents, selects the profile for everything run below it.

profile = "blog"

Profile selection#

Order	Source
1	`-p`, `--profile`, or the `name` passed to `from_profile()`
2	`$PLONE_CLIENT_PROFILE`
3	`.plone-client.toml`
4	`current` in the configuration file

The command line skips profiles when given --url, or when $PLONE_CLIENT_URL is set and no profile was named by --profile or $PLONE_CLIENT_PROFILE. It then reads the settings from the environment variables below.

Environment variables#

from_env() reads these variables, with the prefix PLONE_CLIENT_ unless given another.

Variable	Meaning
`PLONE_CLIENT_URL`	URL of the site root; required.
`PLONE_CLIENT_USERNAME`	Login name; `PLONE_CLIENT_USER` is read when it is not set.
`PLONE_CLIENT_PASSWORD`	Password.
`PLONE_CLIENT_TOKEN`	A JWT issued beforehand.
`PLONE_CLIENT_AUTH_METHOD`	`basic` or `jwt`.
`PLONE_CLIENT_API_PREFIX`	Traversal prefix of the REST API.
`PLONE_CLIENT_TIMEOUT`	Seconds to wait for the site.
`PLONE_CLIENT_VERIFY`	`false` to skip TLS verification, or the path of a CA bundle.
`PLONE_CLIENT_RETRIES`	Times a request is repeated; `0` turns retries off.
`PLONE_CLIENT_BACKOFF`	Base delay in seconds between retries.
`PLONE_CLIENT_READ_ONLY`	`true` to refuse every change.
`PLONE_CLIENT_FRONTEND_URL`	URL of the Volto frontend, when `PLONE_CLIENT_URL` is the backend.

These two are read by the command line only.

Variable	Meaning
`PLONE_CLIENT_PROFILE`	Profile to use.
`PLONE_CLIENT_CONFIG`	Configuration file.