CLI tool to store API keys in the OS credential store (Keychain, Secret Service,
Credential Manager) and serve them over a local HTTP API — no more hard-coding
secrets in scripts, configs, or .env files.
Keep secrets out of your source tree.
keyctlwrites each key to your operating system's native credential store and reads it back on demand, whether you're running from the shell, Python, Node, or a Pi coding-agent session.
- What is keyctl?
- Why use keyctl?
- Installation
- CLI reference
- HTTP daemon mode
- Integration examples
- Security
- Docker / advanced
- License
keyctl is a small, dependency-free CLI (#!/usr/bin/env python3) that stores
API keys in your operating system's native credential store instead of in local
files:
| Platform | Backend | Storage location |
|---|---|---|
| macOS | Keychain (security) |
keyctl:{keyword} generic password items |
| Linux | Secret Service DBus (secret-tool) |
Per-item attributes in the Secret Service DB |
| Windows / WSL | Credential Manager (cmdkey) |
Generic credentials |
Keys are never written to plaintext files on disk. Each key is stored under a
keyword (a short name you choose, like gemini or github), and retrieved
by that same keyword.
- Never hard-code secrets. No API keys in scripts,
models.json,.envfiles, or CI configs. - Cross-platform. One command works on macOS, Linux, and Windows/WSL.
- Callable from anywhere. Shell, Python, Node, or a Pi coding-agent tool can all read a key without knowing where it lives.
- Optional HTTP daemon. Expose keys over a local loopback API so long-running processes (servers, agents, IDEs) can fetch keys without spawning a subprocess.
- Audit and rotate. List keywords, remove individual keys, and rotate compromised credentials in one command.
git clone https://github.com/your-repo/keyctl.git
cd keyctl
make installmake install copies the keyctl script into ~/.local/bin (or ~/bin).
Make sure that directory is on your PATH:
export PATH="$HOME/.local/bin:$PATH"
# add the line above to your ~/.bashrc, ~/.zshrc, or equivalentThen verify:
keyctl --helpIf you don't have make, just copy the script somewhere on your PATH:
# macOS / Linux
cp keyctl ~/.local/bin/keyctl
chmod +x ~/.local/bin/keyctl
# Windows (Git Bash / WSL)
cp keyctl ~/bin/keyctl
chmod +x ~/bin/keyctlThere is no official Homebrew or Linux distro package yet. You can create one
from the single-file keyctl script:
- Homebrew (macOS/Linux): write a Ruby formula that copies
keyctlinto the Homebrew prefixbindirectory. - Linux package: install
keyctlto/usr/local/binand ensuresecret-tool(libsecret) is available on the system.
Every subcommand prints a short status message on success and exits non-zero on failure.
Store a key under a keyword. You can pass the value with --value, read it
from stdin with --stdin, or be prompted interactively.
# Interactive prompt (recommended — value never touches shell history)
keyctl add gemini
# Pass value inline (value appears in process list/shell history — use with care)
keyctl add github --value ghp_xxxxxxxxxxxx
# Pipe from stdin
echo "sk-..." | keyctl add openai --stdinPrint the stored key for a keyword to stdout.
keyctl get geminiCapture into a shell variable:
GEMINI_API_KEY=$(keyctl get gemini)List all stored keywords.
keyctl listExample output:
gemini
github
openai
Delete the stored key for a keyword.
keyctl remove geminiStart the local HTTP API daemon.
# Default: binds to 127.0.0.1:9099
KEYCTL_TOKEN=my-secret-token keyctl daemon
# Custom port
KEYCTL_TOKEN=my-secret-token keyctl daemon --port 9099The --port option sets the TCP port (default 9099). The token is read from
the KEYCTL_TOKEN environment variable — see Authentication.
The daemon is a small threaded HTTP server useful for long-running processes
that need key lookups without spawning keyctl on every request.
- Default bind:
127.0.0.1:9099(loopback only) - Custom port:
keyctl daemon --port <port> - Auth: every request must include
Authorization: Bearer <token>, where<token>is the value of theKEYCTL_TOKENenvironment variable seen by the daemon process. IfKEYCTL_TOKENis unset, all requests return401.
Start it in the background:
export KEYCTL_TOKEN=$(openssl rand -hex 16)
nohup keyctl daemon --port 9099 > keyctl-daemon.log 2>&1 &export KEYCTL_TOKEN=my-secret-token
keyctl daemon --port 9099All client requests must send:
Authorization: Bearer my-secret-token
Set KEYCTL_TOKEN to a strong, random value and restrict the file where you
keep it (see Recommended file modes).
| Method | Path | Description |
|---|---|---|
GET |
/health |
Health check |
GET |
/list |
List stored keywords |
POST |
/lookup |
Look up a key by keyword |
POST |
/add |
Store a keyword/key pair |
DELETE |
/remove |
Remove a keyword |
curl -s -H "Authorization: Bearer $KEYCTL_TOKEN" \
http://127.0.0.1:9099/healthResponse:
{"status": "ok"}curl -s -H "Authorization: Bearer $KEYCTL_TOKEN" \
http://127.0.0.1:9099/listResponse:
{"keywords": ["gemini", "github", "openai"]}curl -s -X POST -H "Authorization: Bearer $KEYCTL_TOKEN" \
-H "Content-Type: application/json" \
-d '{"keyword":"gemini"}' \
http://127.0.0.1:9099/lookupResponse:
{"keyword": "gemini", "key": "sk-..."}curl -s -X POST -H "Authorization: Bearer $KEYCTL_TOKEN" \
-H "Content-Type: application/json" \
-d '{"keyword":"gemini","key":"sk-..."}' \
http://127.0.0.1:9099/addResponse:
{"status": "stored"}curl -s -X DELETE -H "Authorization: Bearer $KEYCTL_TOKEN" \
"http://127.0.0.1:9099/remove?keyword=gemini"Response:
{"status": "removed"}From a Pi coding-agent session you can shell out to keyctl to fetch a key
without hard-coding it, or inject it into the agent's model configuration.
Shell out from a Pi tool:
GEMINI_KEY=$(keyctl get gemini)Read the token into $GEMINI_API_KEY:
export GEMINI_API_KEY=$(keyctl get gemini)Inject into models.json (Pi model config):
KEY=$(keyctl get gemini)
python3 - "$KEY" <<'PY'
import json, sys
key = sys.argv[1]
with open("models.json") as f:
cfg = json.load(f)
cfg.setdefault("models", {}).setdefault("gemini", {})["apiKey"] = key
with open("models.json", "w") as f:
json.dump(cfg, f, indent=2)
PYTip: keep
models.jsonout of version control (add it to.gitignore).
Via the HTTP daemon (requests):
import os
import requests
TOKEN = os.environ["KEYCTL_TOKEN"]
BASE = "http://127.0.0.1:9099"
headers = {"Authorization": f"Bearer {TOKEN}"}
# Look up a key
resp = requests.post(f"{BASE}/lookup", headers=headers,
json={"keyword": "gemini"})
resp.raise_for_status()
api_key = resp.json()["key"]
# List all keywords
resp = requests.get(f"{BASE}/list", headers=headers)
print(resp.json()["keywords"])Via subprocess (keyctl get ...):
import subprocess
def get_key(keyword: str) -> str:
result = subprocess.run(
["keyctl", "get", keyword],
capture_output=True, text=True, check=True,
)
return result.stdout.strip()
api_key = get_key("gemini")Via fetch to the daemon:
const TOKEN = process.env.KEYCTL_TOKEN;
const BASE = "http://127.0.0.1:9099";
async function getKey(keyword) {
const res = await fetch(`${BASE}/lookup`, {
method: "POST",
headers: {
"Authorization": `Bearer ${TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ keyword }),
});
if (!res.ok) throw new Error(await res.text());
const data = await res.json();
return data.key;
}
const apiKey = await getKey("gemini");
console.log(apiKey);Copy a key to the clipboard (macOS pbcopy, Linux xclip/wl-copy, Windows
clip.exe):
# macOS
keyctl get gemini | pbcopy
# Linux (X11)
keyctl get gemini | xclip -selection clipboard
# Linux (Wayland)
keyctl get gemini | wl-copy
# Windows / WSL
keyctl.exe get gemini | clip.exe| Platform | Mechanism | Item name |
|---|---|---|
| macOS | Keychain (security add-generic-password) |
keyctl:{keyword} |
| Linux | Secret Service DBus (secret-tool store) |
attribute keyctl:{keyword} |
| Windows / WSL | Credential Manager (cmdkey) |
generic credential API:{keyword} |
Keys are never written to plaintext files outside the OS credential store.
Each key is stored independently under its keyword. There is no master vault
file. Listing (keyctl list) returns only keywords — never values. To read a
value you must request it by keyword.
If you store KEYCTL_TOKEN in a file (e.g. for direnv or a systemd unit),
restrict it to owner read/write only:
chmod 600 /path/to/keyctl-token.envNever put a real token or API key in a file that is world-readable or checked into version control.
- Remove the old credential:
keyctl remove <keyword> - Store the new credential:
keyctl add <keyword>(or viaPOST /add) - Restart any long-running process holding the old key so it picks up the new value on its next lookup.
Rotate immediately if you suspect a key was committed, logged, or exposed.
Never add real API keys, tokens, or secrets to git:
# Do NOT do this
echo "sk-..." > key.txt
git add key.txtAdd secrets files to .gitignore:
*.env
keyctl-token.env
models.jsonIf a real key is accidentally committed, treat it as compromised: revoke it in
the provider's dashboard, remove it from git history, and store a fresh key via
keyctl add.
A minimal Docker image is provided at docker/Dockerfile for running the
daemon in a container:
docker build -t keyctl -f docker/Dockerfile .
docker run -e KEYCTL_TOKEN=my-secret-token -p 9099:9099 keyctl daemon --port 9099Mount your host credential store into the container if the daemon needs to read existing keys; otherwise the container starts with an empty store.
MIT