Search all skrzynka documentation

Overview#

Skrzynka has no configuration file. Process settings come from CLI options or environment; each mailbox stores its own non-secret profile. Credentials remain Skarbiec items.

Process options#

Reader	Key	Default	Validation / effect
global CLI	`--organization ID`	none	Required organization scope for data commands; no local database path is accepted
global CLI	`--skarbiec-bin PATH`	`skarbiec`	exact child executable
`serve`	`--bind SOCKET`	none	IP must be loopback; also becomes Gmail callback base
message list	`--limit N`	none: every message	a page of N when given; 0 is refused
message list	`--offset N`	`0`	database offset

serve has no polling option: a mailbox is read when its provider announces new mail over IMAP IDLE.

Environment#

Variable	Default	Reader and behavior
`HOME`	current directory when absent	`default_database_path`; appends `.local/share/skrzynka/skrzynka.db`
`SUPABASE_URL`	repository's compiled shared-identity HTTPS URL	`AuthVerifier::from_environment`; must parse as HTTPS
`SUPABASE_ANON_KEY`	repository's compiled shared-identity anonymous key	same reader; trimmed value must be nonempty
`RUST_LOG`	`info`	`tracing_subscriber::EnvFilter::try_from_default_env`; controls stderr logs

SUPABASE_URL and SUPABASE_ANON_KEY affect /v1 authentication, not CLI data access, which is filtered by the --organization the caller names. Invalid identity setup prevents AppState construction even for local state commands other than version.

SKRZYNKA_SOURCE_REVISION is a compile-time variable read by option_env!, not runtime configuration. It changes only the source field of skrzynka version; absent means source-build.

Mailbox create keys#

Create and import accept only the source reference shown below. Account-profile fields belong to the Skarbiec item, not to a separately editable Skrzynka definition:

CLI	HTTP / stored key	Default / source
`--skarbiec-item`	`skarbiec_item_id`	required exact ID
tag `skrzynka:mailbox` on the item	—	declares the item a mailbox; set by `mailbox declare` or `skarbiec retag`

There is no local mailbox edit. Change the account definition in Skarbiec; the next reconciliation adopts it. A receiving-address or IMAP-endpoint change is refused as MAILBOX_IMPORT_PROFILE_CONFLICT because an existing UID cursor cannot safely identify another source. Profile overrides and credential fields are not accepted by any command or route.

Password item fields#

Canonical item kind must be login or bundle, and the item is a mailbox only while its tags include skrzynka:mailbox. fields supports:

Field	Required	Notes
`username`	yes	authentication identity; may supply email
`password`	password auth	secret, resolved per connection
`email`	unless username is an address	outgoing address
`display_name`	no	1–200 characters after trimming
`imap_host`, `smtp_host`	yes	hostnames, not URLs
`imap_port`, `smtp_port`	no	integer or numeric text accepted
`smtp_security`	no	`starttls` or `tls`

Fixed Gmail item IDs#

skrzynka-google-oauth-desktop: fields.value contains a Google Desktop-app client JSON. The installed object must contain text client_id and client_secret; endpoints must be canonical.
skrzynka-google-service-account: fields.value contains a Google service_account JSON with client_email, numeric client_id, private_key, optional private_key_id, and canonical token URI.
skrzynka-gmail-<digest>: generated bundle for one OAuth or delegated mailbox. Do not hand-copy token values into process configuration.

Fixed safety bounds#

These are compiled behavior, not knobs: Skarbiec child timeout 15 seconds; SQLite busy timeout 5 seconds. A Gmail OAuth flow has no lifetime of Skrzynka's own: it stays pending until Google's callback settles it, and the caller that stops waiting abandons it. A sync imports every message past the cursor, one commit each. Skarbiec output, raw messages, bodies, subjects and idempotency keys carry no size bound of Skrzynka's own; the SMTP server accepts or refuses what it carries. Neither the IMAP nor the SMTP client sets a network timeout: each waits for the server's answer or the connection's own error.