Skip to main content

Quickstart

This guide walks you through installing Tegata, creating your first vault, and running your first credential workflow, using TOTP as an example. By the end, you will have a working vault and a complete picture of the workflow. If you are new to Tegata, see the Introduction first.

Prerequisites​

Before you begin, you need the following:

  • A USB drive or microSD card formatted as FAT32 or exFAT
  • A TOTP-compatible account, such as GitHub or Microsoft, that provides a base32 secret or an otpauth:// URI
  • Go 1.25 or later (optional – only if you plan to build from source)
  • Node.js 20 or later and Wails v2 (optional – only if you plan to build the desktop GUI from source)
  • Docker (optional – only if you want to enable audit logging)

Install Tegata​

Download tegata-windows-amd64.exe from the Releases page. Rename it to tegata.exe and copy it to your USB drive.

Open PowerShell. Since PowerShell does not search the current directory for executables, run the following command to run the binary by prefixing it with .\:

.\tegata.exe version

To run tegata from any directory, add the USB drive letter to your PATH by running the following command, replacing <USB_DRIVE_LETTER> with the actual letter of your drive:

$env:PATH += ";<USB_DRIVE_LETTER>:\"

Install the desktop GUI​

A graphical interface is available separately and is installed on your host machine rather than carried on the USB drive.

Download and run tegata-gui-windows-amd64-setup.exe. The NSIS installer places the binary in Program Files and creates a Start Menu entry.

Build the CLI and TUI from source​

If you prefer to build the CLI from the source code, clone the repository and build for your platform.

git clone https://github.com/josh-wong/tegata.git
cd tegata

make build on Windows requires cmd.exe and GNU Make. Instead, in PowerShell, build directly by running the following commands from the repository root:

$env:CGO_ENABLED = "0"
go build -ldflags "-s -w" -o bin\tegata.exe .\cmd\tegata\

The binary is placed in bin\tegata.exe. Copy it to your USB drive alongside your vault.

Make the CLI runnable from anywhere

In PowerShell, run the following command from the repository root:

.\bin\tegata.exe version

To run tegata from any directory, copy bin\tegata.exe to a folder on your PATH (for example, %USERPROFILE%\bin) and add that folder to your user PATH.

Build the desktop GUI from source​

Building the GUI requires the Wails CLI, Go 1.25 or later, and Node.js 20 or later. Install the Wails CLI by running the following command:

go install github.com/wailsapp/wails/v2/cmd/wails@latest

make gui on Windows uses mv, which is not available in PowerShell. Instead, run the following commands from the repository root:

cd cmd\tegata-gui
wails build -clean

The binary is placed in cmd\tegata-gui\build\bin\tegata-gui.exe.

Create a vault​

To create a vault, choose your platform and run the corresponding command.

In PowerShell, run the following command, replacing <USB_DRIVE_LETTER> with the actual letter of your drive:

.\tegata.exe init <USB_DRIVE_LETTER>:\

Tegata prompts you to create a passphrase (minimum 8 characters) and then displays your recovery key:

Vault created: /path/to/vault

Recovery key (store this somewhere safe—you will not see it again):

    ABCD-EFGH-IJKL-MNOP-QRST-UVWX-YZ23-4567
Save your recovery key

Write your recovery key down and store it somewhere physically separate from your USB drive—a printed copy in a safe, a trusted password manager, or a locked drawer. If you forget your passphrase, this key is the only way to recover your vault. It cannot be retrieved after moving on from this screen.

Add a credential​

Tegata supports two methods for adding credentials: scanning an otpauth:// URI and entering the secret manually. In this section, as an example, a credential for GitHub will be added using both methods.

When a service shows you a QR code, most services also offer a "copy link" option or display the otpauth:// URI as text. Copy the URI and run the following command, replacing path/to/vault with your vault path:

tegata add GitHub --scan --vault /path/to/vault

Tegata prompts you to paste the URI (input is hidden). The credential type, issuer, algorithm, digits, and period are parsed automatically from the URI.

Generate your first code​

To generate a TOTP code for the credential you just added, run the following command, replacing /path/to/vault with your vault path:

tegata code GitHub --vault /path/to/vault

The output shows the current code, the time until it expires, and a confirmation that it has been copied to your clipboard. The following is an example output:

482901
Expires in 18s
Copied to clipboard (auto-clear in 45s)

The code is displayed in the terminal and copied to your clipboard. The clipboard is automatically cleared after 45 seconds.

Avoid typing your vault path every time

Set the TEGATA_VAULT environment variable to your USB drive path by running the following command, replacing /path/to/vault with your vault path. All commands will find your vault automatically.

export TEGATA_VAULT=/path/to/vault

In PowerShell on Windows, run the following command, replacing <USB_DRIVE_LETTER> with the actual letter of your drive:

$env:TEGATA_VAULT = "<USB_DRIVE_LETTER>:\"

Workflow​

The typical workflow is straightforward:

  1. Plug in your USB drive.
  2. Run tegata code <label> to generate and copy a code.
  3. Paste the code where needed.
  4. The clipboard clears automatically in 45 seconds.

To list all credentials in your vault, run the following command:

tegata list

Credentials are grouped by tag. Untagged credentials appear under [untagged].

Vault resolution order​

When you do not specify --vault, Tegata looks for your vault in this order:

  1. --vault flag
  2. TEGATA_VAULT environment variable
  3. ./vault.tegata in the current working directory

Prefer the TUI​

If you prefer a visual interface in the terminal, run the following command to launch the TUI:

tegata ui

The TUI shows live TOTP countdown timers, a credential list you can navigate with the keyboard, and an overlay form for adding credentials. If no vault is found, it launches a setup wizard. For a complete walkthrough, see the Using the TUI guide.

Optional: Enable audit logging​

Tegata can record every authentication event in a tamper-evident audit log backed by ScalarDL Ledger. Audit logging is disabled by default and requires Docker.

Enable it once after creating your vault by running the following command, replacing /path/to/vault with your vault path:

tegata ledger start --vault /path/to/vault

After setup, every vault unlock automatically starts the Docker stack in the background. For full details, see the Enable audit logging guide.

Next steps​