CLI reference

This page describes every Tegata CLI command with its flags, defaults, and usage examples. Commands are listed alphabetically.

Vault resolution

All commands that access your vault use the following resolution order.

1. --vault flag (directory or file path—highest priority)
2. TEGATA_VAULT environment variable
3. ./vault.tegata in the current working directory

If a directory is given, Tegata appends vault.tegata automatically.

Global flags

These flags are available on every command.

Flag	Type	Default	Description
--vault	string	(none)	Path to vault file or directory.
--verbose	bool	false	Enable debug logging to stderr.

Commands

This section lists all CLI commands in alphabetical order. For a quickstart guide to the most common commands, see the Quickstart.

tegata add

Add a credential to your vault. Supports TOTP, HOTP, static password, and challenge-response credential types.

Usage: tegata add <LABEL> [FLAGS]

Flags:

Flag	Type	Default	Description
--scan	bool	false	Paste an otpauth:// URI instead of entering fields manually.
--type	string	totp	Credential type: totp, hotp, static, challenge-response.
--issuer	string	(none)	Credential issuer name.
--algorithm	string	SHA1	HMAC algorithm: SHA1, SHA256, SHA512; challenge-response defaults to SHA256.
--digits	int	6	Number of digits in generated code (1–10).
--period	int	30	TOTP period in seconds (15–120).
--tag	string	(none)	Tag to apply (repeatable: --tag work --tag totp).

Examples:

Add TOTP with manual secret entry

tegata add GitHub --type totp --issuer GitHub

Add from an otpauth:// URI

tegata add GitHub --scan

Add with tags

tegata add GitHub --type totp --issuer GitHub --tag work --tag totp

The secret is always prompted interactively with hidden input. When using --scan, the type, issuer, algorithm, digits, and period are parsed from the URI automatically.

tegata bench

Benchmark Argon2id key derivation performance on the current machine. Runs 3 iterations with the default parameters (time=3, memory=64 MiB, parallelism=4) and reports the average unlock time.

Usage: tegata bench

tegata bench

Output includes per-run timings and whether the result is within the 3-second target. Use this on new hardware to verify that key derivation completes in an acceptable time.

tegata change-passphrase

Rotate your vault passphrase without re-encrypting the credential payload. Only the passphrase-wrapped data encryption key and header salt are replaced.

Usage: tegata change-passphrase

tegata change-passphrase

Tegata prompts for the current passphrase, then prompts for and confirms the new passphrase. The operation is fast regardless of vault size.

tegata code

Generate a TOTP or HOTP code for a credential. The code is displayed in the terminal and copied to the clipboard by default.

Usage: tegata code <LABEL> [FLAGS]

Flags:

Flag	Type	Default	Description
--clip	bool	true	Copy code to clipboard.
--show	bool	true	Display code in terminal.

Examples:

Generate a TOTP code (display and copy to clipboard)

tegata code GitHub

Generate without clipboard copy

tegata code GitHub --clip=false

For TOTP credentials, the output includes the remaining seconds until the code expires. For HOTP credentials, the counter is incremented and saved before displaying the code.

tegata config set

Set a configuration value in tegata.toml.

Usage: tegata config set <KEY> <VALUE>

Supported keys:

Key	Values	Description
audit.auto_start	true / false	Auto-start the Docker audit stack on vault unlock.

Examples:

Disable audit auto-start

tegata config set audit.auto_start false

Re-enable audit auto-start

tegata config set audit.auto_start true

tegata config show

Display the effective configuration, including values from tegata.toml or their defaults.

Usage: tegata config show

tegata config show

tegata export

Export all credentials to an encrypted .tegata-backup file. The backup is protected by a separate export passphrase that you choose at export time.

Usage: tegata export [flags]

Flags:

Flag	Type	Default	Description
--out	string	vault.tegata-backup in your vault directory	Output path for the backup file.

Export to a specific location

tegata export --out ~/backups/vault.tegata-backup

Tegata prompts for your vault passphrase, then prompts for and confirms a new export passphrase (minimum 8 characters). The export passphrase is independent of your vault passphrase.

Set a different export passphrase

Using a different passphrase for the backup adds defense in depth—an attacker who learns one passphrase does not automatically have both.

tegata get

Retrieve a static password credential. The password is copied to the clipboard by default and optionally displayed in the terminal.

Usage: tegata get <LABEL> [FLAGS]

Flags:

Flag	Type	Default	Description
--show	bool	false	Display the password in terminal.

Examples:

Retrieve and copy to clipboard

tegata get backup-key

Retrieve and display in terminal

tegata get backup-key --show

tegata history

View authentication event history from the ScalarDL Ledger. Requires audit logging to be enabled in tegata.toml.

Tegata prompts for your vault passphrase to resolve label hashes to human-readable credential names. If a credential has been removed since the event was recorded, the label displays as (deleted).

Usage: tegata history [FLAGS]

Flags:

Flag	Type	Default	Description
--from	string	(none)	Start-date filter (YYYY-MM-DD).
--to	string	(none)	End-date filter (YYYY-MM-DD).
--json	bool	false	Output as JSON array.

Table output columns: Operation, Label (resolved from hash), Timestamp (UTC), Hash (truncated).

JSON fields per record: object_id, operation, label_hash, timestamp (Unix seconds), hash_value.

Examples:

View all history

tegata history

Filter by date range

tegata history --from 2026-01-01 --to 2026-03-31

JSON output for scripting

tegata history --json | jq '.[] | select(.operation == "totp")'

tegata import

Import credentials from an encrypted .tegata-backup file into the current vault. Credentials whose label already exists in your vault are skipped.

Usage: tegata import <BACKUP-FILE>

Example:

tegata import ~/backups/vault.tegata-backup

Tegata prompts for your vault passphrase and then the backup passphrase. For scripted restore flows, the backup passphrase can be provided via the TEGATA_BACKUP_PASSPHRASE environment variable.

tegata init

Create a new encrypted vault. If a path argument is provided, it is used as your vault directory. Otherwise the current directory is used.

Usage: tegata init [path]

Examples:

To create a vault on a USB drive, run the following command, replacing /path/to/usb with your drive path:

Initialize vault on a USB drive

tegata init /path/to/usb

To create a vault in the current directory, run the following command:

Initialize in current directory

tegata init

Tegata prompts for and confirms a passphrase (minimum 8 characters), creates your vault file, writes a default tegata.toml configuration, and displays a recovery key. Store the recovery key in a separate secure location before proceeding.

tegata ledger start

One-click setup that starts the ScalarDL Ledger Docker stack and configures audit logging. Run this once after creating your vault to enable the audit layer.

Usage: tegata ledger start [flags]

Examples:

Start with vault from TEGATA_VAULT or current directory

tegata ledger start

Start with explicit vault path

tegata ledger start --vault /media/usb

Tegata runs the full setup sequence: checks for Docker, extracts bundled compose files to ~/.tegata/docker/, generates a unique entity ID and secret key, starts the Docker stack, waits for the ledger to become ready, registers credentials, and writes the [audit] section to tegata.toml. The process takes 3–7 minutes on first run (the HashStore SDK download is the slow part).

After setup, every vault unlock automatically starts the Docker stack in the background.

For more details, see the Enable audit logging guide.

tegata ledger stop

Stop the ScalarDL Ledger Docker containers. Audit history is preserved on disk.

Usage: tegata ledger stop [flags]

tegata ledger stop
tegata ledger stop --vault /media/usb

tegata ledger setup

Register the HMAC secret key with ScalarDL and verify connectivity. This is the manual alternative to tegata ledger start for users running their own ScalarDL instance rather than the bundled Docker stack.

Usage: tegata ledger setup

tegata ledger setup

Reads the [audit] section from tegata.toml and registers the configured secret key. For configuration steps, see the Enable audit logging guide.

tegata list

List all credentials in your vault, grouped by tag. Untagged credentials appear under [untagged].

Usage: tegata list [flags]

Flags:

Flag	Type	Default	Description
--tag	string	(none)	Filter credentials by tag (case-sensitive exact match).

Examples:

List all credentials

tegata list

Filter by tag

tegata list --tag work

tegata remove

Remove a credential from your vault. Tegata prompts for confirmation before removing.

Usage: tegata remove <LABEL>

tegata remove old-service

tegata resync

Resynchronize an HOTP counter after it has drifted out of sync. Provide two consecutive codes from the server or another authenticator. Tegata scans a look-ahead window of 100 counters to find the matching position.

Usage: tegata resync <LABEL>

tegata resync my-hotp-service

Tegata prompts for two consecutive codes interactively.

tegata sign

Sign a challenge string using a stored HMAC secret (challenge-response credential). The algorithm is determined by the credential's algorithm field: SHA256 produces HMAC-SHA256, anything else defaults to HMAC-SHA1.

Usage: tegata sign <LABEL> [FLAGS]

Flags:

Flag	Type	Default	Description
--challenge	string	(none)	Challenge string to sign (required).
--clip	bool	false	Copy signed response to clipboard instead of printing.

Examples:

Sign and print to stdout

tegata sign github --challenge abc123

Sign and copy to clipboard

tegata sign github --challenge abc123 --clip

tegata tag

Add or remove tags on an existing credential. At least one of --add or --remove must be provided.

Usage: tegata tag <LABEL> [FLAGS]

Flags:

Flag	Type	Default	Description
--add	string	(none)	Tag to add (repeatable).
--remove	string	(none)	Tag to remove (repeatable).

Examples:

Add tags

tegata tag github --add work --add totp

Remove a tag

tegata tag github --remove personal

tegata ui

Launch the interactive terminal user interface. If no vault is found, the TUI starts a setup wizard. For a complete walkthrough, see the Using the TUI guide.

Usage: tegata ui

tegata ui

tegata verify

Verify the integrity of the audit log stored in ScalarDL Ledger. Retrieves all event IDs from the entity's collection and validates each event against its stored hash. Reports the total number of events verified and lists per-event faults if any are detected.

Events logged before audit hashes were stored independently are reported as pre-existing and skipped.

Usage: tegata verify [flags]

Exit codes: 0 on success, 9 on integrity violation, 8 on network failure.

Examples:

Verify vault in current directory

tegata verify

Verify vault at explicit path

tegata verify --vault /media/usb/vault.tegata

tegata verify-recovery

Verify a recovery key against your vault by checking its SHA-256 hash against the value stored at vault creation time.

Usage: tegata verify-recovery

tegata verify-recovery

Tegata prompts for your vault passphrase and then the recovery key string. Run this periodically to confirm that your stored recovery key is still valid.

tegata version

Print version information.

Usage: tegata version

tegata version

Environment variables

Variable	Description
TEGATA_VAULT	Default vault path when --vault is not provided.
TEGATA_PASSPHRASE	Vault passphrase for non-interactive use (warning printed to stderr).
TEGATA_BACKUP_PASSPHRASE	Backup passphrase for scripted tegata import.
NO_COLOR	Disable ANSI color output (any non-empty value activates this).

TEGATA_PASSPHRASE is intended for CI and scripting environments. A warning is printed to stderr whenever it is used. The tegata export command never reads from this variable—an interactive prompt is always required when setting a new backup passphrase.

Exit codes

Code	Meaning
0	Success
1	General error (invalid input, missing file)
2	Authentication error (wrong passphrase)
3	Vault error (corrupted, missing, locked)
4	Network error (ScalarDL unreachable)
5	Integrity error (audit chain broken)
8	Network failure during tegata verify
9	Integrity violation detected by tegata verify