@hasna/secrets

A local encrypted secrets vault for AI agents, CLIs, and developer machines. Store API keys, passwords, tokens, and other credentials without committing them to source control.

Install

bun install -g @hasna/secrets

CLI Usage

secrets --help
secrets docs

Common Commands

Store a secret:

secrets set hasnaxyz/anthropic/live/api_key "$ANTHROPIC_API_KEY" \
  --type api_key \
  --label "Anthropic API Key (live)"

Read a secret value:

secrets get hasnaxyz/anthropic/live/api_key

List and search without printing secret values:

secrets list
secrets list hasnaxyz/anthropic
secrets search anthropic

Inspect audit history:

secrets audit hasnaxyz/anthropic/live/api_key

Export redacted JSON for review:

secrets export --redact

Delete a secret:

secrets delete hasnaxyz/anthropic/live/api_key

Key Format

Use slash-delimited keys:

<division>/<service>/<env>/<name>

Examples:

hasnaxyz/anthropic/live/api_key
hasna/local/apple03/tool/exa/api-key
alumia-production/oauth/youtube_client_secret

Secret Types

Supported types:

api_key, password, token, credential, other

Optional TTL values can be attached when setting a secret:

secrets set temp/session "$TOKEN" --type token --ttl 24h
secrets gc

MCP Usage

Install the MCP server into local AI agents:

secrets mcp install --target codex
secrets mcp install --target claude
secrets mcp install --target gemini

Agents connect over stdio by running:

secrets mcp

The MCP exposes these tools:

list_secrets(namespace?)
search_secrets(query)
get_secret(key)
set_secret(key, value, type?, label?, ttl?)
delete_secret(key)
audit_log(key?, limit?)
register_user(id, name, type?)
list_users(type?)

list_secrets and search_secrets return metadata only. get_secret returns the raw value, so use it only when the agent needs to pass the secret into a tool or command.

Env-File Bridge

The vault can import from and export to the conventional machine-local ~/.secrets tree:

~/.secrets/{division}/{service}/live.env
~/.secrets/{division}/{business}/{service}/live.env

Import .env files into the vault:

secrets import-env --dir ~/.secrets --dry-run
secrets import-env --dir ~/.secrets --overwrite

Export vault entries back to .env files:

secrets export-env --dir ~/.secrets --dry-run
secrets export-env --dir ~/.secrets --force

Cloud Sync

This package supports cloud sync via @hasna/cloud:

cloud setup
cloud sync push --service secrets
cloud sync pull --service secrets

Data Directory

Data is stored in ~/.hasna/secrets/.

secrets path
secrets key

The vault database lives at ~/.hasna/secrets/vault.db. Key material lives in ~/.hasna/secrets/vault.key for local-key mode or ~/.hasna/secrets/vault.key.enc for KMS envelope-encryption mode.

Safety Notes

• list, search, and export --redact do not print secret values.
• get and MCP get_secret return raw secret values.
• Never paste secret values into commits, logs, issues, PRs, or chat messages.
• Keep .env, .env.local, .secrets/, and .connect/ out of git.

License

Apache-2.0 -- see LICENSE