Encrypted local secret storage for agents and automation. Single-file Node CLI with no npm dependencies at runtime (only the Node.js standard library).
Repository: https://github.com/alancnet/agent-secret
npm (recommended)
npm install -g agent-secretFrom a clone
git clone https://github.com/alancnet/agent-secret.git
cd agent-secret
chmod +x agent-secret
# optional: add this directory to PATH, or invoke with node:
node ./agent-secret --helpRequires Node.js 18+.
# Defaults use XDG data dir — see “Data location” below. Override only if needed:
# export AGENT_SECRET_KEY_PATH="$HOME/..."
agent-secret set API_TOKEN "your-token" "production API"
agent-secret ls
agent-secret get API_TOKEN
# --export only if programs you spawn must inherit the variable (see Commands → env)
source <(agent-secret env --export API_TOKEN)
agent-secret infoUse -v / --verbose before a subcommand to print the resolved store path and key source to stderr (never secret values). Run with no arguments to see a short usage summary (exit code 2).
Defaults follow the XDG Base Directory layout for user data:
| Path | |
|---|---|
| Data directory | $XDG_DATA_HOME/agent-secret if XDG_DATA_HOME is set, otherwise ~/.local/share/agent-secret |
| Encrypted store | <data-dir>/secrets.json |
| Key file | <data-dir>/key.json |
Override with AGENT_SECRET_JSON_PATH and AGENT_SECRET_KEY_PATH (see --help). When using the default data directory, the directory is created with mode 0700 (best-effort chmod).
- Master key: Prefer
AGENT_SECRET_KEY_PATH(JSON file) or the default key path under the data directory. If you setAGENT_SECRET_KEY, the raw value is visible in the process environment on many systems (e.g.ps,/proc/<pid>/environon Linux). Use the key file when feasible. - Shell history: Prefer
agent-secret set NAME -and pipe the secret on stdin so the value does not appear in argv. - Logs: Do not log stdout from
getin CI or shared logs. - Terminal stdout:
getandenvrefuse to run when standard output is a terminal (so secrets are not echoed into an interactive session). Pipe or redirect instead (get KEY | cat), or pass global--unsafeif you accept printing secrets to the terminal. - Concurrency: The CLI uses a lock file next to the encrypted store to reduce concurrent write races; avoid running many writers against the same path at once.
| Command | Purpose |
|---|---|
ls / list / ls --json |
List names (and descriptions); list is an alias for ls; --json for machine-readable output |
get <key> |
Print one secret. Refuses if stdout is a TTY unless --unsafe (see Security notes) |
set <key> <value> |
Set value; use - as value to read from stdin |
del / delete / rm |
Delete one or more keys |
env |
Emit KEY=value (.env style) or with --export / -e emit export KEY=value. Same TTY guard as get. Use --export only if child processes must inherit the variables after you source the output; otherwise omit it. Load with source <(agent-secret env …) (bash, zsh) |
info |
Show version, Node.js version, resolved paths, key source, and secret count (no values) |
completion |
Print a shell completion script for bash, zsh, or fish (see below) |
Run agent-secret --help and agent-secret <command> --help for full detail.
After installing the agent-secret binary on your PATH:
# bash (~/.bashrc)
source <(agent-secret completion bash)
# zsh (~/.zshrc, after compinit)
source <(agent-secret completion zsh)
# fish (~/.config/fish/config.fish)
agent-secret completion fish | sourceA manual page is included in the repository at man/agent-secret.1. Install with man man/agent-secret.1 from a clone, or copy it to a section 1 man path (e.g. /usr/local/share/man/man1/) if you package the tool locally.
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Operational error (missing secret, I/O, decrypt failure, lock timeout, …) |
| 2 | Invalid usage, unknown command, or invoked with no arguments |
npm testMIT — see LICENSE.