tethra. Install CLI

Tethra documentation

One local vault. Desktop or terminal.

Install the standalone CLI, create a vault, track a project, and manage the same encrypted data used by the desktop app.

Install

Install the standalone CLI

The desktop app already bundles the helper it needs. Install this standalone binary when you want to use tethra directly in a terminal or script.

macOS Apple Silicon Linux x64 Windows x64

macOS — Apple Silicon

Four commands. Copy one, run it, move to the next.

  1. Download the archive

    Saves it to your Downloads folder.

    curl -fL "https://usetethra.com/downloads/cli/tethra-aarch64-apple-darwin.tar.gz" -o ~/Downloads/tethra.tar.gz

  2. Unpack it

    Extracts the single tethra binary.

    tar -xzf ~/Downloads/tethra.tar.gz -C ~/Downloads tethra

  3. Put it on your PATH

    Asks for your password, because /usr/local/bin is system-owned.

    sudo install -m 0755 ~/Downloads/tethra /usr/local/bin/tethra

  4. Check it works

    Prints the version number. That is the whole install.

    tethra --version

Linux — x86-64

The same four commands, with the Linux build.

  1. Download the archive

    Saves it to your home folder.

    curl -fL "https://usetethra.com/downloads/cli/tethra-x86_64-unknown-linux-gnu.tar.gz" -o ~/tethra.tar.gz

  2. Unpack it

    Extracts the single tethra binary.

    tar -xzf ~/tethra.tar.gz -C ~ tethra

  3. Put it on your PATH

    Asks for your password, because /usr/local/bin is system-owned.

    sudo install -m 0755 ~/tethra /usr/local/bin/tethra

  4. Check it works

    Prints the version number. That is the whole install.

    tethra --version

Windows — x64 PowerShell

Open PowerShell from the Start menu, then run these four in order.

  1. Download the archive

    Saves it to your temporary folder.

    Invoke-WebRequest "https://usetethra.com/downloads/cli/tethra-x86_64-pc-windows-msvc.zip" -OutFile "$env:TEMP\tethra.zip"

  2. Unpack it

    Creates the folder if it does not exist yet.

    Expand-Archive "$env:TEMP\tethra.zip" -DestinationPath "$env:LOCALAPPDATA\Tethra\bin" -Force

  3. Put it on your PATH

    Safe to run twice — it checks before adding.

    $d = "$env:LOCALAPPDATA\Tethra\bin"; $p = [Environment]::GetEnvironmentVariable("Path", "User"); if ($p -notlike "*$d*") { [Environment]::SetEnvironmentVariable("Path", "$d;$p", "User") }; $env:Path = "$d;$env:Path"

  4. Check it works

    Prints the version number. Open a new terminal if it is not found.

    tethra --version

Alpha signing note: the direct macOS desktop DMG is Apple-notarized. The standalone CLI archives and Windows installer are currently unsigned, so macOS Gatekeeper or Windows SmartScreen may ask you to confirm the download.

First run

Create and unlock your vault

The CLI and desktop app use the same platform data directory and encrypted vault. Your master password is not recoverable, so create an encrypted backup after setup. 

tethra init
eval "$(tethra unlock --print-export)"
tethra doctor
tethra backup create ~/tethra-backup.json

PowerShell users can run tethra unlock and follow the shell-specific export instructions it prints. Use tethra lock to end the CLI session.

Primary workflow

Track a project's API activity

track detects supported APIs in a selected folder, presents the exact changes it proposes, and verifies the local activity path. Start with a dry run when you want to inspect without changing files. 

cd /path/to/your/project
tethra track . --dry-run
tethra track .
tethra track status
tethra track doctor
# Restore managed changes later:
tethra track undo

Vault organization

Projects and credentials

Projects group credentials by codebase and environment. Secret values are prompted without echoing and remain encrypted locally. 

tethra project create my-app --env production
tethra project list
tethra key add --project my-app --name openai --provider openai --environment production
tethra key list --project my-app
tethra key status
tethra key validate <credential-id>

Run tethra project --help and tethra key --help for edit, archive, project-lock, metadata, permissions, version-history, reveal, replacement, removal, and provider-revocation operations.

Secret hygiene

Scan code and govern environment files

Repository scans and environment-file inspection happen locally. Review every result before importing, migrating, exporting, suppressing, or installing a Git hook. 

tethra scan /path/to/repository
tethra hooks install /path/to/repository
tethra env discover --project my-app
tethra env drift --project my-app
tethra mapping --help
tethra run --project my-app -- your-command

Local telemetry

Inspect metadata-only API activity

Tethra's opt-in loopback observer records sanitized host, templated path, method, status, latency, and byte counts. It does not store bodies, header values, credentials, cookies, or query strings. 

tethra run --project my-app --observe -- your-command
tethra observe overview
tethra observe apis
tethra observe sessions
tethra activity
tethra usage report --help

Controlled delivery

Destinations, sync, rotation, and access

Delivery actions are explicit and reviewable. Use dry-run and status commands before executing a sync or rotation against a provider or destination. 

tethra destination --help
tethra sync --help
tethra rotation --help
tethra access --help
tethra notify --help

Operations

Monitor, alert, budget, and recover

tethra monitor
tethra alerts list
tethra usage --help
tethra budget --help
tethra pricing --help
tethra backup create ~/tethra-backup.json
tethra backup verify ~/tethra-backup.json
tethra backup restore --help

Reference

Complete top-level command index

Use tethra <command> --help for every subcommand and flag. Add global --json when you need machine-readable output from supported operations, and --data-dir to select another vault directory.

initCreate an encrypted vault
unlock / lockStart or end a CLI session
change-passwordRe-wrap the vault key
doctor / settingsCheck health and configure thresholds
providerCatalog, capabilities, and doc watches
project / templateOrganize projects and detect stacks
keyManage credential lifecycle and evidence
scan / hooks / suppressFind and prevent committed secrets
monitor / alertsRun checks and manage findings
usage / budget / pricingMeasure usage and cost
activityInspect local activity events
mapping / runInject selected secrets into a process
observe / trackInspect and configure API activity
gatewayConfigure the optional loopback gateway
envDiscover, import, drift, export, and clean up
destination / syncPlan controlled secret delivery
rotation / accessRotate keys and issue bounded local grants
backup / notifyRecover the vault and send configured notices

Support and safety

Paths, verification, and troubleshooting

Default vault locations

The historical api-tracker directory name is retained so existing vaults continue to work. Override it with global --data-dir <DIR> or the TETHRA_DIR environment variable.

macOS~/Library/Application Support/api-tracker/
Linux~/.local/share/api-tracker/ (or XDG_DATA_HOME)
Windows%APPDATA%\api-tracker\
Shared vaultThe desktop app and CLI use the same directory.

Verify the macOS CLI archive

curl -fLO "https://usetethra.com/downloads/cli/tethra-aarch64-apple-darwin.tar.gz"
curl -fLO "https://usetethra.com/downloads/cli/tethra-aarch64-apple-darwin.tar.gz.sha256"
shasum -a 256 tethra-aarch64-apple-darwin.tar.gz
cat tethra-aarch64-apple-darwin.tar.gz.sha256

Common fixes

  • Command not found: open a new terminal after installation, or add the chosen install directory to PATH.
  • CLI says the vault is locked: unlock in the current shell and apply the export instructions it prints. Sessions intentionally do not unlock every terminal globally.
  • Desktop and CLI see different vaults: run tethra doctor and compare its data directory with the location shown in app Settings.
  • Tracking has no traffic: run tethra track status, then tethra track doctor. Use tethra track undo to restore files changed by the managed setup.
  • Need a flag or subcommand: run tethra <command> --help. The complete top-level index is above.

Security boundary

Credential values are encrypted locally, but names, notes, paths, and other operational metadata can exist unencrypted in the local database. Protect the OS account and disk, use a strong master password, and keep encrypted backups off-device. The master password is never stored and cannot be recovered.

Tethra is public-alpha software. Test provider, sync, rotation, and observability workflows with non-production credentials before relying on them for sensitive systems.

Read the onsite Privacy Policy and Terms for analytics, network-processing, local-data, and service limitations.