macOS Keychain Credentials

Store secrets in the macOS Keychain, then use them without ever seeing them.

The Keychain is the system secret store: entries are encrypted at rest, unlocked with the login password, and readable only by the logged-in user. This skill wraps it so a secret has exactly one safe path in (the user's clipboard) and one safe path out (the environment of a child process).

scripts/keychain.sh and scripts/registry.sh hold the shared helpers, so nothing else has to be installed.

Throughout, skill_dir means the directory containing this SKILL.md:

skill_dir="<directory containing this SKILL.md>"

The rules that matter

1. Never ask the user to type or paste a secret into the chat. Ask them to copy it to the clipboard, then run pbpaste | store_cred.sh. A secret pasted into the conversation is in the transcript forever.
2. Never print a secret. Not with echo, not in a debug line, not in an error message. Use use_cred.sh so the value goes straight into the child process's environment.
3. Never put a secret in argv. curl -H "Authorization: Bearer sk-..." puts the token in the process list, where any process on the machine can read it. Reference the exported variable inside single quotes instead, so the calling shell never expands it.
4. Never write a secret to a file — not .env, not a config file, not a scratch file, and never into the repository.
5. Never enable shell tracing (set -x) around a command holding a secret.

Storing a credential

Ask the user to copy the secret to the clipboard, then:

pbpaste | "$skill_dir/scripts/store_cred.sh" github-token \
  --description "GitHub PAT, repo + read:org" \
  --validate 'curl -sf -o /dev/null -H "Authorization: Bearer $CRED" https://api.github.com/user'

• SERVICE (github-token here) is the Keychain service name and the handle used everywhere else. Use a short lowercase name; <service>-token or <service>-key reads well.
• --validate is a shell command that must succeed before the secret is stored. It runs with the secret exported as $CRED, so a bad token can never overwrite a working one. It is saved in the registry, so check_cred.sh can re-run it later. Always supply one when the service has a cheap "who am I" endpoint — see references/recipes.md for ready-made ones.
• --env-var NAME overrides the exported variable name, which otherwise comes from the service name (github-token → GITHUB_TOKEN).
• --account ACCOUNT stores a second credential for the same service, e.g. a work and a personal account. It defaults to the macOS username.

Re-running the same command replaces the value and keeps the registered metadata: that is how a token is rotated.

Using a credential

use_cred.sh reads the Keychain and execs the command with the secret in its environment, as both $CRED and the registered variable name:

"$skill_dir/scripts/use_cred.sh" github-token -- \
  bash -c 'curl -sS -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/user' | jq .login

Single quotes around the inner command are load-bearing. With double quotes, the calling shell expands $GITHUB_TOKEN before curl starts — putting the secret into argv and into the agent's transcript.

Define a helper once per shell session for repeated calls against one API:

gh_api() {
  "$skill_dir/scripts/use_cred.sh" github-token -- \
    bash -c 'curl -sS -H "Authorization: Bearer $GITHUB_TOKEN" \
                  -H "Accept: application/vnd.github+json" \
                  "$@"' _ "$@"
}

gh_api https://api.github.com/user/repos?per_page=5 | jq -r '.[].full_name'

Two credentials at once: nest the calls.

"$skill_dir/scripts/use_cred.sh" github-token -- \
  "$skill_dir/scripts/use_cred.sh" openai-key -- ./deploy.sh

A CLI that reads a secret from stdin can take it straight from the pipe:

"$skill_dir/scripts/get_cred.sh" github-token --unsafe-print | gh auth login --with-token

get_cred.sh writes the raw secret to stdout, which is why it demands --unsafe-print. Only ever use it on the left side of a pipe into a program that consumes it. Never run it as a bare command, never capture it into a shell variable that later gets echoed, and never use it to "check" a value.

Checking and listing

"$skill_dir/scripts/check_cred.sh" github-token   # exit 0 valid, 1 missing, 3 present but invalid
"$skill_dir/scripts/list_creds.sh"                # every registered credential and its status
"$skill_dir/scripts/list_creds.sh" --validate     # also re-runs each validation command

Run check_cred.sh before a task that depends on a credential, and after any 401/403. Exit 3 means the secret is expired or revoked — ask the user for a fresh one and store it the same way.

Deleting a credential

Deleting is unrecoverable: the secret cannot be read back afterwards. Confirm the exact service with the user first, then:

"$skill_dir/scripts/delete_cred.sh" github-token --yes

Workflow

When a task needs a credential:

1. list_creds.sh — is something already stored for this service?
2. check_cred.sh SERVICE — is it still valid?
3. If missing or invalid, tell the user exactly where to get the secret (see references/recipes.md for the common ones and the scopes each needs), ask them to copy it to the clipboard, then run pbpaste | store_cred.sh SERVICE --validate '...'.
4. Do the work through use_cred.sh.

If the user pastes a secret into the chat anyway, store it, then tell them plainly that the value is in the transcript and should be rotated.

Troubleshooting

Registry

~/.config/macos-keychain-creds/registry.tsv (override with MACOS_KEYCHAIN_CREDS_HOME or MACOS_KEYCHAIN_CREDS_REGISTRY) records service, account, env var, description, and validation command — no secrets. It exists because the Keychain cannot be listed by prefix without an interactive security dump-keychain prompt. It is safe to read, and safe to back up.

References

• references/recipes.md — copy-paste setup and usage for GitHub, GitLab, OpenAI, Anthropic, Slack, Stripe, npm, Docker registries, and generic Bearer/Basic/header APIs.
• references/agent-integration.md — reading these credentials from another skill, a script, or a hook, and choosing between use_cred.sh and get_cred.sh.