# tene-ai/tene architecture

> Architecture diagram of the GitHub repository tene-ai/tene, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tene-ai/tene
- Repository: https://github.com/tene-ai/tene

## Overview

1. **Repo shape: two major products in one monorepo.**  
   The core product is a **Go CLI** (`cmd/tene`, `internal`, `pkg`) that manages encrypted secrets locally. In parallel, `apps/web` is a **Next.js/TypeScript marketing and documentation site** with blog, comparison pages, SEO/AI-discoverability assets, and interactive product content.

2. **CLI entrypoint and command boundary.**  
   `cmd/tene/main.go` is the executable entrypoint. The CLI is built around Cobra-style command dispatch in `internal/cli`, where each command maps to a user-facing operation such as `init`, `set`, `get`, `run`, `list`, `delete`, `import`, `export`, `passwd`, `recover`, `env`, `audit`, and `permissions`.

3. **Core secret storage pipeline.**  
   The storage path is: **command input → CLI layer → vault/crypto layer → local encrypted vault**.  
   Secret data is stored in a local SQLite-backed vault (`internal/vault`, `internal/encfile`) and encrypted with the crypto primitives in `pkg/crypto`. The README and code layout indicate the vault is local-first and offline by default, with no server required for the CLI.

4. **Crypto and key-management subsystem.**  
   `pkg/crypto` contains the cryptographic boundary: encryption/decryption, key derivation, key rotation, X25519/team-key helpers, and memory zeroing. The design centers on a **master password → Argon2id-derived key → XChaCha20-Poly1305-encrypted vault**. This is the main security boundary in the repository.

5. **OS keychain and recovery flow.**  
   The master key is cached in the **native OS keychain** via `internal/keychain` / `go-keyring`, with a fallback/null-store path for non-interactive or unsupported environments. Recovery is handled by `internal/recovery`, which uses a **12-word mnemonic** to restore access if the master password is lost.

6. **Runtime injection is the key “AI-safe” workflow.**  
   The most important execution path is `tene run -- <cmd>`: secrets are decrypted only long enough to be injected into the child process as **environment variables**, then the AI/editor process runs without seeing plaintext in the repo context. This is the product’s core differentiation: secrets are used at runtime, not exposed to the assistant or file system.

7. **Environment and multi-vault separation.**  
   The CLI supports named environments (`dev`, `staging`, `prod`, etc.) through `internal/vaultcfg` and environment-aware command handling in `internal/cli`. That means the same secret name can exist in multiple isolated environments, and command behavior is scoped by the active or explicitly selected environment.

8. **Permissions and safety gates.**  
   `internal/auth` and the CLI permission tables classify commands into tiers such as metadata-only, secret-write, and secret-read. The repo enforces this as an architectural guardrail: some commands can run without unlocking, while value-revealing actions require explicit trust/password handling. There are also safety checks around stdout leakage and delete/get behavior.

9. **Audit, sync, and cloud are present but partially gated.**  
   The codebase includes `internal/audit`, `internal/sync`, and `internal/auth`, plus command files for `login`, `push`, `pull`, `sync`, `team`, and `billing`. However, the README says these cloud features are currently disabled in the released CLI, so architecturally they form a **latent cloud subsystem** rather than the active local-first path. That boundary matters when diagramming what is live versus planned.

10. **Generated AI-editor context files are a first-class output.**  
   `tene init` does more than create a vault: it generates editor-specific guidance files such as `CLAUDE.md`, `.cursor/rules/tene.mdc`, `.windsurfrules`, `GEMINI.md`, and `AGENTS.md`. This is an important output boundary because it bridges the CLI with AI coding tools and affects how the product is discovered and used by agents.

11. **Web app is a separate presentation/runtime stack.**  
   `apps/web` is a **Next.js app** that serves the public site, blog, comparison pages, CLI docs, RSS/sitemap/robots, and structured SEO metadata. It is largely content-driven: MDX blog posts, static data modules, and reusable UI components. It has its own runtime, build pipeline, and asset set, independent of the Go CLI.

12. **Discoverability and agent-facing content extend beyond the app.**  
   The repo contains `llms.txt`, `.well-known/ai.json`, `skills/tene-cli`, and a large `examples/demo` tree. These are not product runtime paths, but they are part of the architecture because they shape how AI agents and humans learn, validate, and adopt the CLI. They act as documentation, evaluation, and onboarding layers.

13. **Build, release, and distribution are standard but important.**  
   The repo uses GitHub Actions (`.github/workflows`), Go tooling (`golangci-lint`, `goreleaser`, `Makefile`), and a `Dockerfile`. For the CLI, distribution is via Go binaries and GitHub Releases; for the website, deployment is a separate Node/Next.js concern. The architecture is therefore split across two deployable surfaces: a CLI binary and a web frontend.

14. **Overall data-flow summary.**  
   The main flow is: **user command → CLI orchestration → permission check → key retrieval/derivation → vault read/write → output or subprocess injection**. The web side flows separately from **content/data modules → Next.js rendering → static/interactive site output**. There is no default backend service in the active CLI path; the repository’s architecture is intentionally centered on local execution, encrypted storage, and AI-safe runtime injection.

Main entry points: [`internal/cli`](https://github.com/tene-ai/tene/tree/main/internal/cli) (User commands), [`internal/vault/vault.go`](https://github.com/tene-ai/tene/blob/main/internal/vault/vault.go) (Vault store), [`internal/cli/root.go`](https://github.com/tene-ai/tene/blob/main/internal/cli/root.go) (CLI dispatch), [`internal/cli/run.go`](https://github.com/tene-ai/tene/blob/main/internal/cli/run.go) (Runtime inject)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_go_cli["Go CLI"]
  node_cmd_main["tene<br/>entrypoint<br/>[main.go]"]
  node_cli_root["CLI dispatch<br/>command router<br/>[root.go]"]
  node_cli_ops["User commands<br/>command set"]
  node_run_inject["Runtime inject<br/>secret runtime<br/>[run.go]"]
  node_cli_init["Init flow<br/>setup flow<br/>[init.go]"]
  node_authz{{"Permissions<br/>policy gate<br/>[permissions.go]"}}
  node_vaultcfg["Environments<br/>env routing<br/>[vaultcfg.go]"]
end

subgraph group_security_core["Security core"]
  node_vault[("Vault store<br/>sqlite vault<br/>[vault.go]")]
  node_encfile["Encfile<br/>encrypted file<br/>[encfile.go]"]
  node_crypto{{"Crypto"}}
  node_keychain[("Keychain<br/>key storage<br/>[keychain.go]")]
  node_recovery["Recovery<br/>mnemonic restore<br/>[recover.go]"]
end

subgraph group_cloud_latent["Cloud latent"]
  node_audit["Audit log<br/>audit subsystem<br/>[manager.go]"]
  node_sync["Sync engine<br/>cloud sync<br/>[engine.go]"]
  node_cloud_cmds["Cloud commands<br/>gated commands<br/>[cloud_disabled.go]"]
end

subgraph group_web_app["Web app"]
  node_web_app["Web site<br/>nextjs app"]
  node_web_content["Content data<br/>mdx/content"]
  node_web_ui["UI components<br/>presentation"]
  node_seo_assets["SEO assets<br/>discoverability"]
end

subgraph group_ai_onboarding["AI onboarding"]
  node_agent_docs["Agent docs<br/>onboarding"]
  node_demo_examples["Demo flows<br/>examples"]
end

node_cmd_main -->|"starts"| node_cli_root
node_cli_root -->|"routes"| node_cli_ops
node_cli_ops -->|"checks"| node_authz
node_cli_ops -->|"scopes"| node_vaultcfg
node_cli_ops -->|"reads/writes"| node_vault
node_vault -->|"persists"| node_encfile
node_encfile -->|"encrypts"| node_crypto
node_vault -->|"caches"| node_keychain
node_keychain -->|"unwraps"| node_crypto
node_cli_ops -->|"restores"| node_recovery
node_recovery -->|"derives"| node_crypto
node_run_inject -->|"loads"| node_vault
node_run_inject -->|"guards"| node_authz
node_run_inject -->|"spawns"| node_cli_root
node_cli_init -->|"generates"| node_agent_docs
node_cloud_cmds -->|"includes"| node_audit
node_cloud_cmds -->|"includes"| node_sync
node_cloud_cmds -.->|"registered by"| node_cli_root
node_web_app -->|"renders"| node_web_content
node_web_app -->|"composes"| node_web_ui
node_web_app -->|"publishes"| node_seo_assets
node_agent_docs -->|"documents"| node_demo_examples
node_seo_assets -->|"supports"| node_agent_docs

click node_cmd_main "https://github.com/tene-ai/tene/blob/main/cmd/tene/main.go"
click node_cli_root "https://github.com/tene-ai/tene/blob/main/internal/cli/root.go"
click node_cli_ops "https://github.com/tene-ai/tene/tree/main/internal/cli"
click node_run_inject "https://github.com/tene-ai/tene/blob/main/internal/cli/run.go"
click node_cli_init "https://github.com/tene-ai/tene/blob/main/internal/cli/init.go"
click node_authz "https://github.com/tene-ai/tene/blob/main/internal/auth/permissions.go"
click node_vaultcfg "https://github.com/tene-ai/tene/blob/main/internal/vaultcfg/vaultcfg.go"
click node_vault "https://github.com/tene-ai/tene/blob/main/internal/vault/vault.go"
click node_encfile "https://github.com/tene-ai/tene/blob/main/internal/encfile/encfile.go"
click node_crypto "https://github.com/tene-ai/tene/tree/main/pkg/crypto"
click node_keychain "https://github.com/tene-ai/tene/blob/main/internal/keychain/keychain.go"
click node_recovery "https://github.com/tene-ai/tene/blob/main/internal/recovery/recover.go"
click node_audit "https://github.com/tene-ai/tene/blob/main/internal/audit/manager.go"
click node_sync "https://github.com/tene-ai/tene/blob/main/internal/sync/engine.go"
click node_cloud_cmds "https://github.com/tene-ai/tene/blob/main/internal/cli/cloud_disabled.go"
click node_web_app "https://github.com/tene-ai/tene/tree/main/apps/web/src/app"
click node_web_content "https://github.com/tene-ai/tene/tree/main/apps/web/content"
click node_web_ui "https://github.com/tene-ai/tene/tree/main/apps/web/src/components"
click node_seo_assets "https://github.com/tene-ai/tene/tree/main/apps/web/public"
click node_agent_docs "https://github.com/tene-ai/tene/tree/main/skills/tene-cli"
click node_demo_examples "https://github.com/tene-ai/tene/tree/main/examples/demo"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmd_main,node_cli_root,node_cli_ops,node_run_inject,node_cli_init,node_authz,node_vaultcfg toneBlue
class node_vault,node_encfile,node_crypto,node_keychain,node_recovery toneAmber
class node_audit,node_sync,node_cloud_cmds toneMint
class node_web_app,node_web_content,node_web_ui,node_seo_assets toneRose
class node_agent_docs,node_demo_examples toneIndigo
```

## Components

### Go CLI

Local-first secret manager and runtime injection product.

- [tene](https://github.com/tene-ai/tene/blob/main/cmd/tene/main.go): entrypoint · Go CLI executable entrypoint. · `cmd/tene/main.go`
- [CLI dispatch](https://github.com/tene-ai/tene/blob/main/internal/cli/root.go): command router · Cobra-style root command and shared command wiring. · `internal/cli/root.go`
- [User commands](https://github.com/tene-ai/tene/tree/main/internal/cli): command set · Core user actions such as init, set, get, run, list, delete, import, export, passwd, recover, env, audit, and permissions. · `internal/cli`
- [Runtime inject](https://github.com/tene-ai/tene/blob/main/internal/cli/run.go): secret runtime · Decrypts secrets briefly and injects them into child process environment variables. · `internal/cli/run.go`
- [Init flow](https://github.com/tene-ai/tene/blob/main/internal/cli/init.go): setup flow · Initializes vault and generates AI/editor guidance files. · `internal/cli/init.go`
- [Permissions](https://github.com/tene-ai/tene/blob/main/internal/auth/permissions.go): policy gate · Command tiering and unlock requirements for metadata, write, and read operations. · `internal/auth/permissions.go`
- [Environments](https://github.com/tene-ai/tene/blob/main/internal/vaultcfg/vaultcfg.go): env routing · Named environment selection and multi-vault scoping. · `internal/vaultcfg/vaultcfg.go`

### Security core

Crypto, vault, keychain, and recovery boundaries.

- [Vault store](https://github.com/tene-ai/tene/blob/main/internal/vault/vault.go): sqlite vault · Local encrypted vault persistence and schema/migration layer. · `internal/vault/vault.go`
- [Encfile](https://github.com/tene-ai/tene/blob/main/internal/encfile/encfile.go): encrypted file · Encrypted local vault file handling. · `internal/encfile/encfile.go`
- [Crypto](https://github.com/tene-ai/tene/tree/main/pkg/crypto): cryptography · Encryption, decryption, KDF, rotation, team keys, X25519, and memory zeroing. · `pkg/crypto`
- [Keychain](https://github.com/tene-ai/tene/blob/main/internal/keychain/keychain.go): key storage · Native OS keychain cache with fallback and null-store paths. · `internal/keychain/keychain.go`
- [Recovery](https://github.com/tene-ai/tene/blob/main/internal/recovery/recover.go): mnemonic restore · 12-word mnemonic based account recovery path. · `internal/recovery/recover.go`

### Cloud latent

Disabled or gated sync and account features.

- [Audit log](https://github.com/tene-ai/tene/blob/main/internal/audit/manager.go): audit subsystem · Audit collection and reading for secret activity and events. · `internal/audit/manager.go`
- [Sync engine](https://github.com/tene-ai/tene/blob/main/internal/sync/engine.go): cloud sync · Conflict handling, merging, envelopes, and queueing for latent cloud features. · `internal/sync/engine.go`
- [Cloud commands](https://github.com/tene-ai/tene/blob/main/internal/cli/cloud_disabled.go): gated commands · Login, push, pull, sync, team, billing, and related cloud surfaces that are currently disabled or gated. · `internal/cli/cloud_disabled.go`

### Web app

Next.js marketing, docs, blog, and comparison site.

- [Web site](https://github.com/tene-ai/tene/tree/main/apps/web/src/app): nextjs app · Public marketing, docs, blog, comparison pages, and SEO routes. · `apps/web/src/app`
- [Content data](https://github.com/tene-ai/tene/tree/main/apps/web/content): mdx/content · Blog posts, comparison data, FAQs, pricing, and static content modules. · `apps/web/content`
- [UI components](https://github.com/tene-ai/tene/tree/main/apps/web/src/components): presentation · Reusable site, blog, comparison, SEO, and interactive UI components. · `apps/web/src/components`
- [SEO assets](https://github.com/tene-ai/tene/tree/main/apps/web/public): discoverability · robots, sitemap, RSS, llms.txt, ai.json, and structured metadata outputs. · `apps/web/public`

### AI onboarding

Repo-wide agent guidance, discoverability, and demos.

- [Agent docs](https://github.com/tene-ai/tene/tree/main/skills/tene-cli): onboarding · Repo guidance, skills, examples, and generated editor instructions for AI tools. · `skills/tene-cli`
- [Demo flows](https://github.com/tene-ai/tene/tree/main/examples/demo): examples · End-to-end scripted demos showing setup, recovery, multi-env, and AI-safe usage. · `examples/demo`

## Connections

- tene → CLI dispatch: starts · Executable enters CLI command dispatch.
- CLI dispatch → User commands: routes · Root command exposes user-facing operations.
- User commands → Permissions: checks · Commands are classified by permission tier and unlock requirements.
- User commands → Environments: scopes · Commands resolve the active named environment.
- User commands → Vault store: reads/writes · Secret operations flow into the local vault layer.
- Vault store → Encfile: persists · Vault data is stored through encrypted file handling.
- Encfile → Crypto: encrypts · Encrypted vault content depends on crypto primitives.
- Vault store → Keychain: caches · Master key material is cached in the OS keychain when available.
- Keychain → Crypto: unwraps · Cached key material is tied to derived crypto keys.
- User commands → Recovery: restores · Recovery command path rebuilds access from mnemonic.
- Recovery → Crypto: derives · Recovery reconstitutes access keys used by the crypto boundary.
- Runtime inject → Vault store: loads · Run path retrieves secrets just before execution.
- Runtime inject → Permissions: guards · Runtime injection requires the appropriate read permission.
- Runtime inject → CLI dispatch: spawns · After injection, the child process executes outside the CLI.
- Init flow → Agent docs: generates · Init creates editor guidance and agent-facing files.
- Cloud commands → Audit log: includes · Cloud surface contains audit-related functionality.
- Cloud commands → Sync engine: includes · Cloud surface contains sync-related functionality.
- Cloud commands → CLI dispatch: registered by · Cloud commands are part of CLI dispatch but are gated or disabled.
- Web site → Content data: renders · Next.js routes are driven by content and data modules.
- Web site → UI components: composes · Pages are assembled from reusable UI components.
- Web site → SEO assets: publishes · Site output includes discoverability and indexing assets.
- Agent docs → Demo flows: documents · Skill and repo guidance are reinforced by scripted demos.
- SEO assets → Agent docs: supports · Discoverability assets help humans and agents find and use the CLI.