clavitor-cli totp

totp prints the current one-time code of an entry, so an agent or a script can get through a two-factor sign-in without anyone reading a phone. The CLI works the code out on your machine: the vault holds the secret encrypted and never sees it.

Usage

clavitor-cli totp <title> [--fuzzy]

Example

Capture the code where you need it; don't print it on its own:

code=$(clavitor-cli totp "GitHub")

How it works

  • The title must match one entry exactly; case doesn't matter. --fuzzy also accepts part of the title or of one of the entry's URLs.
  • It works on a login that has a one-time-password field and on a TOTP entry.
  • The CLI fetches the entry, decrypts its one-time-password field with its own key (Credential Encryption), and computes the code. A new one-time-password secret is saved under Identity Encryption, so the CLI can read it only after you open it to your agents (see below). Codes saved earlier keep working as they did.
  • It reads a plain base32 secret (6 digits, 30 seconds) or an otpauth:// link, whose own settings it follows: 6 to 8 digits, a period from 1 second to 1 hour, SHA-1, SHA-256 or SHA-512.
  • It prints the code on one line and nothing else.
  • Each call is one read of the entry: it is recorded in the vault's audit log and counts toward the client's read limits.

Letting your agents read a code

A new one-time-password secret is yours alone: it is saved under Identity Encryption, which opens only with your hardware key, so an agent gets CV-2048 for it. To let your agents read one, open the entry in your vault page and click the small L3 badge next to the field's name. Confirm, and that one field moves to Credential Encryption; the badge reads L2 and totp works for it. Your unlocked vault page already holds the key, so there is no extra tap. To take it back, click L2 and confirm: only your key can open the field again.

When it refuses

It prints no code and exits with an error when:

  • the entry has no one-time-password field, more than one, or an empty one (CV-2050);
  • the field does not decrypt with the client's key (CV-2049);
  • the field is protected by Identity Encryption (CV-2048), which an agent cannot open. The message names the field: CV-2048: the TOTP field 'secret' is protected by Identity Encryption: an agent cannot read it;
  • the value is not a one-time-password secret (CV-0015), or uses settings it doesn't support (CV-0016).