cli-tool-secrets

<source_of_truth> The canonical helper is:

<cli-tools-root>/_repo/_secret-manager/secrets.sh

It is backed by the macOS Keychain service namespace cli-tools. The default Keychain file is ~/.local/share/cli-tools/cli-tools.keychain-db, alongside the CLI-tools user profile directories.

For full lifecycle policy, read <cli-tools-root>/_repo/skills/cli-tool/references/secrets.md. If the task is broader CLI creation, update, testing, or auth implementation, also load the repo-owned cli-tool skill and follow its agent-routing rules. </source_of_truth>

Do not use it for CourseCraft, generic project automation, non-CLI workflows, or service runtime state owned by a CLI's auth system.

<quick_start>

1. Choose the CLI tool name and the secret type. The canonical naming schema is <cli-tool>-<type>, where both parts are lowercase hyphenated strings and <cli-tool> is the CLI command name.
2. Check for an existing name before asking Adam for a credential:

   <cli-tools-root>/_repo/_secret-manager/secrets.sh list
   <cli-tools-root>/_repo/_secret-manager/secrets.sh has <name>
   

   When a missing secret is an expected diagnostic result, shape has so the non-zero status is consumed and reported explicitly:

   if output="$(<cli-tools-root>/_repo/_secret-manager/secrets.sh has <name> 2>&1)"; then
     printf 'SECRET_PRESENT:%s\n' '<name>'
   else
     rc=$?
     if [ "$rc" -eq 1 ]; then
       printf 'EXPECTED_MISSING_SECRET:%s\n' '<name>'
       exit 0
     fi
     printf '%s\n' "$output" >&2
     exit "$rc"
   fi
   

3. If the secret exists, retrieve it with get <name> and use it without printing the value.
4. Ask Adam only for missing reusable credentials.
5. Store new values immediately through stdin or SECRET_VALUE, not inline in command examples or .env files:

   printf '%s' "$SECRET_VALUE" | <cli-tools-root>/_repo/_secret-manager/secrets.sh set --tool <cli-tool> --type <type>
   SECRET_VALUE="$SECRET_VALUE" <cli-tools-root>/_repo/_secret-manager/secrets.sh set --tool <cli-tool> --type <type>
   

6. Verify storage with has <name>. Do not verify by echoing the secret value. </quick_start>

Remote host form:

<cli-tools-root>/_repo/_secret-manager/secrets.sh --remote-host <host> <command> [args]

For set, prefer stdin or SECRET_VALUE so the secret does not appear in shell history. Remote set copies the value through a private temporary file on the remote host.

Never store or document reusable credentials in repo-local .env files, profile .env files, .env.example, source files, final answers, screenshots, logs, or general instructions.