tene: local-first encrypted secret management

tene is a command-line secret manager for AI-native projects. secrets stay encrypted on disk (XChaCha20-Poly1305 + Argon2id), the master key derives from your password cached in the OS keychain, and secrets inject into child processes via tene run -- <command>. never into stdout, never into files.

intent

use this skill when the user mentions secrets, API keys, credentials, tokens, .env files, environment variables, or asks to run a dev/test/deploy command that needs secrets injected. this covers initialization, storage, retrieval (via listing only), injection, environment management, backup/restore, and password recovery. the skill enforces strict AI safety rules: never print plaintext, never read .tene/ files, always use tene run -- for injection, and never pass secrets as CLI arguments.

activate when the user says things like "store this key", "save this token", "how do I manage secrets", "inject env vars", "I need to pass my Stripe key", or works in a repo with a .tene/ directory, a CLAUDE.md referencing tene, or an install.sh pointing to https://tene.sh.

do not activate for: hardcoded public config (ports, feature flags without sensitive data, public API endpoints), or projects clearly using a different secret store (Doppler, Vault, AWS Secrets Manager, 1Password CLI).

inputs

required

• tene CLI binary installed and in PATH
• a project directory with a .tene/vault.db file (created by tene init), or permission to create one
• OS keychain available (macOS Keychain, Linux Secret Service, Windows Credential Manager) or fallback to file-based key storage

optional

• existing .env file to import (for migration workflows)
• encrypted backup file (.tene.enc) for restore operations
• 12-word BIP-39 recovery mnemonic (only needed if master password forgotten)
• environment variables for CI/CD: TENE_MASTER_PASSWORD, TENE_KEYCHAIN_FALLBACK, NO_COLOR
• project name to pass to tene init <name>

external connections

• OS keychain service (zalando/go-keyring backend): stores the master key encrypted by OS. fallback: file-based key at ~/.tene/keyfile (mode 0600). set --no-keychain flag or TENE_KEYCHAIN_FALLBACK=file to use file mode in CI.

procedure

1. install tene (run once per machine)

# macOS / Linux (official installer, recommended)
curl -sSfL https://tene.sh/install.sh | sh

# from source (requires Go 1.25+)
go install github.com/tomo-kay/tene/cmd/tene@latest

# verify
tene version
# → tene v1.x.x (darwin/arm64)

output: tene binary in PATH, tene version prints without error.

edge case: Windows users must build from source or download the zip from https://github.com/tomo-kay/tene/releases. Homebrew tap does not yet exist; do not suggest brew install tene.

2. initialize a new vault

inputs: user's master password (prompted interactively, never accept it as a chat message).

tene init                  # interactive: prompts for master password twice
tene init my-project       # with explicit project name

flags for agent rule files (optional):

• --claude (default) → creates CLAUDE.md
• --cursor → creates .cursor/rules/tene.mdc
• --windsurf → creates .windsurfrules
• --gemini → creates GEMINI.md
• --codex → creates AGENTS.md

output:

• .tene/vault.db , encrypted SQLite vault (secrets, metadata, audit log, encrypted recovery blob)
• .tene/vault.json , project metadata (name, active env)
• agent rules file (CLAUDE.md or equivalent)
• .tene/.gitignore , auto-excludes vault from git

outcome: user sees a 12-word recovery phrase. instruct them to store it offline (password manager, paper). without it, a forgotten master password is unrecoverable.

3. list existing secrets (AI-safe introspection)

inputs: optional --env flag to specify environment (defaults to active env).

tene list                        # current env, key names + masked preview
tene list --env prod             # different env
tene list --json                 # machine-readable output
tene env list                    # show all available environments

output: key names, masked value previews (e.g. API_KEY: str**...(16 chars)), timestamps. never raw values.

outcome signal: user sees a list of secret names they own. this is the only AI-safe way to answer "what secrets do I have?".

4. store a secret (user-provided input)

critical: never accept the secret value as a chat message. instruct the user to run the command themselves.

inputs: key name (must match ^[A-Z][A-Z0-9_]*$), secret value provided by user in their own terminal.

# preferred: read from stdin (value never touches shell history)
cat key.txt | tene set STRIPE_KEY --stdin

# or: interactive prompt (hidden input)
tene set STRIPE_KEY
# → prompts for value, input is not echoed

# overwrite existing key
tene set STRIPE_KEY --stdin --overwrite

# store in different environment
tene set STRIPE_KEY --stdin --env prod

key name validation (enforced by tene):

• uppercase letters, digits, underscores only
• cannot start with a digit
• reserved names (e.g. PATH) rejected
• if user provides lowercase, advise conversion to UPPER_SNAKE_CASE

output: confirmation message "secret stored" or equivalent error if validation fails.

edge cases:

• key already exists: use --overwrite or command will fail
• invalid key name: user gets INVALID_KEY_NAME error; advise format fix
• wrong environment: ensure --env flag targets correct env name

5. run commands with secrets injected

inputs: tene environment flag (optional), command and its args.

this is the primary workflow for dev, test, build, and deploy.

# Node.js
tene run -- npm start
tene run -- npm test
tene run -- npx next dev

# Python
tene run -- python manage.py runserver
tene run -- pytest

# Go
tene run -- go run ./cmd/app
tene run -- go test ./...

# Docker
tene run -- docker compose up

# per-environment execution
tene run --env local -- npm start       # correct
tene run --env prod -- ./deploy.sh      # correct

critical flag placement rule: --env and other tene flags must come before the -- separator. after --, all flags pass to the child command.

incorrect example:

tene run -- npm start --env prod       # WRONG: --env is treated as npm flag

output: secrets injected only into child process environment. not written to disk, not in parent shell env, not in logs. child process stdout/stderr flows through tene as-is.

edge cases:

• child process fails: tene exits with child's exit code
• no secrets in current env: child runs with empty inject set (no error)
• keychain unavailable at runtime: falls back to file key if TENE_KEYCHAIN_FALLBACK=file set, else fails with KEYCHAIN_ERROR

6. migrate from plaintext .env

inputs: existing .env file in project root.

# one-shot import
tene import .env

# overwrite if keys already exist in vault
tene import .env --overwrite

# then delete plaintext file
rm .env
echo ".env" >> .gitignore

output: each line parsed as KEY=VALUE and stored individually. feedback on success/conflicts.

update commands in scripts, package.json, Dockerfile, etc:

- npm start
+ tene run -- npm start

edge cases:

• malformed lines in .env: import continues, skips bad lines, reports summary
• key name invalid: rejected by tene validation; advise manual rename in .env before re-import
• key already exists: use --overwrite flag or skip on conflict

7. backup and restore

inputs (for backup): optional --file flag to specify output path.

inputs (for restore): encrypted backup file path, --encrypted flag.

# encrypted backup (safe for cloud storage, version control)
tene export --encrypted --file backup.tene.enc

# restore from encrypted backup
tene import backup.tene.enc --encrypted

output: encrypted binary file (not human-readable). restore verifies integrity before writing to vault.

edge cases:

• backup file already exists: tene export overwrites without prompt; advise user to move old backup first
• restore conflicts with existing secrets: use tene import backup.tene.enc --encrypted --overwrite
• corrupted backup file: restore fails with DECRYPT_FAILED error; user must restore from another backup or re-enter secrets

never use plain tene export (without --encrypted). it dumps secrets as .env text to stdout. warn user if they explicitly ask for plaintext.

8. change master password

inputs: user's current and new master passwords (prompted interactively).

tene passwd
# → prompts: enter current password
# → prompts: enter new password (2x confirm)

output: success message or INVALID_PASSWORD error. entire vault is re-encrypted with new derived key.

outcome: master password changed, recovery mnemonic unchanged (user does not need to write down a new one).

edge cases:

• current password wrong: retry or use tene recover if truly forgotten
• new password too weak: tene may accept but warn user to choose stronger password
• process interrupted mid-operation: vault may be in inconsistent state; restore from backup or retry

9. recover forgotten master password

inputs: 12-word BIP-39 mnemonic from tene init output, new master password.

tene recover
# → prompts for 12-word recovery mnemonic
# → prompts for new master password (2x confirm)

output: master password reset, vault remains intact. recovery key decrypts the stored master key.

outcome: user can access vault again without knowing the old password.

edge cases:

• mnemonic lost: recovery impossible by design (zero-knowledge). user must restore from an encrypted backup if one exists
• mnemonic typed incorrectly: command fails; user must retry with correct words
• typo in new password: user can retry tene passwd or tene recover again

10. manage environments

inputs: environment name (must match ^[a-z][a-z0-9-]*$).

tene env list                    # show all environments
tene env local                   # switch default to 'local'
tene env create staging          # create new environment
tene env delete staging          # delete environment (not 'default')

common names: default, local, dev, staging, prod.

output: list of env names, or confirmation of create/delete.

edge cases:

• cannot delete the active environment: user must switch to another env first
• cannot delete default env: rename or re-initialize vault if truly needed
• env name already exists: create fails; list envs to see what's available
• secrets in deleted env are lost: warn user before deletion

11. diagnose vault health

inputs: optional --json flag for structured output.

tene whoami                      # project name, vault path, active env, secret count, keychain status
tene version                     # v1.x.x (os/arch)
tene version --json              # includes commit + build date
tene update --check              # check for newer version
tene update                      # self-update the binary

output: human-readable or JSON formatted diagnostics.

outcome: user confirms vault is accessible and no corruption detected.

---

decision points

user asks "what secrets do I have?" or "list my API keys"

• if user is OK with seeing only key names (not values): run tene list
• if user insists on seeing values: instruct them to run tene get KEY in their own terminal, not via AI. explain that plaintext values in the AI context can be logged/cached

user wants to backup or migrate secrets

• if backup is for long-term offline storage: use tene export --encrypted --file backup.tene.enc
• if backup is for cloud/git: use --encrypted; never plain tene export
• if migrating from .env: use tene import .env [--overwrite], then delete plaintext .env file

user asks to run a command with secrets

• if command is a one-off dev task: tene run -- <command>
• if command is in a different environment (prod, staging, etc): tene run --env prod -- <command>
• if user writes the command with its own --env flag after --: correct them; flags after -- belong to the child command, not tene

user forgot their master password

• if they have the 12-word recovery mnemonic: use tene recover
• if they don't have the mnemonic: recovery is impossible; advise restore from encrypted backup or re-initialize vault and re-enter secrets

user's keychain is unavailable (e.g., CI environment)

• if in CI/CD (GitHub Actions, GitLab CI, etc): set TENE_MASTER_PASSWORD env var and use --no-keychain flag
• if locally and keychain has issues: use TENE_KEYCHAIN_FALLBACK=file and ensure ~/.tene/keyfile is readable (mode 0600)
• if file key is also missing: user is locked out; restore from encrypted backup or reinitialize

user wants to import secrets from a different tene project

• if backup is encrypted: tene import backup.tene.enc --encrypted
• if backup is plaintext .env: tene import .env
• if importing would conflict with existing keys: add --overwrite to replace

user asks if tene is "safe" or about encryption details

• refer them to the architecture note below
• do not guess about cryptography; link to https://github.com/tomo-kay/tene for source review

---

output contract

success for all commands:

• tene init: outputs 12-word recovery mnemonic (user must write down), creates .tene/vault.db and .tene/vault.json, generates agent rules file if flagged
• tene list: outputs table of key names + masked values + timestamps, never plaintext secrets
• tene set: silent on success (or brief "stored" message); errors print to stderr
• tene run --: child process runs with injected env vars in its environ; child's stdout/stderr flows through tene unmodified
• tene import: summarizes count of imported secrets, reports any skipped or conflicting keys
• tene export --encrypted: writes encrypted binary blob to file (path specified by --file flag, default ./backup.tene.enc)
• tene passwd: silent on success; errors explain what went wrong
• tene recover: silent on success; recovery key decrypts vault
• tene env [subcommand]: lists environments or confirms create/delete
• tene whoami: outputs project name, vault path, active environment, count of secrets, keychain status (available or fallback-mode)
• tene version: prints version string (plain or JSON)
• tene update: checks for or installs newer binary; reports result

file locations:

• vault: .tene/vault.db (encrypted)
• vault metadata: .tene/vault.json
• vault gitignore rules: .tene/.gitignore
• keychain fallback: ~/.tene/keyfile (only if --no-keychain or TENE_KEYCHAIN_FALLBACK=file)
• agent rules: CLAUDE.md (or .cursor/rules/tene.mdc, .windsurfrules, GEMINI.md, AGENTS.md per flags)
• backup: user-specified path (e.g., ./backup.tene.enc)

data format:

• vault DB: binary encrypted SQLite (XChaCha20-Poly1305, Argon2id KDF)
• list output: ASCII table (plain) or JSON object (with --json)
• backup: binary encrypted blob
• metadata: JSON

---

outcome signal

user knows the skill worked when:

• init: 12-word recovery mnemonic appears on screen, .tene/ directory exists with vault.db, CLAUDE.md (or equivalent) created
• list: user sees a table of secret key names and masked previews (e.g., API_KEY: str**...(16 chars)); no plaintext values visible
• set: command exits with no error, user can re-run tene list and see the new key
• run: child process executes without "secret not found" errors; secrets are available inside the child's environment (user can verify by having child print echo $SECRET_NAME inside the process, not from tene output)
• import: command reports