Configuration

Precedence (highest wins)

1. CLI flags — e.g. --base-url, --profile.
2. Environment variables — PYNTERACTA_* prefixed.
3. Config file profile — selected by --profile, else by current_profile in the file.
4. Built-in defaults — e.g. base_path = "/portal", timeout_seconds = 30.0.

Config file

Location:

• Linux/macOS: $XDG_CONFIG_HOME/pynteracta/config.toml, i.e. ~/.config/pynteracta/config.toml by default (XDG convention on both platforms — not ~/Library/Application Support on macOS).
• Windows: platformdirs.user_config_dir("pynteracta"), i.e. %LOCALAPPDATA%\pynteracta\config.toml.
• Override the path with PYNTERACTA_CONFIG_FILE or --config-file.

current_profile = "default"

[profiles.default]
base_url        = "https://interacta.example.it"
base_path       = "/portal"
api_version     = 2
service_account_key = "~/.config/pynteracta/sa.json"
token_cache     = "file"
timeout_seconds = 30.0
log_level       = "INFO"

[profiles.staging]
base_url        = "https://staging.interacta.example.it"
service_account_key = "~/.config/pynteracta/sa-staging.json"

Managing profiles

pynteracta config add-profile staging --base-url https://staging.interacta.example.it
pynteracta config use-profile staging
pynteracta config set service_account_key ~/.config/pynteracta/sa-staging.json
pynteracta config list

Environment variables

Variable	Profile field
PYNTERACTA_BASE_URL	base_url
PYNTERACTA_BASE_PATH	base_path
PYNTERACTA_API_VERSION	api_version
PYNTERACTA_AUTH_METHOD	auth_method (service_account or google_oauth2)
PYNTERACTA_SERVICE_ACCOUNT_KEY	service_account_key
PYNTERACTA_GOOGLE_OAUTH2_TOKEN	google_oauth2_token (not persisted to config)
PYNTERACTA_TOKEN_CACHE	token_cache (file or memory)
PYNTERACTA_TOKEN_CACHE_DIR	token_cache_dir
PYNTERACTA_TIMEOUT	timeout_seconds
PYNTERACTA_LOG_LEVEL	log_level — used by the CLI when --log-level is not given
PYNTERACTA_AUDIT_LOG	audit_log — enable audit logging
PYNTERACTA_AUDIT_LOG_FILE	audit_log_file — rotating file path (implies audit on)
PYNTERACTA_AUDIT_LOG_BODIES	audit_log_bodies — capture request/response bodies
PYNTERACTA_AUDIT_LOG_RAW	audit_log_raw — bypass redaction (unsafe)
PYNTERACTA_AUDIT_LOG_MAX_BYTES	audit_log_max_bytes — max bytes per log file
PYNTERACTA_AUDIT_LOG_BACKUPS	audit_log_backups — rotated file count
PYNTERACTA_CONFIG_FILE	config file path override

Profile fields

Field	Type	Default	Description
base_url	HttpUrl	— (required)	Interacta tenant URL
base_path	str	/portal	URL path prefix
api_version	int	2	API version
auth_method	"service_account" or "google_oauth2"	service_account	Authentication method
service_account_key	Path	None	Path to SA key JSON
google_oauth2_token	str	None	Google access token; supply via env/flag, not persisted to config
token_cache	"file" or "memory"	file	Cache backend
token_cache_dir	Path	~/.config/pynteracta/tokens/ (XDG)	Override cache directory
timeout_seconds	float	30.0	HTTP timeout
log_level	DEBUG/INFO/WARNING/ERROR	INFO	Log verbosity for the CLI; --log-level overrides it
audit_log	bool	false	Enable API call audit logging
audit_log_file	path	(none)	Rotating JSON-lines audit file path
audit_log_bodies	bool	false	Capture request/response bodies (opt-in)
audit_log_raw	bool	false	Bypass redaction — unsafe, never use in production
audit_log_max_bytes	int	10000000	Max bytes per audit log file before rotation
audit_log_backups	int	5	Number of rotated backup files to keep