PIZAUTH(1)

📦 version 1.1.1, in nixos 26.05, nixpkgs unstable

💅 PIZAUTH(1) 💅

okay so this is the General Commands Manual page for pizauth, and we are gonna get you fluent in it, no cap. It’s giving “OAuth2 daemon with main character energy”, and honestly? Obsessed.

🌸 NAME 🌸

pizauth — OAuth2 authentication daemon

✨ SYNOPSIS ✨

pizauth command

💖 DESCRIPTION 💖

okay so pizauth requests, shows, and refreshes OAuth2 tokens. It’s formed of two components: a persistent “server” which interacts with the user to obtain tokens, and refreshes them as necessary; and a command-line interface which can be used by other programs to show the OAuth2 token for a current account.

The top-level commands are:

  • dump — writes the current pizauth state to stdout: this can later be fed back into pizauth with restore. The dump format is stable within a pizauth major release (but not across major releases) and stable across platforms, though it includes timestamps that may be affected by clock drift on either the machine performing dump or restore. Clock drift does not affect security, though it may cause dumped access tokens to be refreshed unduly early or late upon a restore. Refreshed access tokens will then be refreshed at the expected intervals.
⚠️ note that while the dump output may look like it is encrypted, it is trivial for an attacker to recover access and refresh tokens from it. It is strongly recommended that you use external encryption on the output so that your data cannot be compromised. This is not a drill, bestie. 🔥
  • info [-j] — writes output about pizauth to stdout including: the cache directory path; the config file path; and pizauth version. Defaults to human-readable output in an unspecified format that may change freely between pizauth versions.
    • -j — specifies JSON output. The info_format_version field is an integer value specifying the version of the JSON output: if incompatible changes are made, this integer will be monotonically increased.
  • refresh [-u] account — request a refresh of the access token for account. Exits with 0 upon success. If there is not currently a valid access or refresh token, reports an error to stderr, initiates a new token request, and exits with 1. Unless -u is specified, the error will include an authorization URL. Note that this command does not block and will not start a new refresh if one is ongoing.
    • -u — when specified, the error won’t include an authorization URL (because unless -u is specified, it will include one).
  • reload — reload the server’s configuration. Exits with 0 upon success or 1 if there is a problem in the configuration.
  • restore — reads previously dumped pizauth state from stdin and updates those parts of the current state it determines to be less useful than the dumped state. This does not change the running instance’s configuration: any changes in security relevant configuration between the dumping and restoring pizauth instances causes those parts of the dump to be silently ignored. See dump for information about the dump format, timestamp warnings, and encryption suggestions.
  • revoke account — removes any token, and cancels any ongoing authentication, for account. Note that OAuth2 provides no standard way of remotely revoking a token: revoke thus only affects the local pizauth instance. Exits with 0 upon success.
  • server [-c config-file] [-dv] — start the server. If not specified with -c, pizauth checks for the configuration file (in order) at: $XDG_CONFIG_HOME/pizauth.conf, $HOME/.config/pizauth.conf. The server will daemonise itself unless -d is specified. Exits with 0 if the server started successfully or 1 otherwise.
    • -c config-file — use this config file; if it’s not specified with -c, pizauth checks the two paths above in order.
    • -d — the exception to the daemonise rule: if -d is specified, the server does not daemonise itself.
    • -v — enables more verbose logging. -v can be used up to 4 times, with each repetition increasing the quantity of logging.
  • show [-u] account — if there is an access token for account, print that access token to stdout and exit with 0. If there is not currently a valid access token, prints an error to stderr and exits with 1. If refreshing might obtain a valid access token, refreshing is initiated in the background. Otherwise (unless -u is specified), the error will include an authorization URL. Note that this command does not block: commands must expect that they might encounter an error when showing an access token.
    • -u — when specified, the error won’t include an authorization URL (because otherwise, unless -u is specified, it will include one).
  • shutdown — shut the server down. Note that shutdown occurs asynchronously: the server may still be alive for a period of time after this command returns.
  • status — writes output about the current accounts and whether they have access tokens to stdout. The format is human-readable and in an unspecified format that may change freely between pizauth versions.

🦋 SEE ALSO 🦋

👑 AUTHORS 👑

pizauth was written by Laurence Tratt https://tratt.net/laurie/

💖 Debian • September 13, 2022 • PIZAUTH(1) 💖

📦 where this page comes from