---
myst:
  html_meta:
    "description": "The configuration file, profile settings, project file, and environment variables of plone-client."
    "property=og:description": "The configuration file, profile settings, project file, and environment variables of plone-client."
    "property=og:title": "Configuration"
---

(reference-configuration)=

# Configuration

## Configuration file

<!-- source: src/plone_client/profiles.py -->

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

1. `$PLONE_CLIENT_CONFIG`
2. `$XDG_CONFIG_HOME/plone-client/config.toml`
3. `~/.config/plone-client/config.toml`

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

(reference-configuration-groups)=

## Groups

The `groups` table names lists of profiles, which `plone-client mcp --group` serves together; see {ref}`reference-assistant-server-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

<!-- source: src/plone_client/credentials.py -->

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

```toml
profile = "blog"
```

## Profile selection

| Order | Source |
|---|---|
| 1 | `-p`, `--profile`, or the `name` passed to {meth}`~plone_client.PloneClient.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

<!-- source: src/plone_client/profiles.py, settings_from_env -->

{meth}`~plone_client.PloneClient.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. |

## Related

- {ref}`howto-profiles` creates and manages profiles.
- {ref}`explanation-secrets` explains where secrets go and why.