agent-secret

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

Install

npm (recommended)

npm install -g agent-secret

From 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 --help

Requires Node.js 18+.

Quick start

# 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 info

Use -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).

Data location

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).

Security notes

• Master key: Prefer AGENT_SECRET_KEY_PATH (JSON file) or the default key path under the data directory. If you set AGENT_SECRET_KEY, the raw value is visible in the process environment on many systems (e.g. ps, /proc/<pid>/environ on 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 get in CI or shared logs.
• Terminal stdout: get and env refuse 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 --unsafe if 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.

Commands

| 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.

Shell completions

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 | source

Man page

A 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.

Exit status

| 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 |

Development

npm test

License

MIT — see LICENSE.