Search all skrzynka documentation

Invocation#

text

skrzynka account app-password --provider gmail --email <EMAIL> [--display-name <DISPLAY_NAME>]

Purpose#

Connect one personal Gmail account or one Workspace user with an app-specific password supplied only through stdin, without a Workspace administrator or OAuth client, and declare it a mailbox in Skarbiec.

Inputs and options#

Input or option	Required	Meaning
`--email <EMAIL>`	Yes	The Gmail or Workspace login address. It also becomes the mailbox address and outgoing `From` address; an alias public address is the item's own `email` field in Skarbiec.
`--display-name <DISPLAY_NAME>`	No	Mailbox display name stored in the bundle.
stdin	Yes	The Google app-specific password. Skrzynka reads all of stdin, removes trailing CR/LF, and never accepts the secret in argv.

Global options accepted on this path are --organization <ID> (required on every command except serve, version and onboarding; none is assumed), --skarbiec-bin <PATH> (default skarbiec) and --text (print results as path: value lines for people instead of JSON).

Output and state effect#

Opens TLS to imap.gmail.com:993 and authenticates before writing anything. After Google accepts the credential, Skrzynka writes the deterministic canonical skarbiec.item.v2 bundle named skrzynka-gmail-app-password-<20-character-email-digest> through skarbiec set-json with IMAP imap.gmail.com:993 TLS and SMTP smtp.gmail.com:587 STARTTLS, tags it skrzynka:mailbox, reconciles, and prints the mailbox that now stands for it.

Refusals#

Missing --email is refused by Clap before dispatch with exit 2.
GMAIL_APP_PASSWORD_INPUT_INVALID: Google app-specific password could not be read from stdin.
GMAIL_APP_PASSWORD_INPUT_INVALID: Google app-specific password supplied through stdin must be valid UTF-8.
GMAIL_APP_PASSWORD_INPUT_INVALID: Google app-specific password supplied through stdin must not be empty.
GMAIL_PROFILE_INVALID: email is not a valid address.
SKARBIEC_WRITE_FAILED when Skarbiec refuses the skrzynka:mailbox retag; the refusal names the saved item: Google app-specific password was saved in Skarbiec item '<SKARBIEC_ITEM_ID>', but it was not declared a mailbox: <DETAIL>.
IMAP_UNAVAILABLE (retryable:true): IMAP server could not be reached over TLS.
GMAIL_IMAP_PASSWORD_REJECTED: Google refused IMAP password authentication. The error names the mailbox and Skarbiec item, gives the Weles app-password command for the same organization, and gives skrzynka --organization <ORGANIZATION> account connection --provider gmail --email <MAILBOX_EMAIL> --bind <loopback-address:port> to measure alternatives. Supply the callback address intended for OAuth; no address is assumed. Nothing has been written when this refusal returns. See weles.wisent.com/docs/app-password.
Password LOGIN failures append IMAP LOGIN at <HOST>: <DETAIL> with the observed response code and explanation. Connection or protocol failures use IMAP_AUTHENTICATION_FAILED instead of claiming that Google rejected the password; I/O and lost connections are retryable. The supplied password is removed from the detail. See Managed service for interpretation.
SKARBIEC_UNAVAILABLE (retryable:true) names the selected executable, item and operating-system cause when starting the write fails. The shared wait diagnostic announces the actual Skarbiec operation while it runs.
SKARBIEC_WRITE_FAILED retains the item and actual input-pipe, process or vault refusal. Failed credential reads, writes and deletions retain the child exit status or termination signal even when stderr is empty. Payload encoding failures retain the encoder cause; SKARBIEC_RESPONSE_INVALID retains the returned-item JSON decoder cause. These diagnostics do not include credential payloads.
Credential writes feed stdin and drain stdout/stderr concurrently, preserving a child refusal even if it arrives before the payload is consumed. A failed child wait reports that persisted state is unknown; success requires both full input delivery and a successful process exit.
The selected Skarbiec executable owns local-versus-fleet vault routing for reads and writes. Skrzynka does not retry a refused read through stado credentials or choose another vault after a failed status; the original refusal is preserved. A host without a vault requires a Skarbiec release supporting the declared fleet-owner route.
INTERNAL_ERROR: Gmail credential verification stopped unexpectedly if the blocking IMAP task terminates without a result.
MAILBOX_IMPORT_PROFILE_CONFLICT when the item already backs a mailbox with a different receiving address or IMAP endpoint.