tess, the whole reference.

Reference

Global flag: --vault sets the vault file for any command. With no argument, tess prints current codes for every account; with one, it prints and copies that account's code.

Print and copy TOTP/HOTP/Steam codes from an encrypted local vault.

  tess                     current codes for every account
  tess acme                one account's code, copied to the clipboard
  tess watch               live view with countdown bars
  tess add <uri|key|file>  add accounts
  tess vault init          create a vault

Usage:
  tess [query] [flags]
  tess [command]

Codes:
  code         Print the current code for a matching account (or all if omitted)
  watch        Live, auto-refreshing view with countdown bars and copy

Accounts:
  add          Add accounts from an otpauth/migration URI, a setup key, a QR image, an export file, the screen, or manual flags
  alias        Set an account's handle (the short name you type to reference it)
  list         List accounts (without codes)
  move         Move an account into a folder (empty folder to clear)
  rename       Rename an account's issuer, account label, and/or handle
  rm           Remove an account
  show         Show an account's details (type, algorithm, digits, period, folder, tags)
  tag          Add or remove a tag on an account

Transfer:
  export       Export accounts as otpauth URIs, base32 secrets, QR images, another app's export, or an encrypted vault copy
  import       Bulk-import accounts from files, other apps, Google exports, otpauth URIs, or QR images
  merge        Merge accounts from another Tessera vault or encrypted backup into this vault

Vault:
  vault        Manage the vault

Additional Commands:
  completion   Generate the autocompletion script for the specified shell
  help         Help about any command

Flags:
      --clear int      clear the clipboard after this many seconds, 0 to keep (default $TESSERA_CLIP_CLEAR)
  -c, --copy           copy the code to the clipboard (the default on a terminal; -c copies even when piped)
  -h, --help           help for tess
      --json           output JSON (never copies)
      --next           for HOTP, advance and persist the counter
      --no-copy        print the code without touching the clipboard
      --now            print the current code instead of waiting for the next one
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)
  -v, --version        version for tess

Use "tess [command] --help" for more information about a command.

Print one account's code and copy it to the clipboard:

  tess code acme            # print and copy
  tess code acme --no-copy  # print only
  tess code acme --json     # machine-readable, never copies
  tess code                 # every account's code

The code is copied on a terminal. Piped or with --json, tess prints the raw
digits and leaves the clipboard alone unless you pass -c.

Usage:
  tess code [query] [flags]

Flags:
      --clear int   clear the clipboard after this many seconds, 0 to keep (default $TESSERA_CLIP_CLEAR)
  -c, --copy        copy the code to the clipboard (the default on a terminal; -c copies even when piped)
  -h, --help        help for code
      --json        output JSON (never copies)
      --next        for HOTP, advance and persist the counter
      --no-copy     print the code without touching the clipboard
      --now         print the current code instead of waiting for the next one

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

Live, auto-refreshing view with countdown bars and copy

Usage:
  tess watch [flags]

Flags:
  -h, --help   help for watch

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

Add one or more accounts. The positional argument auto-detects:

  tess add "otpauth://totp/GitHub:me?secret=..."   # otpauth URI
  tess add ZB573K4APD63E6RLD3WAHI3QFZ35RLEP        # bare base32 setup key -> TOTP
  tess add code.png                                # QR image (all codes decoded)
  tess add export.json                             # Aegis/2FAS/Raivo export, or migration/otpauth lines
  tess add --screen                                # select a QR code on screen (macOS)
  cat export.json | tess add -                     # read the input from stdin

For a setup key, --issuer/--account/--digits/--period/--algorithm override the
TOTP defaults. --qr and --secret keep working as before.

Usage:
  tess add [input] [flags]

Flags:
      --account string     account name (manual/setup key)
      --algorithm string   SHA1|SHA256|SHA512 (manual/setup key) (default "SHA1")
      --digits int         code digits (manual/setup key) (default 6)
      --folder string      folder to place the account(s) in
  -h, --help               help for add
      --issuer string      issuer (manual/setup key)
      --period int         period seconds (manual/setup key) (default 30)
      --qr string          decode the account(s) from a QR image file (png/jpeg/webp/tiff/bmp)
      --screen             select a QR code on screen and add it (macOS)
      --secret string      base32 secret (manual)
      --type string        totp|hotp|steam (manual) (default "totp")

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

Set an account's handle (the short name you type to reference it)

Usage:
  tess alias <account> <handle> [flags]

Flags:
  -h, --help   help for alias

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

List accounts (without codes)

Usage:
  tess list [flags]

Aliases:
  list, ls

Flags:
      --folder string   filter by folder
  -h, --help            help for list
      --json            output JSON
      --tag string      filter by tag

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

Move an account into a folder (empty folder to clear)

Usage:
  tess move <query> <folder> [flags]

Flags:
  -h, --help   help for move

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

Rename an account's issuer, account label, and/or handle

Usage:
  tess rename <query> [flags]

Flags:
      --account string   new account label
      --handle string    new handle (short identifier)
  -h, --help             help for rename
      --issuer string    new issuer

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

Remove an account

Usage:
  tess rm <query> [flags]

Flags:
  -h, --help   help for rm

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

Print one account's record. The secret is never shown unless you ask for it:

  tess show github            # details, no secret
  tess show github --secret   # also print the base32 setup key (cleartext)
  tess show github --uri      # also print the otpauth:// setup link (cleartext)

Usage:
  tess show <query> [flags]

Flags:
  -h, --help     help for show
      --secret   also print the base32 setup key (cleartext)
      --uri      also print the otpauth:// setup link (cleartext)

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

Add or remove a tag on an account

Usage:
  tess tag <query> <tag> [flags]

Flags:
  -h, --help     help for tag
      --remove   remove the tag instead of adding it

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

Export account data (CLEARTEXT secrets — handle with care):

  tess export --uri                 # all accounts as otpauth:// URIs (bulk backup / migrate)
  tess export --uri github          # one account's otpauth URI
  tess export --secret github       # just the base32 secret (the raw key)
  tess export --qr ./qrcodes        # a QR PNG per account (scan into a phone)
  tess export --qr ./qrcodes github # one account's QR PNG
  tess export --file backup.json    # an encrypted copy of the whole vault (safe to store)
  tess export --format aegis        # the vault in another app's export format, on stdout
  tess export --format aegis --out aegis.json          # ... or written to a file
  tess export --format google-migration --out ./qr     # transfer QR codes for Google Authenticator

Formats for --format:
  2fas              2FAS Auth backup JSON (no backup password)
  aegis             Aegis Authenticator vault JSON (unencrypted)
  andotp            andOTP plain backup JSON
  apple-csv         Apple Passwords CSV (Title,URL,...,OTPAuth)
  bitwarden         Bitwarden Authenticator JSON export
  google-migration  Google Authenticator transfer QR codes (PNG per batch)
  proton            Proton Authenticator JSON export (no password; TOTP and Steam only)

Usage:
  tess export [query] [flags]

Flags:
      --file string     write an encrypted copy of the vault to this path
      --format string   rewrite the vault as another app's export: 2fas, aegis, andotp, apple-csv, bitwarden, google-migration, proton
  -h, --help            help for export
      --out string      where --format writes: a file, or a directory for multi-file formats (default stdout)
      --qr string       write a QR PNG per account to this directory (cleartext secrets)
      --secret          print only the base32 secret(s) (cleartext)
      --uri             print otpauth:// URIs (secrets in cleartext)

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

Import accounts in bulk. Sources combine and can be repeated; everything that
parses is imported, and items that fail are listed without aborting the batch:

  tess import accounts.txt export.json code.png   # paths auto-detect by content
  cat export.json | tess import -                 # read the input from stdin
  tess import --file accounts.txt                 # otpauth:// / otpauth-migration:// lines, or a setup key per line
  tess import --file export.json                  # an app export (see the list below)
  tess import --qr a.png --qr b.png               # QR images (multiple codes per image are all read)
  tess import --migration "otpauth-migration://offline?data=..."
  tess import --otpauth "otpauth://totp/...."

Exports it reads, recognized by content rather than by file name:

  Aegis, 2FAS, Raivo, andOTP, FreeOTP+, Stratum (Authenticator Pro),
  Bitwarden Authenticator, Bitwarden, Proton Authenticator, Ente Auth,
  Apple Passwords (CSV), 1Password (CSV and .1pux), and Google Authenticator
  (an otpauth-migration:// URI or a photo of its transfer QR code)

An export must be unencrypted; an encrypted one is refused by name rather than
half-read. Items with no one-time-password field, which is most of a password
manager's export, are left out. Duplicate accounts (same type, issuer, account
and secret) are skipped. docs/TRANSFER.md lists what to export from each app.

Usage:
  tess import [path...] [flags]

Flags:
      --file stringArray        text, JSON, CSV or .1pux export file, - for stdin (repeatable)
  -h, --help                    help for import
      --migration stringArray   Google Authenticator otpauth-migration:// URI (repeatable)
      --otpauth stringArray     single otpauth:// URI (repeatable)
      --qr stringArray          QR image file (repeatable; png/jpeg/webp/tiff/bmp)

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

Merge another Tessera vault (or an encrypted backup exported from the macOS
app) into the current vault. Accounts are unioned, never dropped:

  - an account present in both (same id) keeps whichever copy was edited last
  - an account already present by content (same type/issuer/account/secret) is skipped
  - every other account is added

By default the source file is opened read-only and only the current vault is
written. --two-way applies the same rule in both directions and WRITES BOTH
FILES, so two vaults that have drifted apart end up holding the same accounts:

  tess merge --two-way ~/Library/.../app-vault.json

Each vault keeps its own handles. If the source shares this vault's passphrase
you are not prompted again; otherwise enter the source's passphrase (or set
$TESSERA_MERGE_PASSPHRASE).

Usage:
  tess merge <vault-file> [flags]

Flags:
  -h, --help      help for merge
      --two-way   also write the missing and newer accounts back into the source vault

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

Manage the vault

Usage:
  tess vault [command]

Available Commands:
  forget      Remove the vault passphrase from the login keychain
  init        Create a new empty encrypted vault
  passwd      Change the vault passphrase
  remember    Store the vault passphrase in the login keychain
  reset       Delete the vault file so a fresh vault can be created
  status      Show the vault path, file details, and wrap methods

Flags:
  -h, --help   help for vault

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

Use "tess vault [command] --help" for more information about a command.

Remove the vault passphrase from the login keychain

Usage:
  tess vault forget [flags]

Flags:
  -h, --help   help for forget

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

Create a new empty encrypted vault

Usage:
  tess vault init [flags]

Flags:
  -h, --help   help for init

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

Change the vault passphrase. The current passphrase is read from
$TESSERA_PASSPHRASE or prompted for; the replacement is read from
$TESSERA_NEW_PASSPHRASE or entered twice on a terminal.

Usage:
  tess vault passwd [flags]

Flags:
  -h, --help   help for passwd

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

Store the vault passphrase in the macOS login keychain so tess stops
prompting. The passphrase is verified against the vault before it is stored.

Usage:
  tess vault remember [flags]

Flags:
  -h, --help   help for remember

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

Delete the vault at its resolved path (respects --vault and $TESSERA_VAULT).
This is irreversible and removes every account. Run "tess vault init" afterward
to create a new empty vault. Use --force to skip the confirmation in scripts.

Usage:
  tess vault reset [flags]

Flags:
      --force   skip the confirmation prompt
  -h, --help    help for reset

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

Report the resolved vault path, whether the file exists, its size and
modification time, the wrap methods in the envelope header, and whether a login
keychain entry exists. Nothing is decrypted and the passphrase is never shown.

Usage:
  tess vault status [flags]

Flags:
  -h, --help   help for status

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

JSON output

tess code --json and tess list --json print JSON for scripts. One account:

$ tess code github --json
{
  "account": "ibra",
  "code": "899519",
  "expires_in": 17,
  "issuer": "GitHub",
  "type": "totp"
}

Without a query, tess code --json prints an array. Set TESSERA_PASSPHRASE to avoid the prompt, or run tess vault remember once. Errors go to stderr as error: … with exit status 1.

Shell completions

Once per shell. Completing an account name reads the vault, so handles are offered once it opens without a prompt, from TESSERA_PASSPHRASE or the login keychain.

# zsh, macOS with Homebrew
$ tess completion zsh > $(brew --prefix)/share/zsh/site-functions/_tess
# zsh, Linux
$ tess completion zsh > "${fpath[1]}/_tess"
# bash, macOS with Homebrew (needs bash-completion)
$ tess completion bash > $(brew --prefix)/etc/bash_completion.d/tess
# bash, Linux
$ tess completion bash > /etc/bash_completion.d/tess
# fish
$ tess completion fish > ~/.config/fish/completions/tess.fish

Generate the autocompletion script for the bash shell.

This script depends on the 'bash-completion' package.
If it is not installed already, you can install it via your OS's package manager.

To load completions in your current shell session:

	source <(tess completion bash)

To load completions for every new session, execute once:

#### Linux:

	tess completion bash > /etc/bash_completion.d/tess

#### macOS:

	tess completion bash > $(brew --prefix)/etc/bash_completion.d/tess

You will need to start a new shell for this setup to take effect.

Usage:
  tess completion bash

Flags:
  -h, --help              help for bash
      --no-descriptions   disable completion descriptions

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

	tess completion fish | source

To load completions for every new session, execute once:

	tess completion fish > ~/.config/fish/completions/tess.fish

You will need to start a new shell for this setup to take effect.

Usage:
  tess completion fish [flags]

Flags:
  -h, --help              help for fish
      --no-descriptions   disable completion descriptions

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need
to enable it.  You can execute the following once:

	echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions in your current shell session:

	source <(tess completion zsh)

To load completions for every new session, execute once:

#### Linux:

	tess completion zsh > "${fpath[1]}/_tess"

#### macOS:

	tess completion zsh > $(brew --prefix)/share/zsh/site-functions/_tess

You will need to start a new shell for this setup to take effect.

Usage:
  tess completion zsh [flags]

Flags:
  -h, --help              help for zsh
      --no-descriptions   disable completion descriptions

Global Flags:
      --vault string   vault file path (default $TESSERA_VAULT or ~/.local/share/tessera/vault.json)

Environment

TESSERA_VAULT

Vault path. Default ~/.local/share/tessera/vault.json; --vault overrides both.

TESSERA_PASSPHRASE

Skips the passphrase prompt. For scripts.

TESSERA_NEW_PASSPHRASE

The replacement passphrase for tess vault passwd.

TESSERA_MERGE_PASSPHRASE

The source vault's passphrase for tess merge, when it differs.

TESSERA_CLIP_CLEAR

Seconds after which a copied code is wiped from the clipboard. The --clear default.

NO_COLOR

Turns colored output off. Output is also plain when piped.