Settings, files and environment

For signing in, profiles and sessions, see Account.

The config file

~/.config/proton-cli/config.yaml. It does not exist until you write it, and nothing needs it.

profile: work

output: json
log-level: warn

confirm:
  ask:
    "*": mutations

per-profile:
  work:
    confirm:
      deny:
        "*": deletions
  personal:
    output: text
    no-color: true

The top level applies whichever profile you are acting as. per-profile: narrows a setting to one of them.

Key	Also settable as
profile	-p, --profile; PROTON_PROFILE
output	-o, --output
quiet	-q, --quiet
log-level	--log-level; PROTON_LOG_LEVEL
zone	--zone; TZ
full-ids	--full-ids
no-color	--no-color; NO_COLOR
no-input	--no-input; PROTON_NO_INPUT
no-log	--no-log; PROTON_NO_LOG
no-update-check	PROTON_NO_UPDATE_CHECK
confirm	--confirm; PROTON_CONFIRM (what it does)

profile only works at the top level. Everything else may appear in either place.

An unrecognised key is an error, and so is a value of the wrong shape. Nothing runs until the file parses:

$ proton mail messages list
Error: /home/you/.config/proton-cli/config.yaml: [4:1] unknown field "loglevel"

Settings the file rejects

Setting	Why
--yes	A standing “yes” would cancel every confirmation you wrote, including a deny. Type it per run or not at all.
--dry-run	A file that turns every command into a preview looks exactly like work getting done.
--verified	It is a single token from a single refusal. It means nothing the next day.
--api-url	It is for developing proton, not using it. A durable way to point the CLI at a host that is not Proton is where credentials go missing.

Reading a different file

$ proton --config ./ci.yaml mail messages list
$ PROTON_CONFIG=/etc/agents/proton.yaml proton mail drafts send 7fK2mQ

--config beats PROTON_CONFIG, which beats the default path.

A file you name and that is not there is an error. The default one being absent just means you have written no configuration.

Which source wins

For ordinary settings, the nearest source wins:

--flag  >  environment variable  >  per-profile section  >  top level  >  built-in default

Which profile you are acting as is settled first:

--profile  >  PROTON_PROFILE  >  top-level profile:  >  default

The confirmation policy is the exception. The strictest source wins:

strongest of { built-in, top level, per-profile section, PROTON_CONFIRM, --confirm }

So nothing you write can make proton less careful than it is with no configuration at all.

Turning a file setting off for one run

A boolean you set in the file is still a preference, so pass the flag with an explicit value:

$ proton --quiet=false mail messages list

Environment variables

Variable	What it does
PROTON_CONFIG	A config file somewhere other than the default path
PROTON_CONFIRM	The confirmation policy, on one line (syntax)
PROTON_PROFILE	Active profile (default: default)
PROTON_API_URL	API base URL (default: https://mail.proton.me/api)
NO_COLOR	Set to any value, even empty, to turn colour off (no-color.org)
FORCE_COLOR	Set to any value, even empty, to paint even when the output is piped (force-color.org). Set beside NO_COLOR, this one wins
COLORTERM	Set to truecolor or 24bit if your terminal takes 24-bit colour and does not advertise it. Only affects how exactly a colour swatch is drawn
PROTON_NO_INPUT	Set to any value, even empty, to never prompt. A missing credential becomes an error
PROTON_LOG_LEVEL	debug, info, warn or error
PROTON_NO_LOG	Set to any value, even empty, to write no diagnostic log (what that is)
TZ	The IANA zone to work in, such as Europe/Vienna. POSIX’s own variable, read when no flag or file names one
PROTON_NO_UPDATE_CHECK	Set to any value, even empty, to never look for a new release (what that is)
PROTON_VERIFIED	A human verification already solved, as the refusal printed it (when you need it)

Files on disk

Path	What is in it
~/.config/proton-cli/config.yaml	Your settings and confirmation policy. You write this one
~/.config/proton-cli/sessions/<profile>.json	Session tokens and the encrypted key password (mode 0600)
~/.config/proton-cli/idcache/<profile>.json	Short-ID lookup table (what that is)
~/.config/proton-cli/index/<profile>/	The encrypted copy proton index create builds (mode 0600, what it is for)
~/.config/proton-cli/update-check.json	When proton last looked for a new release (why)
~/.config/proton-cli/logs/	What every run did, one file per day (below)

Those are the Linux paths. macOS uses ~/Library/Application Support/proton-cli/, and Windows uses %APPDATA%\proton-cli\. Nothing else is written.

The diagnostic log

Every run writes what it did to ~/.config/proton-cli/logs/, one file per day, at full detail whatever --log-level says; that flag decides what reaches your screen. proton report reads it. What it holds, what never enters it, and how to send it with a bug report: Reporting a bug.

To write nothing at all:

$ proton --no-log mail messages list
$ PROTON_NO_LOG=1 proton mail messages list

no-log: true

With the log off, proton report has nothing to show but this build and your settings.

Global flags

Every command takes these.

Flag	What it does
-p, --profile NAME	Which profile to act as
-o, --output text|json|yaml	Output format (default text)
-n, --dry-run	Preview a mutation without applying it
-y, --yes	Answer confirmation prompts with yes (when a script needs it)
-q, --quiet	Suppress the non-essential stderr output
--config PATH	Settings file to read (env: PROTON_CONFIG)
--confirm POLICY	Which commands stop for a yes (env: PROTON_CONFIRM)
--full-ids	Do not shorten IDs in interactive output
--no-color	Turn colour off (env: NO_COLOR)
--force-color	Paint even when the output is piped or redirected (env: FORCE_COLOR)
--log-level debug|info|warn|error	Logging verbosity (env: PROTON_LOG_LEVEL)
--zone NAME	IANA time zone to work in (env: TZ)
--no-input	Never prompt. A missing credential becomes an error (env: PROTON_NO_INPUT)
--no-log	Write no diagnostic log for this run (env: PROTON_NO_LOG)
--verified TOKEN	A human verification already solved, as the refusal printed it (env: PROTON_VERIFIED)

The five you type most have a single-letter form, and they cluster, so -qn is a quiet dry run.

--api-url URL points the CLI at a different API host. It is for developing proton and is hidden from --help.