Keychain Access

intent

manage macOS Keychain items safely via the security CLI. use this skill when the user needs to list, retrieve, store, update, or delete generic passwords. the helper wraps security calls with confirmation gates on destructive ops, masks secrets by default, and supports dry-run previews so you can inspect commands before they touch the keychain.

inputs

• keychain helper script: ./skills/keychain-access/keychain-access.sh (bundled).
• macOS system requirement: security binary present on PATH (standard on macOS 10.6+).
• keychain access permissions: if targeting a non-default keychain, the user's login credentials must have access to that keychain file. prompts for unlock password if the keychain is locked.
• environment setup: optional. if using --password-env VAR, the variable must be set in the calling shell. the helper reads and unsets it immediately after use.
• stdin: required for set operations if using --password-stdin; otherwise the helper prompts interactively if stdin is a TTY.
• service and account parameters: string identifiers for the credential. service and account together form the lookup key. substring matching is supported in list operations but full exact matches are required for get, set, and delete.

procedure

1. list credentials: invoke ./skills/keychain-access/keychain-access.sh list [--keychain PATH] [--service NAME] [--account NAME] [--dry-run]. the helper scans the target keychain (or default search list if not specified) via security dump-keychain, filters by service/account if provided (substring match), and prints matching entries as service/account/label rows. use --dry-run to preview the dump command without executing it. output is human-readable summary or "no matching entries found" if the result set is empty.

2. get a credential: invoke ./skills/keychain-access/keychain-access.sh get --service SERVICE --account ACCOUNT [--keychain PATH] [--raw] [--dry-run]. both --service and --account are required to avoid ambiguity. the helper queries via security find-generic-password and returns metadata (keychain path, version, class, attributes). password is masked by default; add --raw only when the user explicitly requests the secret value. use --dry-run to preview the find command without querying the keychain. if no matching entry exists, the helper reports "credential not found" and exits with status 1.

3. set a credential: invoke printf '<PASSWORD>' | ./skills/keychain-access/keychain-access.sh set --service SERVICE --account ACCOUNT --password-stdin [--keychain PATH] [--yes] [--dry-run]. password source options: pipe via stdin (preferred, --password-stdin), read from env var and unset it immediately (--password-env VAR), or let the helper prompt interactively if stdin is a TTY and no source is provided. the legacy --password flag is supported but insecure; the helper warns if it is used. if a matching service/account already exists, the helper announces the pending update and prompts for confirmation before overwriting (use --yes to skip the prompt). use --dry-run to print the security add-generic-password invocation with the password redacted; the helper exits before checking for an existing entry or prompting.

4. delete a credential: invoke ./skills/keychain-access/keychain-access.sh delete --service SERVICE --account ACCOUNT [--keychain PATH] [--yes] [--dry-run]. the helper verifies the entry exists and always prompts before deletion; use --yes to skip the prompt once the user has authorized removal. use --dry-run to preview the security delete-generic-password invocation; the helper exits before verifying the entry or prompting. if the entry does not exist, the helper reports "credential not found" and exits with status 1 without prompting.

decision points

• if the user wants to reveal a secret: use get --raw. without --raw, the password is masked in output. secrets are never printed unless explicitly requested.
• if the user is automating credential management: use --yes to bypass confirmation prompts on set and delete. manual confirmation is the default for safety.
• if the user wants to preview a command first: use --dry-run with any operation. the helper prints the security invocation with secrets redacted and exits without modifying the keychain.
• if supplying the password from a shell variable: use --password-env VAR instead of --password. the helper reads the var and unsets it immediately, preventing the secret from remaining in the environment. do not use --password VALUE in production; it leaves the secret in shell history and process listings.
• if targeting a specific keychain file: use --keychain /path/to/keychain. the helper operates on the default search list if not specified. if the keychain is locked, the system prompts for the unlock password.
• if the keychain is locked: the security CLI will prompt for the keychain password. if running non-interactively and the keychain is locked, the operation will fail. pre-unlock the keychain or use an unlocked keychain.
• if no matching credential is found in get or delete: the helper exits with status 1 and reports "credential not found". do not attempt to delete or get a non-existent entry without checking list first if certainty is required.
• if the result set from list is empty: the helper prints "no matching entries found." and exits with status 0. this is not an error; it means the filters matched no credentials.
• if service or account contains special characters or spaces: quote the value when passing it as a shell argument. the helper accepts any string; security does the escaping internally.

output contract

• list: stdout prints one line per matching entry in the format "service | account | label" or "no matching entries found.". exit status 0. if --dry-run, prints the security dump-keychain command instead of executing it.
• get: stdout prints password (masked or raw depending on flag) and metadata block (keychain path, version, class, attributes). exit status 0 on success, 1 if credential not found. if --dry-run, prints the security find-generic-password command and exits without executing it.
• set: stdout prints "stored credential for 'SERVICE' / 'ACCOUNT'." if successful. if overwriting an existing credential and --yes is not set, prompts the user for confirmation before proceeding. exit status 0 on success, 1 if the operation is cancelled or fails. if --dry-run, prints the redacted security add-generic-password command and exits without touching the keychain.
• delete: stdout prints "deleted credential for 'SERVICE' / 'ACCOUNT'." if successful. prompts for confirmation before deletion unless --yes is provided. exit status 0 on success, 1 if the credential does not exist, the user cancels the prompt, or the operation fails. if --dry-run, prints the security delete-generic-password command and exits without touching the keychain.

outcome signal

• list succeeds: user sees the matching credentials listed by service and account, or receives "no matching entries found." if no results match.
• get succeeds: user sees the password (masked or revealed) and metadata, confirming the credential exists in the keychain.
• set succeeds: user sees "stored credential..." message and can immediately verify the entry with get or list --service X --account Y.
• delete succeeds: user sees "deleted credential..." message. running get or list on that service/account afterward should return no results.
• dry-run succeeds: user sees the security command that would be executed (with secrets redacted) without any side effects on the keychain.
• operation fails or is cancelled: the helper exits with status 1 and prints an error message describing the reason (e.g., "credential not found", "operation cancelled", "authentication failed"). the keychain remains unchanged if the operation was destructive.

testing transcript (safe context)

# prepare a disposable keychain (password = testpass123)
security create-keychain -p testpass123 /tmp/keychain-access-test.keychain
security unlock-keychain -p testpass123 /tmp/keychain-access-test.keychain

# 1) list entries (empty keychain)
./skills/keychain-access/keychain-access.sh list \
  --keychain /tmp/keychain-access-test.keychain
# output:
# No matching entries found.

# 2) set a credential (with --yes to skip confirmation)
printf 'super-secret-token-xyz' | ./skills/keychain-access/keychain-access.sh set \
  --service test-service --account test-user \
  --password-stdin --keychain /tmp/keychain-access-test.keychain --yes
# output:
# Stored credential for 'test-service' / 'test-user'.

# 3) get the credential (masked by default)
./skills/keychain-access/keychain-access.sh get \
  --service test-service --account test-user \
  --keychain /tmp/keychain-access-test.keychain
# output:
# password: (masked)
# keychain: "/private/tmp/keychain-access-test.keychain"
# version: 256
# class: "genp"
# attributes: ...

# 4) get the credential (raw, secret revealed)
./skills/keychain-access/keychain-access.sh get \
  --service test-service --account test-user \
  --keychain /tmp/keychain-access-test.keychain --raw
# output:
# password: "super-secret-token-xyz"
# keychain: "/private/tmp/keychain-access-test.keychain"
# version: 256
# class: "genp"
# attributes: ...

# 5) preview a delete command without executing
./skills/keychain-access/keychain-access.sh delete \
  --service test-service --account test-user \
  --keychain /tmp/keychain-access-test.keychain --dry-run
# output:
# security delete-generic-password -s 'test-service' -a 'test-user' /tmp/keychain-access-test.keychain

# 6) delete the credential (with --yes to skip confirmation)
./skills/keychain-access/keychain-access.sh delete \
  --service test-service --account test-user \
  --keychain /tmp/keychain-access-test.keychain --yes
# output:
# Deleted credential for 'test-service' / 'test-user'.

# 7) verify deletion
./skills/keychain-access/keychain-access.sh get \
  --service test-service --account test-user \
  --keychain /tmp/keychain-access-test.keychain
# output:
# credential not found.
# (exit status 1)

# cleanup
security delete-keychain /tmp/keychain-access-test.keychain

include this transcript in reports so the calling agent knows the commands and expected output shapes.

credits: original skill authored for clawhub. enriched and standardized for Implexa.