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)

Set up Tegata​

Tegata offers two interfaces. Set up the one that fits your workflow, or set up both.

Troubleshooting

If the interface you set up does not launch on first run, check Set up your OS and Troubleshooting for platform-specific fixes.

Run the CLI and TUI​

The CLI and TUI run directly from your USB drive and requires no installation on the host machine.

Download tegata-windows-amd64.exe. 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​

The desktop GUI is installed on your host machine rather than carried on your 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.

note

If SmartScreen blocks first launch, select More info, then choose Run anyway.

Build from source​

If you prefer to build from source, clone the repository first:

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

CLI and TUI​

Build the CLI and TUI for your platform.

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.

Desktop GUI​

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​

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.

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​

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:

482901
Expires in 18s
Copied to clipboard (auto-clear in 45s)
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:

  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

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.

Run the following command once after creating your vault, 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​